> 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: ListItemSelect Component

## Article: ListItemSelect Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/list-item-select-component.md

## Article Content:

# ListItemSelect

_Components/Form/Dropdownlistitems_

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

## Overview

```jsx
<Layout cols={1}>
  <ListItemSelect checkbox title="For multi selection" suffix="Suffix area" />
</Layout>;
```

List Item Select represents a single option of any select component. It's highly configurable and can appear in Dropdown, Multiselect or Search components.

### Do

- Use it to build Dropdown, Multiselect, Search dropbox values or custom lists.

### Don't

- Don't use it as standalone component for general layouts. Use SectionHeader instead.

### Feature examples

#### Size

Component supports two sizes - `small` and `medium`

```jsx
<Layout cols={1}>
  <ListItemSelect title="Medium size" />
  <ListItemSelect size="small" title="Small size" />
</Layout>;
```

#### Checkbox

Item can be configured for multi select components by enabling `checkbox`.

```jsx
<Layout cols={1}>
  <ListItemSelect title="For single selection" />
  <ListItemSelect checkbox title="For multi selection" />
</Layout>;
```

#### Affix

Component has `prefix` and `suffix` areas. If plain text or icon is inserted, component automatically inverts the color when selected.

```jsx
<Layout cols={1}>
  <ListItemSelect
    prefix={
      <Box>
        <Icons.Toolbox />
      </Box>
    }
    title="Title area"
    suffix="Suffix area"
  />
  <ListItemSelect
    prefix={<Avatar size="size24" />}
    title="Title area"
    suffix={
      <Box>
        <Badge size="small" skin="success">
          Badge
        </Badge>
      </Box>
    }
  />
  <ListItemSelect
    selected
    prefix={
      <Box>
        <Icons.Toolbox />
      </Box>
    }
    title="Title area"
    suffix="Suffix area"
  />
  <ListItemSelect
    selected
    prefix={<Avatar size="size24" />}
    title="Title area"
    suffix={
      <Box>
        <Badge size="small" skin="success">
          Badge
        </Badge>
      </Box>
    }
  />
</Layout>;
```

#### Subtitle

Additional information, like user email or address can be inserted to subtitle area.

```jsx
<ListItemSelect title="Title area" subtitle="subtitle area" />;
```

#### Disabled

Component can be disabled, it automatically changes color of all areas if used as text or icon.

Tooltip can be added to explain why the component is disabled with `disabledDescription`

```jsx
() => {
  const listItemSelectOptions = [
    listItemSelectBuilder({
      id: 0,
      title: 'Disabled Action',
      disabled: true,
    }),
  ];

  return (
    <StorybookComponents.Stack spacing="24px" flexDirection="column">
      <ListItemSelect
        disabled
        prefix={<Icons.Toolbox />}
        title="Disabled without tooltip"
        subtitle="Subtitle area"
        suffix="Suffix area"
      />

      <ListItemSelect
        disabled
        checkbox
        prefix={<Icons.Toolbox />}
        title="Disabled with tooltip"
        subtitle="Subtitle area"
        suffix="Suffix area"
        disabledDescription="This action is disabled"
      />
    </StorybookComponents.Stack>
  );
};
```

#### Text cropping

By default component wraps the text. If needed it can be configured to show ellipsis and display full value on hover.

Tooltips on truncated text will be overridden if the component is disabled. In that case, it will show `disabledDescription` first.

```jsx
<Layout cols={1}>
  <ListItemSelect
    ellipsis
    titleMaxLines={2}
    subtitleMaxLines={2}
    title="This is a very very very very very very very very long text that will wrap to 2 lines"
    suffix="Nice long long long long long Suffix"
  />
  <ListItemSelect
    ellipsis
    title="This is a very very very very long text that will be cropped by ellipsis at some point"
    suffix="Nice long long long long long Suffix"
  />
  <ListItemSelect
    disabled
    ellipsis
    title="This is a very very very very long text that will be cropped by ellipsis at some point"
    suffix="Nice long long long long long Suffix"
    disabledDescription="This is disabled"
  />
</Layout>;
```

#### Advanced example

All properties work together and can be combined in various ways. It can be rendered as standalone or as part of dropdown.

