> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: SelectorList Component

## Article: SelectorList Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/lists/selector-list-component.md

## Article Content:

# SelectorList

_Components/Lists_

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

## Overview

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `French toast`,
          extraNode: <Text secondary>$10</Text>,
          image: <Image width="100%" height="100%" src="FoodExample1.jpg" />,
        },
        {
          id: 1,
          title: `Pasta with mushrooms`,
          extraNode: <Text secondary>$15</Text>,
          image: <Image width="100%" height="100%" src="FoodExample2.jpg" />,
        },
        {
          id: 3,
          title: `Seafood paella`,
          extraNode: <Text secondary>$20</Text>,
          image: <Image width="100%" height="100%" src="FoodExample3.jpg" />,
        },
        {
          id: 4,
          title: `Toast with eggs`,
          extraNode: <Text secondary>$10</Text>,
          image: <Image width="100%" height="100%" src="FoodExample4.jpg" />,
        },
        {
          id: 5,
          title: `Pumpkin soup`,
          extraNode: <Text secondary>$8</Text>,
          image: <Image width="100%" height="100%" src="FoodExample5.jpg" />,
        },
        {
          id: 6,
          title: `Salmon with vegetables`,
          extraNode: <Text secondary>$17</Text>,
          image: <Image width="100%" height="100%" src="FoodExample6.jpg" />,
        },
        {
          id: 7,
          title: `Breakfast berry toast`,
          extraNode: <Text secondary>$8</Text>,
          image: <Image width="100%" height="100%" src="FoodExample1.jpg" />,
        },
        {
          id: 8,
          title: `Pesto pasta`,
          extraNode: <Text secondary>$12</Text>,
          image: <Image width="100%" height="100%" src="FoodExample2.jpg" />,
        },
        {
          id: 9,
          title: `Vegan paella`,
          extraNode: <Text secondary>$18</Text>,
          image: <Image width="100%" height="100%" src="FoodExample3.jpg" />,
        },
        {
          id: 10,
          title: `Egg wrap`,
          extraNode: <Text secondary>$9</Text>,
          image: <Image width="100%" height="100%" src="FoodExample4.jpg" />,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return (
    <Box align="center">
      <SelectorList
        itemsPerPage={10}
        dataSource={data}
        imageSize="small"
        multiple
      >
        {({ renderList, renderToggleAllCheckbox, selectedItems }) => (
          <CustomModalLayout
            width="600px"
            height="480px"
            title="Import dishes"
            primaryButtonText="Import"
            secondaryButtonText="Cancel"
            onCloseButtonClick={() => {}}
            removeContentPadding
            showFooterDivider
            showHeaderDivider
            sideActions=<Box paddingLeft="1">{renderToggleAllCheckbox()}</Box>
          >
            {renderList()}
          </CustomModalLayout>
        )}
      </SelectorList>
    </Box>
  );
};
```

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.

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
        },
        {
          id: 1,
          title: `Item`,
        },
        {
          id: 2,
          title: `Item`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return (
    <StorybookComponents.Stack flexDirection="column">
      <SelectorList dataSource={data} />
      <SelectorList dataSource={data} multiple />
    </StorybookComponents.Stack>
  );
};
```

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

