The DataTable component has been deprecated and will be removed in a future version. Use Table instead.

Data tables display information in a way that’s easy to scan, so that users can look for patterns and insights.

Usage

Ensure that Text uses the xsmall size for consistency. Empty table cells should display an em dash (—).

// docs helpers
const titleCase = (str) => str.charAt(0).toUpperCase() + str.slice(1);
const variants = ['stripes', 'dividers'];
const [separation, setSeparation] = useState(variants[0]);
// end: docs helpers
const data = [
  { employee: 'Luca Pacioli', email: undefined, phone: '0487654321' },
  { employee: 'Edwin Waterhouse', email: 'edwin@reckon.com', phone: undefined },
  { employee: 'John Rockerfeller', email: 'john@reckon.com', phone: '0412345678' },
];
const renderByKey = React.useCallback(
  (key) => (index) => <Text size="xsmall">{data[index][key] ?? '—'}</Text>,
  [data]
);
const columns = {
  employee: { label: 'Employee name', render: renderByKey('employee') },
  email: { label: 'Email address', render: renderByKey('email') },
  phone: { label: 'Phone number', render: renderByKey('phone') },
};
return (
  <Stack gap="large">
    <Inline>
      <SegmentedControl
        onChange={setSeparation}
        value={separation}
        options={variants.map((value) => ({ label: titleCase(value), value }))}
      />
    </Inline>
    <DataTable
      rowCount={data.length}
      columns={columns}
      separation={separation}
    />
  </Stack>
);

Sortable

Passing the sort prop and onSortChange callback will allow the user to change the sort order of the data.

We export a handy sortTableData function for this purpose. You should only use sortTableData if your data set is small and exists entirely in-memory, otherwise sorting should be implemented by sorting in the actual database.

Edit in Playroom

const data = [
  { employee: 'Luca Pacioli', earnings: 71921, super: 65334 },
  { employee: 'Edwin Waterhouse', earnings: undefined, super: 6279 },
  { employee: 'John Rockerfeller', earnings: 41702, super: null },
];
const dollars = (val) => `$${(val / 100).toFixed(2)}`;
const [sort, setSort] = React.useState({ key: 'employee', asc: true });
const sortedData = React.useMemo(() => sortTableData(data, sort), [sort]);
const renderByKey = React.useCallback(
  (key) => (index) => {
    const value = sortedData[index][key];
    let text = value ?? '—';
    if (typeof value === 'number') text = dollars(value);
    return <Text size="xsmall">{text}</Text>;
  },
  [sortedData]
);
const columns = {
  employee: { label: 'Employee', render: renderByKey('employee') },
  earnings: { label: 'Earnings', render: renderByKey('earnings') },
  super: { label: 'Super', render: renderByKey('super') },
};
return (
  <DataTable
    sort={sort}
    onSortChange={setSort}
    rowCount={sortedData.length}
    columns={columns}
  />
);

Overflow

When there isn't enough horizontal space to fit all the columns comfortably, you may introduce scrolling behaviour by setting the allowOverflow property.

Edit in Playroom

const data = [
  { employee: 'Luca Pacioli', email: 'luca@reckon.com', phone: '0487654321' },
  { employee: 'Edwin Waterhouse', email: 'edwin@reckon.com', phone: '0401234567' },
  { employee: 'John Rockerfeller', email: 'john@reckon.com', phone: '0412345678' },
];
const renderByKey = React.useCallback(
  (key) => (index) => <Text size="xsmall">{data[index][key] ?? '—'}</Text>,
  [data]
);
const columns = {
  employee: { width: 500, label: 'Employee', render: renderByKey('employee') },
  email: { width: 500, label: 'Email address', render: renderByKey('email') },
  phone: { width: 500, label: 'Phone number', render: renderByKey('phone') },
};
return (
  <DataTable
    allowOverflow
    rowCount={data.length}
    columns={columns}
  />
);

Custom rendering

Use the render prop to customise how cells in a row will be rendered.

Edit in Playroom

