SelectorList

Components/Lists

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/selectorlist

Overview

Copy

Selector lists allow users to select one or multiple items within a data set. They have built-in search and loading behaviors.

Do

  • Use when users can select one or multiple items in data sets.
  • Use when there's a long list of items and searching is helpful.
  • Use inside parent containers such as a <CustomModalLayout/>.

Don't

  • Don't use them for lists that can be edited by users. Use <EditableSelector/> instead.
  • Don't use them for data sets that need to be displayed in rows and columns. Use <Table/> instead.

Feature examples

Type

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.
Copy

Item structure

Add more elements to the list items with the following props:

  • image
  • title (required)
  • subtitle

To 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.
Copy

Size

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"
Copy

Image shape

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.
Copy

Image size

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.

Copy

Height

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.

Copy

Disabled item

Mark a list item as unavailable for selection with the disabled prop.

The item will still be displayed in the list and search results.

Copy

Subtitle

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.

Copy

The selector list has a search input field by default. Control its visibility using withSearch prop.

Change the search placeholder value with searchPlaceholder prop.

Copy

Select or deselect all

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.

Copy

Below node

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.

Copy

No items empty state

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.

Copy

No search results empty state

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.

Copy

Developer examples

Number of items to load

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.

Copy

Common use case examples

Single selection

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.

Copy

Multiple 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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
autoFocusboolean—Focus the element on mount (standard React input autoFocus).
childrenSelectorListRenderProp—Accepts a render function that receives renderList, renderToggleAllCheckbox and selectedItems, and returns the content to render. Without it, only the list is rendered.
dataHookstring—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 }>
deselectAllTextstring'Deselect all'Sets the label for the checkbox which allows to deselect all selected items.
emptyStateReactNode—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.
heightstring'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.
initialAmountToLoadnumber—Sets the number of items to load on initial render or after search. If not defined, it equals the itemsPerPage value.
itemsPerPagenumber50Sets the number of items to be loaded each time users scroll down to the end of the list.
maxHeightstring'100%'Sets the maximum height of the component in % or px.
multiplebooleanfalseRenders 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.
searchDebounceMsnumber—Sets search debounce in milliseconds.
searchMaxLengthnumber—Sets the maximum number of characters allowed in the search input.
searchPlaceholderstring'Search...'Defines placeholder value shown in the search input.
selectAllTextstring'Select all'Sets the label for the checkbox which allows to select all items.
showDividerbooleanfalseUse to display a divider between items.
size"small" | "medium"'medium'Controls the size of component paddings and list items.
subtitleReactNode—Contains text or other component in a fixed position at the top of the list.
withSearchbooleantrueControls whether to display the search input.

Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

Changelog

  • 1.345.0 — fix: tabbing into the list no longer replaces an existing selection or calls onSelect; keyboard focus now lands on the selected item. (#17669)
  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.2 (2026-09-29) — fix: items span the full width and height of the list again, removing the 6px inset added in 1.323.0. (#17279) — has visual changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.326.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.308.0 (2026-08-04) — fix: don't activate the first item when clicking an item's checkbox (#16722)
  • 1.307.0 (2026-08-03) — fix: item hover, pressed, and keyboard-focus backgrounds are neutral grey instead of blue in Harmony (odeditor) and Studio 2.0 (odeditor-dark). (#16704) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.257.0 (2026-02-19) — feat: expose maxLength prop for search input (#15928)
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.251.0 (2026-01-28) — feat: implementing proper keyboard navigation for accessibility (#15785)
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.220.0 (2025-09-29) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.203.0 (2025-07-01) — feat: add autoFocus prop (#15027)
  • 1.197.0 (2025-06-06) — maintenance release, no component-specific changes
  • 1.190.0 (2025-05-22) — maintenance release, no component-specific changes
  • 1.186.0 (2025-05-05) — maintenance release, no component-specific changes
  • 1.185.0 (2025-04-30) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.104.1 (2024-05-14) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?