TableListItem

Components/Lists/Table

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

Overview

Copy

A table list item is a single row of a table or a list, that allows users to scan and compare sets of data. These sets can be a list of similar items, like products, posts or contacts.

Do

  • Use this component for a simple list when a <Table/> is too complex.
  • Group similar items together for improved readability.
  • Organize important information for users.

Don't

  • Don't create tables with multiple actions like filtering, bulk operations and column sorting. Build a <Table/> instead.
  • Don't build drag and drop lists, a <NestableList/> is a better option for this.

Feature examples

Structure

Table list item organizes different sets of information into columns. It can have any number of columns, which can be added through options.

Add any content to the column with the value prop.

Note that column width and alignment can be controlled separately.

Copy

Padding

Adjust vertical spacing by using verticalPadding and horizontalPadding props. It supports 6 options:

  • xxTiny
  • xTiny
  • tiny
  • small (default)
  • medium
  • large

Use tiny size set for compact lists that display more items in smaller space.

Small (default) is a standard list size for most common cases.

While medium and large are used to emphasize a few items.

Copy

Drag handle size

Control a drag handle size with dragHandleSize prop. It supports two sizes:

  • small is used for more compact lists
  • large (default) is used for tables and more spacious UI layouts
Copy

Draggable item indication

Control a drag grip icon with props:

  • draggable marks that the component can be dragged.
  • dragging indicates that the component is being dragged.
  • showDragHandleOnHover shows handle only on hover
  • dragDisabled show that the component can't be dragged.

Note, drag and drop logic is not part of this component. For this solution, go to <NestableList/>.

Copy

Border

Control the appearance of the component using the border prop.

Use this property to emphasize the separation between items in a list.

Copy

Expandable

Give an ability to make an item expandable with expanded prop.

Copy

Selectable

Make an item selectable with the following props:

  • Use checkbox to enable the checkbox and show that the item can be selected.
  • checked changes the checkbox's default state to selected.
  • showSelectionBorder allows to turn off the blue strip indication when the item is selected
  • checkboxDisabled disables the checkbox.
  • selectable enables the selected state on the item
Copy

Divider

Enable the bottom divider with showDivider, which visually separates the items.

Note that the last item on the list shouldn't have a bottom divider.

Copy

Column width

Control the width of columns with the width prop. It supports all CSS grid-column-template values.

Copy

Column alignment

Align content inside of column cells using the align prop. It supports 3 values:

  • left
  • center
  • right
Copy

Actionable

Make an item actionable with the onClick prop. Once enabled, the item becomes interactive.

The <TableActionCell/> displays main and secondary actions.

Copy

Common use case examples

Grouped list

The TableListItem can be used to build lists that splits items into stages or categories.