```jsx
() => {
  const plainData = [
    {
      id: 0,
      title: `Title`,
    },
    {
      id: 1,
      title: `Title`,
    },
    {
      id: 2,
      title: `Title`,
    },
  ];

  const dataWithImage = [
    {
      id: 0,
      title: `Title`,
      subtitle: 'Subtitle',
      extraNode: (
        <StorybookComponents.Placeholder>
          Extra node
        </StorybookComponents.Placeholder>
      ),
      image: <Image width="100%" height="100%" />,
      subtitleNode: (
        <StorybookComponents.Placeholder>
          Subtitle node
        </StorybookComponents.Placeholder>
      ),
    },
    {
      id: 1,
      title: `Title`,
      subtitle: 'Subtitle',
      extraNode: (
        <StorybookComponents.Placeholder>
          Extra node
        </StorybookComponents.Placeholder>
      ),
      image: <Image width="100%" height="100%" />,
      subtitleNode: (
        <StorybookComponents.Placeholder>
          Subtitle node
        </StorybookComponents.Placeholder>
      ),
    },
    {
      id: 2,
      title: `Title`,
      subtitle: 'Subtitle',
      extraNode: (
        <StorybookComponents.Placeholder>
          Extra node
        </StorybookComponents.Placeholder>
      ),
      image: <Image width="100%" height="100%" />,
      subtitleNode: (
        <StorybookComponents.Placeholder>
          Subtitle node
        </StorybookComponents.Placeholder>
      ),
    },
  ];

  const dataWithNode = [
    {
      id: 0,
      title: `Coffee shop 1`,
      subtitle: 'Main street 1',
      extraNode: <Text secondary>2 tables available</Text>,
      image: <Image width="100%" height="100%" src="FoodExample4.jpg" />,
      subtitleNode: (
        <Box direction="horizontal" gap="1" paddingTop="SP1" color="D30">
          <Tooltip content="Table seating">
            <Icons.TableReservationSmall />
          </Tooltip>
          <Tooltip content="Bar">
            <Icons.BarSmall />
          </Tooltip>
        </Box>
      ),
    },
    {
      id: 1,
      title: `Coffee shop 2`,
      subtitle: 'Main street 2',
      extraNode: <Text secondary>7 tables available</Text>,
      image: <Image width="100%" height="100%" src="FoodExample1.jpg" />,
      subtitleNode: (
        <Box direction="horizontal" gap="1" paddingTop="SP1" color="D30">
          <Tooltip content="Table seating">
            <Icons.TableReservationSmall />
          </Tooltip>
        </Box>
      ),
    },
    {
      id: 2,
      title: `Coffee shop 3`,
      subtitle: 'Main street 2',
      extraNode: <Text secondary>1 table available</Text>,
      image: <Image width="100%" height="100%" src="FoodExample5.jpg" />,
      subtitleNode: (
        <Box direction="horizontal" gap="1" paddingTop="SP1" color="D30">
          <Tooltip content="Table seating">
            <Icons.TableReservationSmall />
          </Tooltip>
          <Tooltip content="Bar">
            <Icons.BarSmall />
          </Tooltip>
        </Box>
      ),
    },
  ];

  const getDataSource = (data) => (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const filtered = data.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return (
    <StorybookComponents.Stack flexDirection="column">
      <SelectorList dataSource={getDataSource(plainData)} />
      <SelectorList dataSource={getDataSource(dataWithImage)} />
      <SelectorList dataSource={getDataSource(dataWithNode)} />
    </StorybookComponents.Stack>
  );
};
```

#### 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"`

```jsx
() => {
  const items = [
    { id: 1, title: 'Dashboard' },
    { id: 2, title: 'Storefront' },
    { id: 3, title: 'Bookings' },
    { id: 4, title: 'Blog' },
    { id: 5, title: 'Analytics' },
  ];

  const createDataSource = () => async (searchQuery, offset, limit) => {
    const normalizedQuery = (searchQuery || '').toLowerCase();

    const filteredItems = items.filter((item) =>
      String(item.title).toLowerCase().includes(normalizedQuery),
    );

    return {
      items: filteredItems.slice(offset, offset + limit),
      totalCount: filteredItems.length,
    };
  };

  return (
    <Box gap="20px" direction="vertical">
      <SelectorList
        size="small"
        withSearch
        maxHeight="220px"
        dataSource={createDataSource()}
      />

      <SelectorList
        size="medium"
        withSearch
        maxHeight="220px"
        dataSource={createDataSource()}
      />
    </Box>
  );
};
```

#### Image shape

Control shape of the images with the `imageShape` prop:

- `rectangular`is the default that's used for all common cases.
- `circle` is for images that show users or user initials.

```jsx
() => {
  const rectangularData = [
    {
      id: 0,
      title: `Rectangular (default)`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 1,
      title: `Rectangular (default)`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 2,
      title: `Rectangular (default)`,
      image: <Image width="100%" height="100%" />,
    },
  ];

  const circleData = [
    {
      id: 0,
      title: `Circle`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 1,
      title: `Circle`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 2,
      title: `Circle`,
      image: <Image width="100%" height="100%" />,
    },
  ];

  const getDataSource = (data) => (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const filtered = data.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return (
    <StorybookComponents.Stack flexDirection="column">
      <SelectorList dataSource={getDataSource(rectangularData)} />
      <SelectorList
        dataSource={getDataSource(circleData)}
        imageShape="circle"
      />
    </StorybookComponents.Stack>
  );
};
```

#### 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`.

