⚠️ Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.
Listbox is only available in the React API for SWAN.
For a better mobile experience, use Dropdown when the list contains simple text choices. Use Listbox only if you require images, sections, or other styling inside the choices.
A BasicListbox is a simple-to-use convenience component that handles most typical use cases of a Listbox.
It takes a set of ListboxOption components as children:
ListboxOption must have a key prop holding that option's value.label prop for each ListboxOption. This feature allows you to display specific content or have callouts in the Listbox's button element when an option is selected.Inside each ListboxOption you can put any HTML content, including bold text, colored text, Callouts, etc. When using HTML or JSX inside a ListboxOption, include a textValue prop whose value is an accessible label for the option.
BasicListbox also needs an accessible label: either an aria-labelledby prop whose value is the id of the element on the page that labels the Listbox, or an aria-label prop whose value is localized text for the label.
The preview has been updated.
Use a full Listbox for more advanced features, like for instance, an inner or floating label.
You will need to include some sub-components that BasicListbox takes care of for you.
The preview has been updated.
⚠️ size is deprecated in SWAN v3.3
The component now automatically handles sizing based on the selected mode(standardMode/compactMode). Please update your implementation to rely on the new mode-based sizing.
Use size="mini" to reduce the height of a Listbox. Use also the "mini" size for components that should play a supporting role in the layout, ensuring a clear visual hierarchy. This size works well in situations where there are limitations on vertical space.
The preview has been updated.
Use fullWidth to grow a Listbox to fill it's container.
The preview has been updated.
Use labelPrefix to display a "prefix" on the left and the selected value on the right.
Note that the BasicListbox convenience component cannot be used for this purpose.
The preview has been updated.
Use the placeholder property if you want to show a text when no options are selected.
The preview has been updated.
Use ListboxWithFloatingLabel to move the label inside the input above the selection. This creates visual harmony with other form elements like text inputs that support floating labels. Keep label text short or use the fullWidth prop to maximize width.
The preview has been updated.
Use ListboxOptionThumbnailContainer, which contains a square FluidImage, to display square thumbnail images in selections.
The preview has been updated.
Use ListboxSection to display a section title to wrap a group of selections. Each ListboxSection requires a title and a key prop.
The preview has been updated.
Use Callout size="mini" when adding a Callout to a ListboxOption. Specify the content of the Callout in the ListboxOption's label field, using brackets to display it next to the selected option, as in 《New!》.
The preview has been updated.
By default, the Listbox displays the first option in the button, but doesn't select it until the user clicks an option: this is to mirror the behavior of an HTML select tag. To preselect an option in the Listbox, use the value prop.
The preview has been updated.
Use disabled or disabledKeys to display a disabled state.
The preview has been updated.
You can use any core prop from SWAN or enclose any SWAN component to create your custom Listbox Option. A very peculiar use case of this across Vista is showing Quantity and Pricing in conjunction, which can be achieved using the FlexBox component as below.
The preview has been updated.
As is the case with most form elements, folks often want to "control" this component. Controlling a component means that you take ownership over its state rather than letting the browser manage the state for you. When you control a component, you own the source of truth for the UI. This means that you don't need to query the DOM in order to determine the current value of the element. So, when it comes time to use the value of the element somewhere else (e.g. submitting the selection to a back-end service) you can trust your stored value.
To control a Listbox, store the selected value (e.g., in React state or a Redux store) and provide a handler to update this value when users interact with the component.
The preview has been updated.
If you don't need to manage the state of the Listbox, you can omit the selectedKeys and onSelectionChange props, allowing the browser to handle the state. Consider using the value prop to specify the initial selected value.
Use the Dynamics Collections API with a render function as the child of ListboxList for better performance with large or dynamic data.
To use the API, pass an array into the items prop of the Listbox. Be sure to keep the items reference stable, by storing it in state or using useMemo, when the data isn’t changing.
The preview has been updated.
Every Listbox requires an aria-labelledby prop with a value representing the id of the labeling element, even if it has an "inner label." This labeling element can be visually hidden if not intended for display on screens.
Alternatively, you can use the aria-label attribute on ListboxButton in Listbox or directly on BasicListbox in the convenience component.
A Listbox containing numerous options or only a few can be overwhelming, difficult to navigate, and may introduce unnecessary challenges by concealing information that could be easily visible.
The Listbox prioritizes usability through generous padding and a large font, resulting in a minimum width determined by the widest option within the Listbox.
<div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.| prop | type | required | description | default |
|---|---|---|---|---|
| size | "standard" | "mini" | false | ⚠️ Deprecated - This is deprecated without a replacement.
The size (height) of the Listbox.
One of: "standard", "mini". | null |
| skin | "standard" | "error" | false | The visual style of the Listbox.
One of: "standard", "error".
The visual style of the Listbox.
One of: "standard", "error". | null |
| fullWidth | boolean | false | Whether or not the Listbox should expand to fill the entire width of its container. | null |
| disabled | boolean | false | Whether or not the Listbox is disabled. | null |
| selectionMode | "multiple" | "single" | false | The selection mode of the Listbox.
One of: "single", "multiple". | null |
| selectedKeys | "all" | Set<string | number> | false | The keys of the selected items in the Listbox. | null |
| disabledKeys | Set<string | number> | false | The keys of the disabled items in the Listbox. | null |
| onSelectionChange | ((selectedKeys: ListboxSelectedValues) => void) | false | Callback function that gets triggered when the selection changes. | null |
| value | string | null | false | The value of the selected item in single selection mode (for backward compatibility). | null |
| onChange | ((value: string) => void) | false | Callback function that gets triggered when the value changes (for backward compatibility). | null |
| items | Iterable<any> | false | Optional collection of dynamic options. Use with a render function as a child of ListboxList/ComboboxList | null |
| inModal | boolean | null | false | Set to "true" if the Basic Listbox is rendering inside a Modal. | false |
<div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.| prop | type | required | description | default |
|---|---|---|---|---|
| size | "standard" | "mini" | false | ⚠️ Deprecated - This is deprecated without a replacement.
The size (height) of the Listbox.
One of: "standard", "mini". | null |
| skin | "standard" | "error" | false | The visual style of the Listbox.
One of: "standard", "error".
The visual style of the Listbox.
One of: "standard", "error". | null |
| fullWidth | boolean | false | Whether or not the Listbox should expand to fill the entire width of its container. | null |
| disabled | boolean | false | Whether or not the Listbox is disabled. | null |
| selectionMode | "multiple" | "single" | false | The selection mode of the Listbox.
One of: "single", "multiple". | single |
| selectedKeys | "all" | Set<string | number> | false | The keys of the selected items in the Listbox. | null |
| disabledKeys | Set<string | number> | false | The keys of the disabled items in the Listbox. | null |
| onSelectionChange | ((selectedKeys: ListboxSelectedValues) => void) | false | Callback function that gets triggered when the selection changes. | null |
| value | string | null | false | The value of the selected item in single selection mode (for backward compatibility). | null |
| onChange | ((value: string) => void) | false | Callback function that gets triggered when the value changes (for backward compatibility). | null |
| items | Iterable<any> | false | Optional collection of dynamic options. Use with a render function as a child of ListboxList/ComboboxList | null |
<button /> as the root element. You can utilize the native attributes supported by <button /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.| prop | type | required | description | default |
|---|---|---|---|---|
| placeholder | ReactNodeLike | false | Placeholder Text to display when no item is selected, instead of the first item. | null |
| labelPrefix | ReactNodeLike | false | Content to be displayed before the selected items. | null |
<ul /> as the root element. You can utilize the native attributes supported by <ul /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.<li /> as the root element. You can utilize the native attributes supported by <li /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.| prop | type | required | description | default |
|---|---|---|---|---|
| label | ReactNodeLike | false | The contents to render inside the ListboxButton. Can include JSX | null |
| disabled | boolean | null | false | Whether or not the option is disabled. | null |
| textValue | string | null | false | The option's human-readable string. Required if using JSX inside of an option | null |
| withThumbnail | boolean | null | false | Whether or not the option has a thumbnail. | null |
<label /> as the root element. You can utilize the native attributes supported by <label /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.<div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.| prop | type | required | description | default |
|---|---|---|---|---|
| fullWidth | boolean | null | false | - | null |
<div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.| prop | type | required | description | default |
|---|---|---|---|---|
| children | ReactNode | false | The content to be displayed within the popover. | null |
| placement | Placement | false | The placement of the popover. eg: "bottom start", "top end", "top", "bottom" | bottom start |
| offset | number | false | The offset distance from the trigger element. | null |
| isNonModal | boolean | false | Specifies whether the popover is used in a non-modal context. | null |
| hideArrow | boolean | false | Specifies whether to hide the arrow of the popover. | true |
| fullBleed | boolean | false | Specifies whether the popover should take up the full available width. | null |
| labelText | string | false | The label text for accessibility. | null |
| portalContainer | Element | false | The container for the portal where the popover is rendered. | null |
| inModal | boolean | null | false | Set to "true" if the Listbox Popover is rendering inside a Modal. | null |
<div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.<div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.<section /> as the root element. You can utilize the native attributes supported by <section /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
