Components/Lists/Table
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/table
Table is a component used to display data in rows and columns. It organizes information in a way that is easy to scan.
<NestableList/> instead.Table structures can vary, but they can include up to four elements:
<TableToolbar/> that displays table titles, filters and actions.<Table.SubToolbar/> that displays content related to toolbar actions (optional).<Table.Titlebar/> that displays titles in data columns (optional).<Table.Content/> that shows rows of data. Important: <Table.Content/> renders the column titlebar internally by default. If you render <Table.Titlebar/> explicitly (e.g. inside <Page.Sticky>), you must pass titleBarVisible={false} to <Table.Content/> to avoid a double titlebar.Choose between two colors for column title bars by using the skin prop.
standard is used for common cases (default).neutral is used to minimize the emphasis on column titles. It's also common for tables that don't support sorting.Use rowVerticalPadding to control the whitespace above and below row data. Choose one of the following options:
xxTiny - Adds 3px padding. Use it to create very compact tables that contain text only.xTiny - Adds 6px padding. Use it to create dense tables with short content.tiny - Adds 12px padding. Use it to create dense tables or for rows that contain media elements, such as images or avatars.small (default) - Adds 15px padding. Use this for common cases.medium - Adds 18px padding. Use this for short data lists.large - Adds 24px padding. Use sparingly for short data lists with a few items only.Note that in the Harmony and Studio 2.0 themes rows are taller and less crowded, and the table draws no rules between its rows, so a padding option renders more open there than the pixel values above suggest, and separation comes from the whitespace rather than from a divider.
Specify table width in pixels or percentage with the width property. If not set, table will have the same width as its parent container.
Define data columns via the columns array. Table can have any number of columns.
Control content alignment in a column with the align prop. It supports 3 options:
start (default)centerendSpecify width of each column with width prop. If not specified, columns will be sized equally.
Let people set their own column widths by dragging a handle in the column header. Resizing needs three things: resizable and horizontalScroll on the table, and a resizeProps.id on every column that should be resizable.
Give resizable columns a width in pixels. A percentage width is left untouched by the resize logic, so the drag has nothing to resize from. Bound the drag with minColumnWidth and maxColumnWidth, and pass resizeProps.disabled to pin a single column. The last column has no handle, since there is nothing to its right to trade width with. Use onColumnResize to persist the width someone picked.
Add a tooltip to give additional information about a specific column using infoTooltipProps. Style the tooltip message with all common <Tooltip/> properties.
Add any required content to the table cells. It accepts any component or a composition of multiple elements.
Emphasize specific rows that require user attention by highlighting them. Define a condition which must be matched via isRowHighlight function.
Highlight affects row background color and a font weight.
Allow users to find relevant data quicker by enabling column sorting.
Specify which column is sortable in columns array using the sortable prop.
Reveal more details about each row by allowing rows to expand. Define whether a specific row can be expanded or not with the expandable prop in data array.
By default one row can be expanded at a time only. Allow users to expand multiple rows simultaneously with the allowMultiDetailsExpansion prop.
Use the rowDetails prop to pass content to display once row is expanded. Control whether content has paddings or not with the removeRowDetailsPadding prop. Remove paddings when you want to display another table inside row details.
Specify whether column titles are visible with the titleBarDisplay prop.
Hide the titlebar only when column values are self explanatory.
Note: Column titles should be announced for assistive technology users even when titlebar is visually hidden.
Allow table content to exceed the width of a table itself by enabling horizontalScroll. Use it to support any number of data columns.
Allow users to act upon multiple items at once by enabling row selection with the showSelection prop.
Control 'Select all' checkbox visibility with the hideBulkSelectionCheckbox prop.
Display available bulk actions in the toolbar with following components:
<Button/> for main actions<PopoverMenu/> for secondary actionsNote: There should be no more than 3 actions visible in the toolbar at once.
Control what happens when user clicks on 'Select all' checkbox when one or few items are already selected.
By default, the first click on indeterminate state selects all remaining items in the list. Change it to deselecting all items first with the deselectRowsByDefault prop.
Restrict users from selecting a specific row by:
unselectable prop.selectionDisabled function. Use the checkboxTooltipContent prop to pass a tooltip message that explains why the row is disabled .Note: Tooltip message will not be reachable by assistive technologies and should be used as an additional explanation only. Make sure you explain the reason why item selection is not available in alternative ways, for example by using a subtitle or a different item status.
Load data to the table progressively with infiniteScroll.
Specify a number of items to load at once with the itemsPerPage prop. The rest will load on demand when the user scrolls down the list.
Define how many items will be selected in infinite scroll table when user clicks on 'Select All' checkbox with the totalSelectableCount prop. Newly loaded items that fall into a specified range will be selected automatically once loaded.
Split up large amounts of data across multiple pages using <Pagination/>. Use it to give users control to manually navigate between pages. It's beneficial when users operate with data chunks instead of a full list.
In tables that have selection enabled, make sure to provide an option to 'Select All' items in a toolbar container next to selected items count.
Use <Table.EmptyState/> to indicate that there are no existing entries that could be shown in a table. Make sure the illustration you show reflects the type of items the table will contain.
Make sure to provide an empty state when the user looks for content via search query or tries to narrow down the data list via filters and no items match the criterias.
Render table without a toolbar when it is displayed in an overlay component, such as a <CustomModalLayout/> or a <SidePanel/>. Make sure content paddings in a selected layout is turned off.
Enable users to find relevant data quicker by providing them with data filters and search.
We recommend to store up to 3 filters at once in a toolbar container. Check <Table.Toolbar/> page for all available toolbar arrangement options.
If there are more than 3 filters, transfer them outside of a table to a side panel. Add a button to a toolbar to call out this panel.
Note: Make sure to inform users about currently active filters. Display them as a list of tags in a <Table.Subtoolbar/> container.
Wrap table toolbar to a<Page.Sticky/> element to keep it always visible to users. Use it for infinite scroll tables.
| Name | Type | Default | Description |
|---|---|---|---|
allowMultiDetailsExpansion | boolean | — | |
bulkSelectionCheckboxRef | null | (instance: HTMLInputElement | null) => void | RefObject<HTMLInputElement> | — | A ref to the bulk selection checkbox in the table titlebar. |
children | ReactNode | — | Accept any wrapper component as a child element. It must eventually include <Table.Content/>. |
columns (required) | TableColumn<RowData>[] | — | Configures table columns. Required properties for each column: * title: specifies a text string or an element to display in the table titlebar * render: defines a function which is called to display this row value for this columnOptional properties for each column: * onCellClick: defines a callback function which is called each time a cell in this column is clicked. Signature: onCellClick(column, rowData, rowNum, event) * sortable: specifies whether field is sortable. If true, clicking the header calls onSortClick. * sortDescending: specifies what sort icon to display in the column header. true shows an up arrow, false shows a down arrow, undefined' shows no icon. * infoTooltipProps: controls info [tooltip](/?path=/story/components-overlays--tooltip) appearance in titlebar. Note: dataHook, moveByandchildrenwon't be passed to tooltip. *style: applies a custom CSS class to the component's root element * align: controls the alignment of the column content * width: sets the width of a column. No value means the column tries to contain its children, if possible. * important: increases text size of this column data across all rows, sets font color to D10 * stickyActionCell: specifies whether controls are fixed to the right side of the table *resizeProps: configures column resize behavior. When provided with an id, enables resizing for this column. Use disabled: trueto show a disabled handle, ordisabled: true, hideDisabledResizeHandle: true` to hide the handle completely. |
controlled | boolean | — | Specifies whether infinite scroll paging is controlled by the consumer. When true, the table renders all of data and calls loadMore whenever it needs more rows, instead of first revealing the rows already in data itemsPerPage at a time. Used only when infiniteScroll is true. |
data | RowData[] | — | |
dataHook | string | — | Applies a data-hook HTML attribute to be used in the tests. |
deselectRowsByDefault | boolean | false | Controls bulk selection checkbox behaviour in indeterminate state. By default, first click on indeterminate state selects all items in the table. If set to true, the first click deselects all items instead. |
dragAndDrop | any | — | Enables reordering rows by drag and drop. Pass TableDragAndDrop from @wix/wix-style-react-incubator/drag-and-drop, which supplies the droppable table context and the drag handle column. |
dynamicRowClass | (rowData: RowData, rowNum: number) => string | — | |
hasMore | boolean | false | Specifies whether there are more rows to load. When false, loadMore isn't called. Used only when infiniteScroll is true. |
headerClass | string | — | |
headerRowClass | string | — | |
hideBulkSelectionCheckbox | boolean | false | Hides bulk selection checkbox in the table titlebar. |
horizontalScroll | boolean | false | Specifies whether the table scrolls horizontally when its columns are wider than its container. |
id | string | — | |
infiniteScroll | boolean | false | Specifies whether rows are rendered gradually as the user scrolls instead of all at once. |
infiniteScrollRef | null | (instance: any) => void | RefObject<any> | — | |
initialLoad | boolean | true | Specifies whether infinite scroll checks for more rows to load right after the table mounts. Used only when infiniteScroll is true. |
isApplyColumnWidthStyle | boolean | — | |
isDragAndDropDisabled | boolean | — | Disables dragging rows and hides the drag handle column. Used only when dragAndDrop is set. |
isRowActive | (rowData: RowData, rowNum: number) => boolean | — | |
isRowDisabled | (rowData: RowData) => boolean | — | |
isRowHighlight | (rowData: RowData, rowNum: number) => boolean | — | |
itemsPerPage | number | 20 | Sets how many rows are revealed on each load. Used only when infiniteScroll is true. |
loader | ReactNode | — | |
loadMore | () => void | null | Defines a callback function which is called when more rows are requested while scrolling. Used only when infiniteScroll is true. |
onDragCancel | (event: DragEndEvent) => unknown | — | |
onDragEnd | (event: DragEndEvent) => unknown | — | |
onDragStart | (event: DragStartEvent) => unknown | — | |
onMouseEnterRow | (rowData: RowData, rowNum: number) => void | — | |
onMouseLeaveRow | (rowData: RowData, rowNum: number) => void | — | |
onRowClick | (rowData: RowData, rowNum: number) => void | — | |
onSelectionChanged | OnSelectionChangedFn | — | Defines a callback function which is called when selection happens. There are 3 types of selections: * ALL - bulk selection checkbox has been triggered to select all items * SINGLE_TOGGLE - a checkbox to select one item from the list has been triggered. The change object also includes an id prop with the unique item identifier and a value prop with the new boolean selection state of the item. * NONE - bulk selection has been triggered to unselect all items. |
onSelectionStarted | () => void | — | Called when item selection triggered but not changed yet. |
onSortClick | (colData: TableColumn<any>, colNum: number) => void | — | Defines a callback function which is called on column title click. |
removeRowDetailsPadding | boolean | false | Specifies whether the vertical padding of an expanded row details section is removed. |
resizable | boolean | — | |
resizeProps | DataTableResizeProps | — | |
rowClass | string | — | |
rowDataHook | string | DataTableRowDataHookFn<RowData> | — | |
rowDetails | (rowData: RowData, rowNum: number) => ReactNode | — | |
rowStatus | (row: RowData, rowNum: number) => TableRowStatusValue | null | undefined | — | When provided, renders a fixed-width status slot per row to the right of the selection/row-number control. The callback returns a { status, messages } config for rows that need a status indicator, or null/undefined for an empty but width-reserved slot — the slot never collapses. Only error and warning statuses are supported; the slot is exclusively for those two indicator kinds, rendered via the WDS <StatusIndicator/>. |
rowVerticalPadding | "small" | "tiny" | "medium" | "large" | "xxTiny" | "xTiny" | 'small' | Controls the vertical padding of the table rows. |
scrollElement | HTMLElement | RefObject<any> | null | Sets the element whose scroll events infinite scroll listens to. Overrides useWindow. Used only when infiniteScroll is true. |
selectedIds | string[] | number[] | — | Defines an array of selected rows. |
selectionDisabled | false | true | SelectionDisabledFn<RowData> | — | Specifies whether table row selection is restricted at a given moment. Can be defined as: * bool disables selection for all table rows * function that is called for each row to check whether to disable selection or not depending on specified condition |
showHeaderWhenEmpty | boolean | false | Specifies whether the table header is rendered when data is empty. When false, an empty table renders nothing. |
showLastRowDivider | boolean | true | Specifies whether a divider is shown below the last row. |
showRowNumbers | boolean | false | When true and showSelection is enabled, displays row numbers in the selection column. The checkbox appears on hover or when the row is selected. |
showSelection | boolean | false | Displays selection checkbox as a first column in each row. To hide the selection checkbox from a specific row, set its row.unselectable value to true in the data array. |
skin | "standard" | "neutral" | 'standard' | Controls the header style of the table. 'standard' fills the header with the standard surface color and 'neutral' fills it with the neutral surface color. |
stickyColumns | number | 0 | Sets the number of leading columns that stay fixed while the table scrolls horizontally. Used only when horizontalScroll is true. |
totalSelectableCount | number | — | Specifies the total number of selectable items in the table (including items not loaded yet). When 'Select all' is triggered in infinite scroll tables, newly loaded items are selected automatically. In this case, SelectionContext holds not-selected items rather than the selected ones. SelectionContext.infiniteBulkSelected is true and SelectionContext.selectedCount is the value of totalSelectableCount minus the count of unselected items. |
useWindow | boolean | true | Specifies whether infinite scroll listens to scroll events on the window. When false, it listens on the table's parent element. Used only when infiniteScroll is true. |
viewportRef | RefObject | — | Sets the scrollable element that <TableFloatingScrollBar/> sticks to. Used only when horizontalScroll is true. Inside a <Page/>, the page's scroll container is used instead. |
virtualized | boolean | — | |
virtualizedLineHeight | number | 60 | Sets the height of each row in pixels. Used only when virtualized is true. |
virtualizedListRef | null | string | (instance: any) => void | RefObject<any> | — | |
virtualizedTableHeight | number | — | |
width | string | '100%' | Sets the width of the table. Accepts a percentage or pixel value. |
withWrapper | boolean | true | When false then Table would not create a <div/> wrapper around it's children. Useful when using <Table/> to wrap a <Page/> component, in that case we use the <Table/> only as a context provider and it doesn't render anything to the DOM by itself. |
No testkit for this component — it doesn't expose a unidriver testkit.
onRowClick) no longer breaks the column layout — in 1.323.0 the focused row's cells shifted one column to the right and every other row shrank. The row shows the standard focus ring again. (#17096) — has visual changesonRowClick and no longer swallows the keystroke, so typing in cell inputs works. Only the row itself still activates on Enter/Space. (#16760)flex: 1 if width is null (#13918)Last updated: 22 October 2026