title: DataTable storybookPath: data-display-data-table isExperimentalPackage: true

The DataTable component presents a list of data in table form.

It uses @tanstack/react-table as a dependency to implement data selection and filtering capabilities. As such, certain table options are available as DataTable props. For example, the items and columns prop are required options.

Currently supported features from @tanstack/react-table are the following:

1. Row selection
2. Multi-row selection
3. Row expansion
4. Column visibility

However, certain defaults have been set for the component:

1. enableHiding is enabled by default;
2. enableMultiRowSelection is disabled by default, meaning row selection defaults to single-row;
3. enableRowSelection is automatically enabled when a callback value is passed in onRowSelectionChange.
4. The data property in React Table options is renamed to items to align with the rest of Spark Web's usage of data as a data attribute.

Copyable cells

Enable copying for an individual column with meta.copyToClipboard. On hover-capable pointer devices the copy button is visually hidden until the cell is hovered or the button receives keyboard focus; on devices without a hover-capable pointer it is always visible. Either way the cell reserves its space so the text does not reflow.

When a ToastProvider is mounted above the table, a successful copy shows a positive “{column name} copied to clipboard.” toast and an unsuccessful copy shows a critical toast. The column name comes from a string header or the column ID; set meta.copyLabel to override it. Copying still works when the consumer has no ToastProvider; it simply has no toast feedback.

import { ToastProvider } from '@spark-web/toast';

<ToastProvider>
  <DataTable
    items={items}
    columns={[
      {
        accessorKey: 'referenceNumber',
        header: 'Reference number',
        meta: { copyToClipboard: true },
      },
      {
        accessorKey: 'amount',
        header: 'Amount',
        meta: {
          copyToClipboard: true,
          getCopyText: context => `$${context.getValue()}`,
        },
      },
    ]}
  />
</ToastProvider>;

By default, string, number, boolean, and bigint accessor values can be copied. Use getCopyText for formatted values or non-primitive values. The automatic control is available only when DataTable renders its standard body; a custom renderRow owns its own copy interactions.

Example

<DataTable
  items={[
    {
      id: 1,
      name: 'Ken Adams',
      category: 'Solar System',
      amount: 3500,
    },
  ]}
  columns={[
    {
      id: 'id',
      accessorKey: 'id',
      header: 'ID',
      cell: info => <Text size="small">{info.renderValue()}</Text>,
    },
    {
      id: 'name',
      accessorKey: 'name',
      header: 'Name',
      cell: info => <Text size="small">{info.renderValue()}</Text>,
    },
    {
      id: 'category',
      accessorKey: 'category',
      header: 'Category',
      cell: info => <Text size="small">{info.renderValue()}</Text>,
    },
    {
      id: 'amount',
      accessorKey: 'amount',
      header: 'Amount',
      cell: info => <Text size="small">{info.renderValue()}</Text>,
    },
  ]}
/>

Props

DataTable