Use <TableListHeader/> component to display titles for different sections.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaLabelstring—Provides context for screen readers when has a root element of list component in selectable state.
borderbooleanfalseAdds a border around the component.
borderRadius"none"—Controls the border radius of the component. Set to 'none' to render square (0px) corners, useful in themes that apply rounded corners by default.
checkboxbooleanfalseDefines whether the component is selectable by a checkbox.
checkboxDisabledboolean—Disables the visible checkbox.
checkboxTooltipContentReactNode—Defines a message to be displayed in a tooltip. Tooltip is displayed on a checkbox hover.
checkboxTooltipPropsTooltipCommonProps—Tooltip props (when hovering over the checkbox)
checkedboolean—Defines if component is selected.
contentStyleCSSProperties—Styles applied to the row's leading content — the controls container when the item renders controls, the options container otherwise.
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
dragDisabledboolean—Disables the visible drag handle.
draggablebooleanfalseMakes drag handle visible.
draggingboolean—Visually indicates that component is being dragged.
dragHandlePropsPartial<DragHandleProps>—Extra props to pass to the <DragHandle /> element.
dragHandleSize"small" | "large"largeChanges the size of the DragHandle.
expandablebooleanfalseAdds functionality to expand the list item.
expandDisabledboolean—Disables the visible expand handle.
expandedbooleanfalseDefines whether the list component is expanded/collapsed.
focusedboolean—Forces focus on drag handle.
hideDragHandleboolean—Hides drag handle visually.
horizontalPadding"small" | "tiny" | "medium" | "large" | "xxTiny" | "xTiny"largeAdjusts the left and right padding size.
onBlur(e: FocusEvent<Element, Element>) => void—Defines a callback when item loses its focus.
onCheckboxChangeChangeEventHandler—Defines a callback when checkbox is clicked.
onClickReactEventHandler<HTMLElement>—Defines a callback when the item is clicked.
onClickExpandMouseEventHandler—Defines a callback when caret handle is clicked.
onContextMenuMouseEventHandler—Defines a callback function which is called on contextmenu event on the list item.
onFocus(e: FocusEvent<Element, Element>) => void—Defines a callback when item gains focus.
onKeyUp(e: KeyboardEvent<Element>) => void—Defines a callback when the item is focused, and a key is pressed and released. Used for NestableList solutions controlled with a keyboard.
onMouseEnterMouseEventHandler—Defines a callback function which is called on onMouseEnter event on the list item.
onMouseLeaveMouseEventHandler—Defines a callback function which is called on onMouseLeave event on the list item.
options (required)TableListItemColumn[]—Defines each TableListItem column individually, using the following props: - value - defines column's content. - width - sets the width of a column. It supports every CSS grid-template-columns track value, for example 2fr or 120px. - align - aligns the content in the horizontal axis.
refnull | string | (instance: unknown) => void | RefObject<unknown>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).
reserveDragHandleSpaceboolean—Hides the drag handle without changing the layout. Used for aligning items when there's a mix of draggable and non-draggable items at the same level.
reserveExpandHandleSpaceboolean—Hides the expand handle without changing the layout. Used for aligning items when there's a mix of expandable and non-expandable items at the same level.
selectablebooleanfalseDefines whether the root element of list component is selectable.
showDividerbooleanfalseEnables a divider at the bottom of the list item.
showDragHandleOnHoverbooleanfalseEnables showing drag handle only on hover.
showSelectionBorderbooleantrueWhen item is with checkbox and is selected, adds a border on the left side of the component.
verticalPadding"small" | "tiny" | "medium" | "large" | "xxTiny" | "xTiny"smallAdjusts the top and bottom padding size.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getColumnTextAtGet column alternative text.
rightClickTriggers a right-click (contextmenu event) on the root element.
isCheckboxExistsDefines if checkbox exists.
isCheckboxCheckedDefines if checkbox is checked.
isCheckboxDisabledDefines if checkbox is disabled.
isCheckboxTooltipEnabledDefines if checkbox tooltip is enabled.
isDragHandleTooltipEnabledDefines if drag handle tooltip is enabled.
expandHandleExistsDefines if expand handle exists.
toggleCheckboxTrigger checkbox toggle.
toggleExpandHandleTrigger expand toggle.
hoverDragHandleTrigger hover on a drag handle.
getDragHandleDisabledDefines if drag handle is disabled.
getCheckboxTooltipContentGet the content of checkbox tooltip.
getDragHandleTooltipContentGet the content of drag handle tooltip.
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.337.0 (2026-10-14) — maintenance release, no component-specific changes
  • 1.336.0 (2026-10-13) — 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.328.0 (2026-09-22) — 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.313.1 (2026-08-18) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.308.0 (2026-08-04) — maintenance release, no component-specific changes
  • 1.307.0 (2026-08-03) — maintenance release, no component-specific changes
  • 1.299.0 (2026-07-17) — breaking: bm reimagined controls spacing and border radius tokens (#16559) — has visual changes
  • 1.294.0 (2026-07-02) — fix: reveal TableActionCell actions on mobile (#16445) — has visual changes
  • 1.293.0 (2026-06-26) — feat: add borderRadius prop (#16440) — 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.290.0 (2026-06-18) — fix: use table-list-item-gap token for column gap (#16415) — has visual changes
  • 1.289.0 (2026-06-17) — maintenance release, no component-specific changes
  • 1.288.0 (2026-06-15) — feat: add onContextMenu callback (#16366)
  • 1.282.0 (2026-05-27) — fix: reduce border-radius from 12px to 8px in odeditor and odeditor-dark (#16314) — has visual changes
  • 1.282.0 (2026-05-27) — fix: theme the expand chevron color so dark skins render it visibly (#16309) — has visual 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) — maintenance release, no component-specific changes
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.239.0 (2025-12-12) — feat: add onFocus & onBlur callback support (#15651)
  • 1.232.0 (2025-11-28) — maintenance release, no component-specific changes
  • 1.224.0 (2025-10-29) — fix: change gap in TableListItem in Studio (#15443)
  • 1.217.0 (2025-09-08) — breaking: update border color & radius (#15278)
  • 1.214.2 (2025-08-25) — feat: add custom selector for mobile hover (#15214)
  • 1.212.0 (2025-08-11) — breaking: add tokens (#15162)
  • 1.200.0 (2025-06-17) — maintenance release, no component-specific changes
  • 1.198.0 (2025-06-09) — maintenance release, no component-specific changes
  • 1.187.0 (2025-05-07) — maintenance release, no component-specific changes
  • 1.176.0 (2025-04-02) — maintenance release, no component-specific changes
  • 1.172.1 (2025-03-21) — maintenance release, no component-specific changes
  • 1.166.0 (2025-03-04) — breaking: tokenization (#14564)
  • 1.161.0 (2025-02-12) — feat: add ability to hide drag handle and show it only when the item is hovered (#14520)
  • 1.161.0 (2025-02-12) — feat: add ability to enable/disable border indicator on the left (#14518)
  • 1.161.0 (2025-02-12) — breaking: add alternative selected indication state | visual update drag handle color in all states (#14499)
  • 1.154.0 (2025-01-16) — feat: added onMouseEnter/onMouseLeave callbacks (#14453)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.136.0 (2024-10-24) — fix: fix table list extend button clicking area (#14238)
  • 1.128.0 (2024-09-19) — maintenance release, no component-specific changes
  • 1.127.1 (2024-09-16) — fix: revert making value container fullheight (#14135)
  • 1.127.0 (2024-09-12) — fix: making value container fullheight (#14120)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.105.0 (2024-05-21) — 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.95.0 (2024-02-15) — maintenance release, no component-specific changes
  • 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?