ListItemSelect

Components/Form/Dropdownlistitems

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

Overview

Copy

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

Copy

Checkbox

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

Copy

Affix

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

Copy

Subtitle

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

Copy

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

Copy

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.

Copy

Advanced example

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
checkboxboolean—If true, a checkbox is shown.
dataHookstring—Applied as data-hook HTML attribute that can be used in the tests.
disabledboolean—If true, the item is disabled.
disabledDescriptionstring—Tooltip description if item is disabled.
disabledDescriptionTooltipPropsOmit<TooltipProps, "children" | "disabled" | "content">—Tooltip props if item is disabled.
ellipsisboolean—If true, long text doesn't break into more than one line and is terminated with an ellipsis.
highlightedboolean—If true, the item is highlighted, if false - highlighted styles aren't automatically applied on item hover.
onClickMouseEventHandler—Callback function triggered when list item is clicked.
prefixReactNode—Accepts any content to render before the title.
selectedboolean—If true, the item is selected.
size"small" | "medium"—Changing text size.
subtitleReactNode—Text of the list item subtitle.
subtitleMaxLinesnumber—Maximum number of subtitle lines before truncating with an ellipsis.
suffixReactNode—Accepts any content to render after the title, styled as secondary text.
titleReactNode—Title of the list item.
titleMaxLinesnumber—Maximum number of title lines before truncating with an ellipsis.
tooltipPropsTooltipProps—Allows to pass all common tooltip props.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
hasCheckboxCheck whether the checkbox appears
getPrefixGet prefix
getTitleGet title Text
getSubtitleGet subtitle Text
getSuffixGet suffix
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns 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)
  • 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) — 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) — 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)
  • 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)
  • 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)
  • 1.174.0 (2025-03-28) — breaking: change List item select font size & line height (#14652)
  • 1.173.0 (2025-03-25) — feat: add maxLines to title and subtitle (#14661)
  • 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)
  • 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)
  • 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)
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?