```jsx
() => {
  const tinyImageData = [
    {
      id: 0,
      title: `Tiny`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 1,
      title: `Tiny`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 2,
      title: `Tiny`,
      image: <Image width="100%" height="100%" />,
    },
  ];

  const smallImageData = [
    {
      id: 0,
      title: `Small`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 1,
      title: `Small`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 2,
      title: `Small`,
      image: <Image width="100%" height="100%" />,
    },
  ];

  const largeImageData = [
    {
      id: 0,
      title: `Large (default)`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 1,
      title: `Large (default)`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 2,
      title: `Large (default)`,
      image: <Image width="100%" height="100%" />,
    },
  ];

  const portraitImageData = [
    {
      id: 0,
      title: `Portrait`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 1,
      title: `Portrait`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 2,
      title: `Portrait`,
      image: <Image width="100%" height="100%" />,
    },
  ];

  const cinemaImageData = [
    {
      id: 0,
      title: `Cinema`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 1,
      title: `Cinema`,
      image: <Image width="100%" height="100%" />,
    },
    {
      id: 2,
      title: `Cinema`,
      image: <Image width="100%" height="100%" />,
    },
  ];

  const getDataSource = (data) => (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const filtered = data.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return (
    <StorybookComponents.Stack flexDirection="column">
      <SelectorList
        dataSource={getDataSource(tinyImageData)}
        imageSize="tiny"
      />
      <SelectorList
        dataSource={getDataSource(smallImageData)}
        imageSize="small"
      />
      <SelectorList
        dataSource={getDataSource(largeImageData)}
        imageSize="large"
      />
      <SelectorList
        dataSource={getDataSource(portraitImageData)}
        imageSize="portrait"
      />
      <SelectorList
        dataSource={getDataSource(cinemaImageData)}
        imageSize="cinema"
      />
    </StorybookComponents.Stack>
  );
};
```

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

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
        },
        {
          id: 1,
          title: `Item`,
        },
        {
          id: 3,
          title: `Item`,
        },
        {
          id: 4,
          title: `Item`,
        },
        {
          id: 5,
          title: `Item`,
        },
        {
          id: 6,
          title: `Item`,
        },
        {
          id: 7,
          title: `Item`,
        },
        {
          id: 8,
          title: `Item`,
        },
        {
          id: 9,
          title: `Item`,
        },
        {
          id: 10,
          title: `Item`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return (
    <StorybookComponents.Stack flexDirection="line">
      <SelectorList dataSource={data} height="240px"></SelectorList>
      <SelectorList dataSource={data} maxHeight="360px"></SelectorList>
    </StorybookComponents.Stack>
  );
};
```

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

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
        },
        {
          id: 1,
          title: `Disabled item`,
          disabled: true,
        },
        {
          id: 2,
          title: `Item`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return <SelectorList dataSource={data} />;
};
```

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

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
        },
        {
          id: 1,
          title: `Item`,
        },
        {
          id: 2,
          title: `Item`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return (
    <SelectorList
      dataSource={data}
      subtitle=<StorybookComponents.Placeholder>
        Subtitle
      </StorybookComponents.Placeholder>
    />
  );
};
```

#### Search

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

Change the search placeholder value with `searchPlaceholder` prop.

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
        },
        {
          id: 1,
          title: `Item`,
        },
        {
          id: 2,
          title: `Item`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return (
    <StorybookComponents.Stack flexDirection="column">
      <SelectorList dataSource={data} withSearch={false} />
      <SelectorList dataSource={data} searchPlaceholder="Custom placeholder" />
    </StorybookComponents.Stack>
  );
};
```

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

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
        },
        {
          id: 1,
          title: `Item`,
        },
        {
          id: 2,
          title: `Item`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return (
    <StorybookComponents.Stack flexDirection="column">
      <SelectorList dataSource={data} multiple>
        {({ renderList, renderToggleAllCheckbox, selectedItems }) => (
          <CustomModalLayout
            title="Import items"
            primaryButtonText="Import"
            secondaryButtonText="Cancel"
            onCloseButtonClick={() => {}}
            removeContentPadding
            showFooterDivider
            showHeaderDivider
            sideActions=<Box paddingLeft="1">{renderToggleAllCheckbox()}</Box>
          >
            {renderList()}
          </CustomModalLayout>
        )}
      </SelectorList>
      <SelectorList
        dataSource={data}
        multiple
        selectAllText="Select all"
        deselectAllText="Deselect all from importing"
      >
        {({ renderList, renderToggleAllCheckbox, selectedItems }) => (
          <CustomModalLayout
            title="Import items"
            primaryButtonText="Import"
            secondaryButtonText="Cancel"
            onCloseButtonClick={() => {}}
            removeContentPadding
            showFooterDivider
            showHeaderDivider
            sideActions=<Box paddingLeft="1">{renderToggleAllCheckbox()}</Box>
          >
            {renderList()}
          </CustomModalLayout>
        )}
      </SelectorList>
    </StorybookComponents.Stack>
  );
};
```

#### 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`.

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
          belowNode: (
            <StorybookComponents.Placeholder>
              Below node
            </StorybookComponents.Placeholder>
          ),
          showBelowNodeOnSelect: true,
          selected: true,
        },
        {
          id: 1,
          title: `Item`,
          belowNode: (
            <StorybookComponents.Placeholder>
              Below node
            </StorybookComponents.Placeholder>
          ),
          showBelowNodeOnSelect: true,
        },
        {
          id: 2,
          title: `Item`,
          belowNode: (
            <StorybookComponents.Placeholder>
              Below node
            </StorybookComponents.Placeholder>
          ),
          showBelowNodeOnSelect: true,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return <SelectorList dataSource={data} />;
};
```

#### No items empty state

Use `emptyState` prop to display the [`<EmptyState/>`](https://wix-pages.com/design-system-documentation/#/component/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.

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return (
    <SelectorList
      dataSource={data}
      imageSize="small"
      emptyState=<Box height="280px" align="center" verticalAlign="middle">
        <EmptyState
          image="EmptyState_Generic1.svg"
          title="Add your first meal"
          subtitle="Start getting orders by adding meals to your menu."
        >
          <TextButton prefixIcon={<Icons.Add />}>Add Meal</TextButton>
        </EmptyState>
      </Box>
    >
      {({ renderList }) => (
        <CustomModalLayout
          title="Edit menu"
          primaryButtonText="Save"
          secondaryButtonText="Cancel"
          onCloseButtonClick={() => {}}
          removeContentPadding
          showFooterDivider
          showHeaderDivider
        >
          {renderList()}
        </CustomModalLayout>
      )}
    </SelectorList>
  );
};
```

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

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Item`,
        },
        {
          id: 1,
          title: `Item`,
        },
        {
          id: 2,
          title: `Item`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return (
    <SelectorList
      dataSource={data}
      multiple
      renderNoResults={() => (
        <Box height="280px" align="center" verticalAlign="middle">
          <EmptyState
            image="EmptyState_Generic2.svg"
            title="No results found"
            subtitle="No items match your search criteria. Try to search by another keyword."
          >
            <TextButton>Clear Search</TextButton>
          </EmptyState>
        </Box>
      )}
    >
      {({ renderList }) => (
        <CustomModalLayout
          title="Import items"
          primaryButtonText="Import"
          secondaryButtonText="Cancel"
          onCloseButtonClick={() => {}}
          removeContentPadding
          showFooterDivider
          showHeaderDivider
        >
          {renderList()}
        </CustomModalLayout>
      )}
    </SelectorList>
  );
};
```

