TableListHeader

Components/Lists/Table

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

Overview

Copy

Table list headers are used to provide column titles for custom list layouts.

Do

  • Provide column titles for data lists.

Don't

  • Don't divide <Card/> content into sections. Use <Card.Subheader/> instead.

Feature examples

Structure

Table list headers can have any number of columns. The default column value is text, but it can be replaced with other component.

Copy

Skin

Set the header's background with the skin prop:

  • standard is the default and suits a header sitting on a card.
  • neutral adds a tinted background, to separate the header from the rows beneath it.
Copy

Number of columns

To define the required number of columns in a table, use the options array.

Copy

Column width

Specify the width of each column in pixels, percentages or frames with the width prop. If not specified, columns will be sized equally.

Copy

Column alignment

Control content alignment in a column with the align prop. It supports 3 options:

  • left (default)
  • center
  • right
Copy

Column info

Include additional info to explain data in a specific column by adding an info icon next to titles. Use infoTooltipProps to show a message that will be displayed in a tooltip on hover.

Copy

Selectable

Add a checkbox that allows users to select all the items below the header with the checkboxState prop. It supports 6 values:

  • hidden (default)
  • normal
  • checked
  • indeterminate
  • hasError
  • disabled
Copy

Sortable

Allow users to sort data displayed below the header by clicking on column titles with the sortable prop.

  • sortDescendingfor setting which arrow displays next to a column title.
  • onSortChange is for defining behavior each time a user clicks on a title.
Copy

Common use case examples

Table with sections

Table list headers can be used to build custom table layouts, for example, a table that's divided into sections but still allows sorting and filter data.

Copy

Code

Copy

Props

NameTypeDefaultDescription
checkboxState"disabled" | "hidden" | "checked" | "normal" | "hasError" | "indeterminate"—State of Checkbox rendered at first column. 'hidden' to not render it.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
onCheckboxChange() => void—Called when checkbox is clicked.
onSortChange(colNum: number, nativeEvent: MouseEvent<HTMLDivElement, MouseEvent>) => void—A callback function called on each column title click. Signature onSortChange(colNum, nativeEvent)
optionsTableListHeaderColumn[]—width supports px/%/fr sortable: Sets whether this field is sortable. If true, clicking the header calls onSortChange sortDescending: Sets what sort icon to display in the column header. true shows an up arrow, false shows a down arrow, undefined' shows no icon infoTooltipProps: Props object for column header's [tooltip](/?path=/story/components-api-components--tooltip). Note: dataHook, moveByandchildren` won't be passed to tooltip.
refnull | string | (instance: HTMLDivElement | null) => void | RefObject<HTMLDivElement>—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).
reserveCheckboxSpacebooleanfalseHides the checkbox without changing the layout when checkboxState is 'hidden'. Used for aligning header columns with TableListItem rows that show a checkbox.
skin"standard" | "neutral"'standard'A way to switch between neutral and standard on the TableListHeader instead of Table.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getColumnTextAt—
toggleColumnSortAt—
getCheckbox—
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) — feat: add a reserveCheckboxSpace prop that keeps the checkbox space when checkboxState is 'hidden', so header columns align with TableListItem rows that show a checkbox. (#17296) — has visual changes
  • 1.330.3 (2026-09-29) — 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.320.0 (2026-09-03) — maintenance release, no component-specific changes
  • 1.313.1 (2026-08-18) — maintenance release, no component-specific changes
  • 1.312.0 (2026-08-14) — maintenance release, no component-specific changes
  • 1.311.0 (2026-08-12) — feat: added a skin prop with standard and neutral values, so the header skin can be set directly instead of through Table. (#16783) — has visual changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific 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.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.182.0 (2025-04-23) — feat: tokenise (#14777)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.112.0 (2024-07-03) — fix: fix infoTooltipIcon props (#13873)
  • 1.102.0 (2024-04-16) — 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?