> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: TableListHeader Component

## Article: TableListHeader Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/lists/table/table-list-header-component.md

## Article Content:

# TableListHeader

_Components/Lists/Table_

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

## Overview

```jsx
<TableListHeader
  options={[
    { value: 'Name', sortable: true, sortDescending: true, width: '40%' },
    { value: 'Email' },
    { value: 'Last activity' },
    { value: 'Date created' },
  ]}
/>;
```

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TableListHeader
    options={[
      { value: <StorybookComponents.Placeholder height="30px" /> },
      { value: <StorybookComponents.Placeholder height="30px" /> },
      { value: <StorybookComponents.Placeholder height="30px" /> },
      { value: <StorybookComponents.Placeholder height="30px" /> },
    ]}
  />
  <TableListHeader
    options={[
      { value: 'Name' },
      { value: 'Email' },
      { value: 'Phone' },
      { value: 'Company' },
    ]}
  />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TableListHeader
    skin="standard"
    options={[{ value: 'Name' }, { value: 'Email' }, { value: 'Phone' }]}
  />
  <TableListHeader
    skin="neutral"
    options={[{ value: 'Name' }, { value: 'Email' }, { value: 'Phone' }]}
  />
</StorybookComponents.Stack>;
```

#### Number of columns

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TableListHeader options={[{ value: 'Name', width: '1fr' }]} />
  <TableListHeader
    options={[
      { value: 'Name', width: '1fr' },
      { value: 'Email', width: '3fr' },
    ]}
  />
  <TableListHeader
    options={[
      { value: 'Name', width: '1fr' },
      { value: 'Email', width: '1fr' },
      { value: 'Phone', width: '2fr' },
    ]}
  />
  <TableListHeader
    options={[
      { value: 'Name', width: '1fr' },
      { value: 'Email', width: '1fr' },
      { value: 'Phone', width: '1fr' },
      { value: 'Company', width: '1fr' },
    ]}
  />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TableListHeader
    options={[
      { value: 'Name', width: '25%' },
      { value: 'Email', width: '25%' },
    ]}
  />
  <TableListHeader
    options={[
      { value: 'Name', width: '1fr' },
      { value: 'Email', width: '1fr' },
    ]}
  />
</StorybookComponents.Stack>;
```

#### Column alignment

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

- `left` (default)
- `center`
- `right`

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TableListHeader
    options={[{ value: 'Align:' }, { value: 'Left', align: 'left' }]}
  />
  <TableListHeader
    options={[{ value: 'Align:' }, { value: 'Center', align: 'center' }]}
  />
  <TableListHeader
    options={[{ value: 'Align:' }, { value: 'Right', align: 'right' }]}
  />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<TableListHeader
  options={[
    {
      value: 'Name',
      infoTooltipProps: {
        content: 'Add additional info to explain this column value here',
      },
    },
    {
      value: 'Email',
      infoTooltipProps: {
        content: 'Add additional info to explain this column value here',
      },
    },
    { value: 'Phone' },
    {
      value: 'Company',
      infoTooltipProps: {
        content: 'Add additional info to explain this column value here',
      },
    },
  ]}
/>;
```

#### 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`

```jsx
<StorybookComponents.Stack flexDirection="column">
  <TableListHeader
    options={[{ value: 'Hidden (default)' }]}
    checkboxState="hidden"
  />
  <TableListHeader
    options={[{ value: 'Normal' }]}
    checkboxState="normal"
    onCheckboxChange={() => {}}
  />
  <TableListHeader
    options={[{ value: 'Checked' }]}
    checkboxState="checked"
    onCheckboxChange={() => {}}
  />
  <TableListHeader
    options={[{ value: 'Indeterminate' }]}
    checkboxState="indeterminate"
    onCheckboxChange={() => {}}
  />
  <TableListHeader
    options={[{ value: 'Has error' }]}
    checkboxState="hasError"
    onCheckboxChange={() => {}}
  />
  <TableListHeader options={[{ value: 'Disabled' }]} checkboxState="disabled" />
</StorybookComponents.Stack>;
```

#### Sortable

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

- `sortDescending`for setting which arrow displays next to a column title.
- `onSortChange` is for defining behavior each time a user clicks on a title.

```jsx
<TableListHeader
  onSortChange={() => {}}
  options={[
    { value: 'Name', sortable: true, sortDescending: true },
    { value: 'Email', sortable: true },
    { value: 'Phone', sortable: true },
    { value: 'Company', sortable: true },
  ]}
/>;
```

### 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.