### 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`.

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = Array(50)
        .fill(0)
        .map((_, i) => ({
          id: i,
          title: `Item ${i + 1}`,
        }));

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return (
    <CustomModalLayout
      height="480px"
      title="Select item"
      primaryButtonText="Select"
      secondaryButtonText="Cancel"
      onCloseButtonClick={() => {}}
      removeContentPadding
      showHeaderDivider
      showFooterDivider
    >
      <SelectorList
        itemsPerPage={15}
        initialAmountToLoad={10}
        dataSource={data}
      />
    </CustomModalLayout>
  );
};
```

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

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Training`,
          subtitle: `3 posts`,
          extraNode: <Text secondary>Current category</Text>,
          disabled: true,
        },
        {
          id: 1,
          title: `Championships`,
          subtitle: `3 posts`,
        },
        {
          id: 3,
          title: `Inventory`,
          subtitle: `21 post`,
        },
        {
          id: 4,
          title: `Trainers`,
          subtitle: `18 posts`,
        },
        {
          id: 5,
          title: `Teams`,
          subtitle: `2 posts`,
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });

  return (
    <CustomModalLayout
      primaryButtonText="Move Post"
      secondaryButtonText="Cancel"
      onCloseButtonClick={() => {}}
      title="Move post to a category"
      removeContentPadding
      showFooterDivider
      showHeaderDivider
      width="600px"
    >
      <SelectorList dataSource={data} withSearch={false} />
    </CustomModalLayout>
  );
};
```

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

```jsx
() => {
  const data = (searchQuery, offset, limit) =>
    new Promise((resolve) => setTimeout(resolve, 2000)).then(() => {
      const items = [
        {
          id: 0,
          title: `Science Expert`,
          subtitle: `Monaco, Monaco`,
          extraNode: <Text secondary>$77/h</Text>,
          image: (
            <Avatar
              name="Science Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 1,
          title: `Yoga Expert`,
          subtitle: `New Delhi, India`,
          extraNode: <Text secondary>$78/h</Text>,
          image: (
            <Avatar
              name="Yoga Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 3,
          title: `History Expert`,
          subtitle: `Singapore, Singapore`,
          extraNode: <Text secondary>$52/h</Text>,
          image: (
            <Avatar
              name="History Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 4,
          title: `Statistics Expert`,
          subtitle: `Abidjan, Ivory Coast`,
          extraNode: <Text secondary>$80/h</Text>,
          image: (
            <Avatar
              name="Statistics Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 5,
          title: `Soccer Expert`,
          subtitle: `Tokyo, Japan`,
          extraNode: <Text secondary>$200/h</Text>,
          image: (
            <Avatar
              name="Soccer Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 6,
          title: `Culinary Expert`,
          subtitle: `Sydney, Australia`,
          extraNode: <Text secondary>$102/h</Text>,
          image: (
            <Avatar
              name="Culinary Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 7,
          title: `Design Expert`,
          subtitle: `Baku, Azerbaijan`,
          extraNode: <Text secondary>$75/h</Text>,
          image: (
            <Avatar
              name="Design Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 8,
          title: `SEO Expert`,
          subtitle: `San Francisco, United States`,
          extraNode: <Text secondary>$115/h</Text>,
          image: (
            <Avatar
              name="SEO Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 9,
          title: `Painting Expert`,
          subtitle: `Seoul, South Korea`,
          extraNode: <Text secondary>$65/h</Text>,
          image: (
            <Avatar
              name="Painting Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 10,
          title: `Health Expert`,
          subtitle: `Paris, France`,
          extraNode: <Text secondary>$160/h</Text>,
          image: (
            <Avatar
              name="Health Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 11,
          title: `Writing Expert`,
          subtitle: `Oklahoma City, United States`,
          extraNode: <Text secondary>$90/h</Text>,
          image: (
            <Avatar
              name="Writing Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 12,
          title: `Painting Expert`,
          subtitle: `Phoenix, Arizona, United States`,
          extraNode: <Text secondary>$80/h</Text>,
          image: (
            <Avatar
              name="Painting Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 13,
          title: `Meditation Expert`,
          subtitle: `Belgrade, Serbia`,
          extraNode: <Text secondary>$64/h</Text>,
          image: (
            <Avatar
              name="Meditation Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 14,
          title: `Career Expert`,
          subtitle: `Tokyo, Japan`,
          extraNode: <Text secondary>$130/h</Text>,
          image: (
            <Avatar
              name="Career Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
        {
          id: 15,
          title: `Sales Expert`,
          subtitle: `Bangkok, Thailand`,
          extraNode: <Text secondary>$75/h</Text>,
          image: (
            <Avatar
              name="Sales Expert"
              size="size60"
              imgProps={{ src: 'NotFoundImage.jpg' }}
            />
          ),
        },
      ];

      const filtered = items.filter(({ title }) =>
        title.toLowerCase().includes(searchQuery.toLowerCase()),
      );

      return {
        items: filtered.slice(offset, offset + limit),
        totalCount: filtered.length,
      };
    });
  return (
    <SelectorList itemsPerPage={10} dataSource={data} multiple>
      {({ renderList, renderToggleAllCheckbox, selectedItems }) => (
        <CustomModalLayout
          width="600px"
          height="480px"
          title="Select experts"
          primaryButtonText="Select"
          secondaryButtonText="Cancel"
          onCloseButtonClick={() => {}}
          removeContentPadding
          showFooterDivider
          showHeaderDivider
          sideActions=<Box paddingLeft="1">{renderToggleAllCheckbox()}</Box>
        >
          {renderList()}
        </CustomModalLayout>
      )}
    </SelectorList>
  );
};
```

## Code

```jsx
import { SelectorList } from '@wix/design-system';
```

### Props

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

## 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](invalid-url))
- **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](invalid-url)) — 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](invalid-url))
- **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](invalid-url)) — 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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **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