const dollars = (val) => `$${(val / 100).toFixed(2)}`;
const makeData = (inc) => {
  const cents = inc * 10000;
  return { earnings: cents, deductions: cents, netPay: cents, super: cents };
};
const data = [
  { employee: 'Luca Pacioli', ...makeData(1) },
  { employee: 'Edwin Waterhouse', ...makeData(1) },
  { employee: 'John Rockerfeller', ...makeData(2) },
];
const renderByKey = React.useCallback(
  (key) => (index) => {
    const value = data[index][key];
    let text = value ?? '—';
    if (typeof value === 'number') text = dollars(value);
    return <Text size="xsmall">{text}</Text>;
  },
  [data]
);
const simpleColumns = {
  earnings: { label: 'Earnings', render: renderByKey('earnings') },
  deductions: { label: 'Deductions', render: renderByKey('deductions') },
  netPay: { label: 'Net pay', render: renderByKey('netPay') },
  super: { label: 'Super', render: renderByKey('super') },
};
return (
  <DataTable
    rowCount={data.length}
    columns={{
      employee: {
        label: 'Employee',
        render: (index) => (
          <Flex alignItems="center">
            <Box marginRight="small">
              <UserAvatar name={data[index].employee} size="xsmall" />
            </Box>
            <Text size="small">{data[index].employee}</Text>
          </Flex>
        ),
      },
      ...simpleColumns,
      actions: {
        label: '',
        width: 100,
        render: (index) => (
          <Inline gap="small">
            <Tooltip content="Edit">
              <IconButton
                icon={Edit3Icon}
                label="Edit"
                size="small"
                variant="outline"
                onClick={() => {}}
              />
            </Tooltip>
            <Tooltip content="Delete">
              <IconButton
                icon={Trash2Icon}
                label="Delete"
                size="small"
                variant="outline"
                colorScheme="critical"
                onClick={() => {}}
              />
            </Tooltip>
          </Inline>
        ),
      },
    }}
  />
);

You may optionally render a table footer using the renderFooter function.

Edit in Playroom

const data = [
  { employee: 'Luca Pacioli', earnings: 71921, deductions: 28579, super: 65334 },
  { employee: 'Edwin Waterhouse', earnings: 50836, deductions: 37275, super: 62790 },
  { employee: 'John Rockerfeller', earnings: 41702, deductions: 90604, super: 70478 },
];
const dollars = (val) => `$${(val / 100).toFixed(2)}`;
const renderByKey = React.useCallback(
  (key) => (index) => {
    const value = data[index][key];
    let text = value ?? '—';
    if (typeof value === 'number') text = dollars(value);
    return <Text size="xsmall">{text}</Text>;
  },
  [data]
);
const footer = React.useCallback(
  (col) => {
    if (col === 'employee') return null;
    const total = data.reduce((num, row) => (num += row[col]), 0);
    return (
      <Text size="small" weight="bold">
        {dollars(total)}
      </Text>
    );
  },
  [data]
);
const columns = {
  employee: { label: 'Employee', render: renderByKey('employee') },
  earnings: { label: 'Earnings', render: renderByKey('earnings') },
  deductions: { label: 'Deductions', render: renderByKey('deductions') },
  super: { label: 'Super', render: renderByKey('super') },
};
return (
  <DataTable rowCount={data.length} columns={columns} renderFooter={footer} />
);

Empty state

Use the emptyState property to show the user something when there's no data to show. This is typically useful when the table is showing filterable data. The emptyState element is only shown when the rowCount is 0.

Edit in Playroom

const columns = {
  employee: { label: 'Employee name' },
  email: { label: 'Email address' },
  phone: { label: 'Phone number' },
};
return (
  <DataTable
    rowCount={0}
    columns={columns}
    emptyState={
      <Stack gap="medium" align="center">
        <Heading level={3}>You have no STP submissions yet</Heading>
        <Text color="muted" size="small">
          STP submissions will show up here as they have been filed
        </Text>
      </Stack>
    }
  />
);

Cell attributes

Use the cellAttributes function to apply styles, custom data-attributes, or anything else you need on a given table cell.

Edit in Playroom

const data = [
  { employee: 'Luca Pacioli', email: undefined, phone: '0487654321' },
  { employee: 'Edwin Waterhouse', email: 'edwin@reckon.com', phone: undefined },
  { employee: 'John Rockerfeller', email: 'john@reckon.com', phone: '0412345678' },
];
const renderByKey = React.useCallback(
  (key) => (index) => <Text size="xsmall">{data[index][key] ?? '—'}</Text>,
  [data]
);
const cellAttributes = React.useCallback(
  ({ key, colIndex, rowIndex }) => {
    const blue = data[rowIndex].employee === 'Edwin Waterhouse';
    const red = key === 'email';
    const background = blue && red ? 'plum' : blue ? 'SkyBlue' : red ? 'pink' : null;
    return {
      'data-first-col': colIndex === 0,
      style: { background },
    };
  },
  [data]
);
const columns = {
  employee: { label: 'Employee', render: renderByKey('employee') },
  email: { label: 'Email address', render: renderByKey('email') },
  phone: { label: 'Phone number', render: renderByKey('phone') },
};
return (
  <DataTable
    rowCount={data.length}
    columns={columns}
    cellAttributes={cellAttributes}
  />
);

Data Table

Usage

Sortable

Overflow

Custom rendering

Footer renderer

Empty state

Cell attributes