Components/Lists
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/selectorlist
Selector lists allow users to select one or multiple items within a data set. They have built-in search and loading behaviors.
<CustomModalLayout/>.<EditableSelector/> instead.<Table/> instead.Control the type of selection users can make with the multiple prop:
false allows users to select a single item only.true allows users to select multiple items.Add more elements to the list items with the following props:
imagetitle (required)subtitleTo add additional text or other components to items, use container props.
subtitleNode shows content below the item subtitle.extraNode shows content at the end of an item.size controls the visual size of each SelectorList row (including selector control and spacing), so you can choose a denser or more spacious list style.
"small""medium"Control shape of the images with the imageShape prop:
rectangularis the default that's used for all common cases.circle is for images that show users or user initials.Change the size of the images with imageSize props:
tiny is for especially dense layouts.small is for dense layouts.large is the default for all common cases.portrait should be used to present images vertically.cinema should be used to present images horizontally.Note: Only use a rectangular image when the size is portrait or cinema.
Control the height of the selector list with these props:
height changes the component's height in pixels or percentage.maxHeight sets the component's max height in pixels or percentage.By default, the component fills in 100% of its parent container. If the selector list is longer than height or maxHeight , a vertical scrollbar appears.
Mark a list item as unavailable for selection with the disabled prop.
The item will still be displayed in the list and search results.
Add any component inside a subtitle container above the search input. Together with search input, they will stick to the top when users scroll the list.
Use this container to add text, a heading or filter to selector list items.
The selector list has a search input field by default. Control its visibility using withSearch prop.
Change the search placeholder value with searchPlaceholder prop.
Allow users to select all items at once by adding a "Select all" checkbox below the list.
When the selector list is inside a <CustomModalLayout/>, add the checkbox to its footer sideActions container using the renderToggleAllCheckbox function.
Customize checkbox labels with the properties selectAllText and deselectAllText.
Note: Make sure the "Select all" checkbox is aligned with the list checkboxes by wrapping renderToggleAllCheckbox function to the <Box/> with 6 px left padding.
Add text or any other component to the container below each item using the belowNode prop, which shows once an item is selected. Be sure to set the showBelowNodeOnSelect property to true.
Use emptyState prop to display the <EmptyState/> component in the section theme when there are no items show.
Make sure the illustration reflects the type of items the list should contain.
Provide an empty state when users look for content via search query and no items match their criteria using the renderNoResults function and the <EmptyState/> in the section theme.
Control the number of items that load with two properties:
initialAmountToLoad is the number of items loaded after a search.itemsPerPage is the number of items that load each consecutive time a user scrolls down to the end of the list. The default is 50.If not specified, initialAmountToLoad will be the same as itemsPerPage.
Use the selector list to load and display a set of items.
If the anticipated number of items is small, hide the default search input field.
Use the subtitle, subtitleNode or extraNode containers to explain why an item is unavailable for selection.
Use the selector list to search and select multiple items.
Allow users to select and deselect all items at once using the renderToggleAllCheckbox function.
| Name | Type | Default | Description |
|---|---|---|---|
autoFocus | boolean | — | Focus the element on mount (standard React input autoFocus). |
children | SelectorListRenderProp | — | Accepts a render function that receives renderList, renderToggleAllCheckbox and selectedItems, and returns the content to render. Without it, only the list is rendered. |
dataHook | string | — | Applies a data-hook HTML attribute to be used in the tests. |
dataSource (required) | SelectorListDatasourceFn | — | Returns data source for the list described in a following structure: typescript (searchQuery: string, offset: number, limit: number) => Promise<{ items: Array<{ id: number | string, // sets the unique item ID (required) title: node, defines // an item's title (required) subtitle?: string, // defines an item's subtitle extraText?: string, // contains any text at the end of an item extraNode?: node, // contains any component at the end of an item disabled?: boolean, // controls if an item is disabled for selection or not selected?: boolean, // sets an item as selected indeterminate?: boolean, // sets an item as indeterminate image?: node, // contains <Image/> or other component to illustrate an item subtitleNode?: node, // contains any component below an item's subtitle belowNode?: node, // contains any component below the item, to be shown after an item is selected showBelowNodeOnSelect?: boolean, // allows to show belowNode content when an item is selected }>, offset: number, // specifies the item index in the data source to start fetching from<br> limit: number, // sets a max amount of items to load from the data source<br> totalCount: number, // sets a max amount of items to load from the data source on user's search query }> |
deselectAllText | string | 'Deselect all' | Sets the label for the checkbox which allows to deselect all selected items. |
emptyState | ReactNode | — | Contains a component which is shown when there are no items to display in the selector list. i.e. empty {items:[], totalCount: 0} was returned on the first call to dataSource. Render <EmptyState/> component in section skin for this purpose. |
height | string | '100%' | Sets the height of the component in % or px. |
imageShape | "circle" | "rectangular" | 'rectangular' | Controls the shape of item images. |
imageSize | "small" | "tiny" | "large" | "portrait" | "cinema" | — | Controls the size of item images. Note: portrait and cinema sizes are only compatible with rectangular image shape. |
initialAmountToLoad | number | — | Sets the number of items to load on initial render or after search. If not defined, it equals the itemsPerPage value. |
itemsPerPage | number | 50 | Sets the number of items to be loaded each time users scroll down to the end of the list. |
maxHeight | string | '100%' | Sets the maximum height of the component in % or px. |
multiple | boolean | false | Renders checkboxes instead of radio buttons and allows users to select multiple items. |
onSelect | (item: SelectorListItem) => void | — | Defines callback that triggers on select and return selected item object. |
renderNoResults | (searchValue: string) => ReactNode | — | Defines a function that gets the current searchQuery and returns the component that is shown when no items are found. Render <EmptyState /> component in section skin for this purpose. |
searchDebounceMs | number | — | Sets search debounce in milliseconds. |
searchMaxLength | number | — | Sets the maximum number of characters allowed in the search input. |
searchPlaceholder | string | 'Search...' | Defines placeholder value shown in the search input. |
selectAllText | string | 'Select all' | Sets the label for the checkbox which allows to select all items. |
showDivider | boolean | false | Use to display a divider between items. |
size | "small" | "medium" | 'medium' | Controls the size of component paddings and list items. |
subtitle | ReactNode | — | Contains text or other component in a fixed position at the top of the list. |
withSearch | boolean | true | Controls whether to display the search input. |
No testkit for this component — it doesn't expose a unidriver testkit.
onSelect; keyboard focus now lands on the selected item. (#17669)autoFocus prop (#15027)Last updated: 30 October 2026