```jsx
() => {
  const indexToColumn = {
    0: 'fieldName',
    1: 'type',
    2: 'appliesTo',
  };

  const [headerOptions, setHeaderOptions] = React.useState([
    {
      value: 'Field name',
      width: '3fr',
      sortable: true,
      sortDescending: true,
    },
    {
      value: 'Type',
      width: '3fr',
      sortable: true,
      sortDescending: true,
    },
    {
      value: 'Applies to',
      width: '2fr',
      sortable: true,
      sortDescending: true,
    },
  ]);

  const [items, setItems] = React.useState([
    { id: 0, text: 'Display info', isHeading: true },
    {
      id: 1,
      fieldName: 'Title',
      type: 'Public',
      appliesTo: 'All members',
    },
    {
      id: 2,
      text: 'Account',
      isHeading: true,
    },
    {
      id: 3,
      fieldName: 'First name',
      type: 'Private',
      appliesTo: 'All members',
    },
    {
      id: 4,
      fieldName: 'Last name',
      type: 'Public',
      appliesTo: 'All members',
    },
    {
      id: 5,
      fieldName: 'Email',
      type: 'Private',
      appliesTo: 'All members',
    },
    {
      id: 6,
      fieldName: 'Phone',
      type: 'Private',
      appliesTo: 'All members',
    },
    {
      id: 7,
      fieldName: 'Company',
      type: 'Private',
      appliesTo: 'All members',
    },
    {
      id: 8,
      text: 'Address',
      isHeading: true,
    },
    {
      id: 9,
      fieldName: 'Street',
      type: 'Private',
      appliesTo: 'All members',
    },
    {
      id: 10,
      fieldName: 'City',
      type: 'Private',
      appliesTo: 'All members',
    },
    {
      id: 11,
      fieldName: 'Zip code',
      type: 'Private',
      appliesTo: 'All members',
    },
    {
      id: 12,
      fieldName: 'Country',
      type: 'Private',
      appliesTo: 'All members',
    },
  ]);

  const handleDrop = ({ removedIndex, addedIndex }) => {
    const nextItems = [...items];
    nextItems.splice(addedIndex, 0, ...nextItems.splice(removedIndex, 1));
    setItems(nextItems);
  };

  const renderItem = ({ isPlaceholder, isPreview, item }) => {
    return (
      <div>
        {item.isHeading && (
          <Card.Subheader
            title=<Text size="small">{item.text}</Text>
            skin="neutral"
          />
        )}
        {!item.isHeading && isPlaceholder && (
          <Box
            boxSizing="border-box"
            width="100%"
            height="50px"
            borderWidth="1px"
            borderColor="B20"
            borderRadius="6px"
            verticalAlign="middle"
            paddingLeft="12px"
            marginBottom="0px"
            borderStyle="none"
            backgroundColor="B50"
          ></Box>
        )}
        {!item.isHeading && !isPlaceholder && (
          <TableListItem
            draggable
            showDivider
            onClick={() => {}}
            options={[
              { value: <Text>{item.fieldName}</Text>, width: '3fr' },
              {
                value: (
                  <Box gap="SP1" color="D30">
                    <Icons.LockLockedSmall />
                    <Text secondary size="small">
                      {item.type}
                    </Text>
                  </Box>
                ),
                width: '3fr',
              },
              {
                value: (
                  <Text secondary skin="primary" size="small">
                    {item.appliesTo}
                  </Text>
                ),
                width: '2fr',
              },
            ]}
          />
        )}
      </div>
    );
  };

  const canDrag = ({ item }) => {
    return !item.isHeading;
  };

  const sortItems = (index, sortDescending) => {
    const sortedItems = items
      .reduce((array, currentItem) => {
        if (currentItem.isHeading || array[array.length - 1][0].isHeading) {
          array.push([currentItem]);
        } else {
          array[array.length - 1].push(currentItem);
        }

        return array;
      }, [])
      .map((itemsArray) => {
        const returnValueWhenPreviousBigger = sortDescending ? 1 : -1;
        return itemsArray.sort((a, b) => {
          if (a[indexToColumn[index]] < b[indexToColumn[index]]) {
            return -returnValueWhenPreviousBigger;
          }

          if (a[indexToColumn[index]] > b[indexToColumn[index]]) {
            return returnValueWhenPreviousBigger;
          }

          return 0;
        });
      })
      .flat();

    setItems(sortedItems);
  };

  const handleSort = (index) => {
    const sortDescending = headerOptions[index].sortDescending;
    const nextHeaderOptions = [...headerOptions];
    nextHeaderOptions[index].sortDescending = !sortDescending;
    setHeaderOptions(nextHeaderOptions);

    sortItems(index, !sortDescending);
  };

  return (
    <Card hideOverflow>
      <Card.Header
        title="Customize form"
        subtitle="Set up fields and decide what info appears on public profile pages"
      />
      <Box direction="vertical">
        <TableListHeader onSortChange={handleSort} options={headerOptions} />
        <SortableListBase
          items={items}
          renderItem={renderItem}
          onDrop={handleDrop}
          canDrag={canDrag}
        />
      </Box>
    </Card>
  );
};
```

## Code

```jsx
import { TableListHeader } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checkboxState` | `"disabled" \| "hidden" \| "checked" \| "normal" \| "hasError" \| "indeterminate"` | — | State of Checkbox rendered at first column. 'hidden' to not render it. |
| `dataHook` | `string` | — | 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)` |
| `options` | `TableListHeaderColumn[]` | — | `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`, `moveBy` and `children` won't be passed to tooltip. |
| `ref` | `null \| 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). |
| `reserveCheckboxSpace` | `boolean` | `false` | Hides 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:

```jsx
// UniDriver
import { TableListHeaderUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { TableListHeaderTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { TableListHeaderTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { TableListHeaderTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `getColumnTextAt` | — |
| `toggleColumnSortAt` | — |
| `getCheckbox` | — |
| `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. |

## 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](invalid-url)) — 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](invalid-url)) — 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](invalid-url))
- **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](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes