Components/Lists/Table
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/tablelistitem
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.
<Table/> is too complex.<Table/> instead.<NestableList/> is a better option for this.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.
Adjust vertical spacing by using verticalPadding and horizontalPadding props. It supports 6 options:
xxTinyxTinytinysmall (default)mediumlargeUse 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.
Control a drag handle size with dragHandleSize prop. It supports two sizes:
small is used for more compact listslarge (default) is used for tables and more spacious UI layoutsControl 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 hoverdragDisabled 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/>.
Control the appearance of the component using the border prop.
Use this property to emphasize the separation between items in a list.
Give an ability to make an item expandable with expanded prop.
Make an item selectable with the following props:
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 selectedcheckboxDisabled disables the checkbox.selectable enables the selected state on the itemEnable the bottom divider with showDivider, which visually separates the items.
Note that the last item on the list shouldn't have a bottom divider.
Control the width of columns with the width prop. It supports all CSS grid-column-template values.
Align content inside of column cells using the align prop. It supports 3 values:
leftcenterrightMake an item actionable with the onClick prop. Once enabled, the item becomes interactive.
The <TableActionCell/> displays main and secondary actions.
The TableListItem can be used to build lists that splits items into stages or categories.
Use <TableListHeader/> component to display titles for different sections.
| Name | Type | Default | Description |
|---|---|---|---|
ariaLabel | string | — | Provides context for screen readers when has a root element of list component in selectable state. |
border | boolean | false | Adds 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. |
checkbox | boolean | false | Defines whether the component is selectable by a checkbox. |
checkboxDisabled | boolean | — | Disables the visible checkbox. |
checkboxTooltipContent | ReactNode | — | Defines a message to be displayed in a tooltip. Tooltip is displayed on a checkbox hover. |
checkboxTooltipProps | TooltipCommonProps | — | Tooltip props (when hovering over the checkbox) |
checked | boolean | — | Defines if component is selected. |
contentStyle | CSSProperties | — | Styles applied to the row's leading content — the controls container when the item renders controls, the options container otherwise. |
dataHook | string | — | Applies a data-hook HTML attribute to be used in the tests. |
dragDisabled | boolean | — | Disables the visible drag handle. |
draggable | boolean | false | Makes drag handle visible. |
dragging | boolean | — | Visually indicates that component is being dragged. |
dragHandleProps | Partial<DragHandleProps> | — | Extra props to pass to the <DragHandle /> element. |
dragHandleSize | "small" | "large" | large | Changes the size of the DragHandle. |
expandable | boolean | false | Adds functionality to expand the list item. |
expandDisabled | boolean | — | Disables the visible expand handle. |
expanded | boolean | false | Defines whether the list component is expanded/collapsed. |
focused | boolean | — | Forces focus on drag handle. |
hideDragHandle | boolean | — | Hides drag handle visually. |
horizontalPadding | "small" | "tiny" | "medium" | "large" | "xxTiny" | "xTiny" | large | Adjusts the left and right padding size. |
onBlur | (e: FocusEvent<Element, Element>) => void | — | Defines a callback when item loses its focus. |
onCheckboxChange | ChangeEventHandler | — | Defines a callback when checkbox is clicked. |
onClick | ReactEventHandler<HTMLElement> | — | Defines a callback when the item is clicked. |
onClickExpand | MouseEventHandler | — | Defines a callback when caret handle is clicked. |
onContextMenu | MouseEventHandler | — | 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. |
onMouseEnter | MouseEventHandler | — | Defines a callback function which is called on onMouseEnter event on the list item. |
onMouseLeave | MouseEventHandler | — | 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. |
ref | null | 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). |
reserveDragHandleSpace | boolean | — | 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. |
reserveExpandHandleSpace | boolean | — | 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. |
selectable | boolean | false | Defines whether the root element of list component is selectable. |
showDivider | boolean | false | Enables a divider at the bottom of the list item. |
showDragHandleOnHover | boolean | false | Enables showing drag handle only on hover. |
showSelectionBorder | boolean | true | When item is with checkbox and is selected, adds a border on the left side of the component. |
verticalPadding | "small" | "tiny" | "medium" | "large" | "xxTiny" | "xTiny" | small | Adjusts the top and bottom padding size. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
getColumnTextAt | Get column alternative text. |
rightClick | Triggers a right-click (contextmenu event) on the root element. |
isCheckboxExists | Defines if checkbox exists. |
isCheckboxChecked | Defines if checkbox is checked. |
isCheckboxDisabled | Defines if checkbox is disabled. |
isCheckboxTooltipEnabled | Defines if checkbox tooltip is enabled. |
isDragHandleTooltipEnabled | Defines if drag handle tooltip is enabled. |
expandHandleExists | Defines if expand handle exists. |
toggleCheckbox | Trigger checkbox toggle. |
toggleExpandHandle | Trigger expand toggle. |
hoverDragHandle | Trigger hover on a drag handle. |
getDragHandleDisabled | Defines if drag handle is disabled. |
getCheckboxTooltipContent | Get the content of checkbox tooltip. |
getDragHandleTooltipContent | Get the content of drag handle tooltip. |
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. |
Last updated: 22 October 2026