```jsx
<Box height="230px">
  <DropdownLayout
    visible
    selectedId={2}
    options={[
      listItemSelectBuilder({
        id: 0,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Carmel Lloyd',
        subtitle: 'Kaplan 41',
        suffix: '31 Dec 2017',
      }),
      listItemSelectBuilder({
        id: 1,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Gracie-May Marsden',
        subtitle: 'Sderot Ben Gurion 75',
        suffix: '20 Jan 2000',
      }),
      listItemSelectBuilder({
        id: 2,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Keisha Decker',
        subtitle: 'Aminadav 18',
        suffix: '4 Nov 2010',
      }),
      listItemSelectBuilder({
        id: 3,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Ruairidh Fitzgerald',
        subtitle: 'HaYarkon 228',
        suffix: '7 Apr 2009',
        disabled: true,
        disabledDescription: 'User has unsubscribed and cannot be selected',
      }),
      listItemSelectBuilder({
        id: 4,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Sheldon Chavez',
        subtitle: 'Pinkas 2',
        suffix: '2 Dec 2019',
      }),
      listItemSelectBuilder({
        id: 5,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Brandan Gibbs',
        subtitle: 'Frishman 38',
        suffix: '1 Feb 2003',
      }),
      listItemSelectBuilder({
        id: 6,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Gordon Holmes',
        subtitle: 'HaShalom road 66',
        suffix: '19 Aug 2016',
      }),
      listItemSelectBuilder({
        id: 7,
        checkbox: true,
        prefix: <Avatar size="size30" />,
        title: 'Aaisha Rios',
        subtitle: 'Arlozorov 101',
        suffix: '22 Jul 2018',
      }),
    ]}
  />
</Box>;
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checkbox` | `boolean` | — | If true, a checkbox is shown. |
| `dataHook` | `string` | — | Applied as data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | If true, the item is disabled. |
| `disabledDescription` | `string` | — | Tooltip description if item is disabled. |
| `disabledDescriptionTooltipProps` | `Omit<TooltipProps, "children" \| "disabled" \| "content">` | — | Tooltip props if item is disabled. |
| `ellipsis` | `boolean` | — | If true, long text doesn't break into more than one line and is terminated with an ellipsis. |
| `highlighted` | `boolean` | — | If true, the item is highlighted, if false - highlighted styles aren't automatically applied on item hover. |
| `onClick` | `MouseEventHandler` | — | Callback function triggered when list item is clicked. |
| `prefix` | `ReactNode` | — | Accepts any content to render before the title. |
| `selected` | `boolean` | — | If true, the item is selected. |
| `size` | `"small" \| "medium"` | — | Changing text size. |
| `subtitle` | `ReactNode` | — | Text of the list item subtitle. |
| `subtitleMaxLines` | `number` | — | Maximum number of subtitle lines before truncating with an ellipsis. |
| `suffix` | `ReactNode` | — | Accepts any content to render after the title, styled as secondary text. |
| `title` | `ReactNode` | — | Title of the list item. |
| `titleMaxLines` | `number` | — | Maximum number of title lines before truncating with an ellipsis. |
| `tooltipProps` | `TooltipProps` | — | Allows to pass all common tooltip props. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { ListItemSelectUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { ListItemSelectTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { ListItemSelectTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { ListItemSelectTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `hasCheckbox` | Check whether the checkbox appears |
| `getPrefix` | Get prefix |
| `getTitle` | Get title Text |
| `getSubtitle` | Get subtitle Text |
| `getSuffix` | Get suffix |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **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.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.322.0** (2026-09-09) — fix: fix invalid selection attributes reported by accessibility checks for dropdown options and checkbox items. ([#17038](invalid-url))
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.306.0** (2026-07-31) — fix: align with the Harmony spec. Subtitle font weight changed from `500` to `400` in Harmony (odeditor) and Studio 2.0 (odeditor-dark). Medium items are no longer pinned to a 52px height in those themes and now size to their content, growing with taller prefixes (e.g. avatars). In Harmony (odeditor), left padding changed from `12px` to `8px` and the small-size suffix line-height from `16px` to `18px`. ([#16620](invalid-url)) — has visual changes
- **1.299.0** (2026-07-17) — maintenance release, no component-specific changes
- **1.298.0** (2026-07-14) — fix: refresh odeditor paddings, typography, gap and fills ([#16494](invalid-url)) — has visual changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — feat: disabled tooltip customisation ([#16014](invalid-url))
- **1.250.0** (2026-01-27) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.246.0** (2026-01-09) — maintenance release, no component-specific changes
- **1.245.0** (2026-01-06) — maintenance release, no component-specific changes
- **1.232.0** (2025-11-28) — maintenance release, no component-specific changes
- **1.216.0** (2025-09-01) — maintenance release, no component-specific changes
- **1.211.0** (2025-08-07) — maintenance release, no component-specific changes
- **1.205.0** (2025-07-15) — maintenance release, no component-specific changes
- **1.187.0** (2025-05-07) — breaking: fix studio styles ([#14831](invalid-url))
- **1.184.0** (2025-04-30) — maintenance release, no component-specific changes
- **1.180.0** (2025-04-14) — maintenance release, no component-specific changes
- **1.175.1** (2025-04-01) — fix: pass maxLine props through listItemSelectBuilder ([#14692](invalid-url))
- **1.174.0** (2025-03-28) — breaking: change List item select font size & line height ([#14652](invalid-url))
- **1.173.0** (2025-03-25) — feat: add maxLines to title and subtitle ([#14661](invalid-url))
- **1.172.1** (2025-03-21) — maintenance release, no component-specific changes
- **1.172.0** (2025-03-20) — maintenance release, no component-specific changes
- **1.169.0** (2025-03-10) — maintenance release, no component-specific changes
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.146.0** (2024-12-10) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.128.0** (2024-09-19) — fix: allow pointer events ([#14146](invalid-url))
- **1.120.1** (2024-08-08) — maintenance release, no component-specific changes
- **1.120.0** (2024-08-02) — maintenance release, no component-specific changes
- **1.114.0** (2024-07-11) — maintenance release, no component-specific changes
- **1.108.0** (2024-06-03) — fix: fix text centering ([#13799](invalid-url))
- **1.103.3** (2024-04-30) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.99.1** (2024-04-02) — feat: add mobile breakpoint ([#13540](invalid-url))
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes