<Table aria-label="Example table">
  <TableHeader>
    <TableColumnHeader>Name</TableColumnHeader>
    <TableColumnHeader>Email</TableColumnHeader>
    <TableColumnHeader>Created</TableColumnHeader>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell role="rowheader">Ludovico Wixey</TableCell>
      <TableCell>lwixeyrp@constantcontact.com</TableCell>
      <TableCell>2021-07-23</TableCell>
    </TableRow>
    <TableRow>
      <TableCell role="rowheader">Christa Starkie</TableCell>
      <TableCell>cstarkierq@sphinn.com</TableCell>
      <TableCell>2021-12-08</TableCell>
    </TableRow>
    <TableRow>
      <TableCell role="rowheader">Herc Orneles</TableCell>
      <TableCell>hornelesrr@ibm.com</TableCell>
      <TableCell>2021-07-23</TableCell>
    </TableRow>
  </TableBody>
</Table>

Concepts

This package contains many low-level "primitive" components, which can be composed together to achieve the desired table interface.

Primitives

Primitives are "dumb" components that assume as little as possible about their usage, they don't own any state and have no side-effects, making them easier to understand and maintain for our team.

Primitives allow us to move quickly and build the best abstraction for each case. While the approach to composition may vary depending on requirements and constraints, primitives offer familiarity along with flexibility.

<Table>
  <TableHeader>
    <TableColumnHeader />
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableBody>
  <TableFooter>
    <TableCell />
  </TableFooter>
</Table>

Motivation

Monolithic components don't know your application's constraints and requirements. Assumptions must be made about how a component will be used, which often results in some less-than-ideal implementation artefacts:

increased API surface-area i.e. endless prop configuration
limited opportunity for performance improvements
inability to support changes in design requirements

Appearance

Cell appearance

The TableCell component accepts props to adust appearance:

align — Sets the horizontal alignment of cell contents.
maxWidth — Sets the maximum width of the cell.
minWidth — Sets the minimum width of the cell.
width — Sets the width of the cell.
showDivider — Whether the cell should show a divider between it and the next cell. When using sticky cells dividers are shown by default.

Edit in Playroom

<Table aria-label="Example with cell appearance props">
  <TableHeader>
    <TableColumnHeader showDivider minWidth={140} maxWidth={220}>
      Name
    </TableColumnHeader>
    <TableColumnHeader minWidth={320}>Notes</TableColumnHeader>
    <TableColumnHeader align="right" width={120}>
      Created
    </TableColumnHeader>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell role="rowheader" showDivider minWidth={140} maxWidth={220}>
        Ludovico Wixey
      </TableCell>
      <TableCell minWidth={320}>
        Risus praesent lectus vestibulum quam sapien varius ut blandit
      </TableCell>
      <TableCell align="right" width={120}>
        2021-07-23
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell role="rowheader" showDivider minWidth={140} maxWidth={220}>
        Christa Starkie
      </TableCell>
      <TableCell minWidth={320}>
        Quam pharetra magna ac consequat metus sapien ut nunc vestibulum ante
        ipsum primis in faucibus orci luctus et ultrices
      </TableCell>
      <TableCell align="right" width={120}>
        2021-12-08
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell role="rowheader" showDivider minWidth={140} maxWidth={220}>
        Herc Orneles
      </TableCell>
      <TableCell minWidth={320}>
        Morbi ut odio cras mi pede malesuada in imperdiet et commodo vulputate
        justo in blandit ultrices enim lorem ipsum dolor sit amet consectetuer
        adipiscing elit
      </TableCell>
      <TableCell align="right" width={120}>
        2021-07-23
      </TableCell>
    </TableRow>
  </TableBody>
</Table>

Row appearance

The TableRow component accepts props to adust appearance:

status — Sets the interaction status of the row.
tone — Sets tone of the row, influences the background colour.
disabled - Makes the row as disabled. Can be used while dragging or selecting where some rows aren't meant to be interacted with.

Edit in Playroom

<Stack gap="large">
  <Table aria-label="Example with row status">
    <TableHeader>
      <TableColumnHeader>Status</TableColumnHeader>
    </TableHeader>
    <TableBody>
      <TableRow>
        <TableCell role="rowheader">Default</TableCell>
      </TableRow>
      <TableRow status="dragging">
        <TableCell role="rowheader">Dragging</TableCell>
      </TableRow>
    </TableBody>
  </Table>
  <Table aria-label="Example with row tone">
    <TableHeader>
      <TableColumnHeader>Tone</TableColumnHeader>
    </TableHeader>
    <TableBody>
      <TableRow>
        <TableCell role="rowheader">Default</TableCell>
      </TableRow>
      <TableRow tone="positive">
        <TableCell role="rowheader">Positive</TableCell>
      </TableRow>
      <TableRow tone="cautious">
        <TableCell role="rowheader">Cautious</TableCell>
      </TableRow>
      <TableRow tone="critical">
        <TableCell role="rowheader">Critical</TableCell>
      </TableRow>
    </TableBody>
  </Table>
  <Table aria-label="Example with disabled row">
    <TableHeader>
      <TableColumnHeader>Status</TableColumnHeader>
    </TableHeader>
    <TableBody>
      <TableRow disabled>
        <TableCell role="rowheader">Disabled</TableCell>
      </TableRow>
      <TableRow>
        <TableCell role="rowheader">Not disabled</TableCell>
      </TableRow>
    </TableBody>
  </Table>
</Stack>

Table appearance

The root Table component accepts props to infuence the appearance of every cell:

alignY — Sets the vertical alignment for content within each cell. Only relevant when allowing text content to wrap.
density — Sets the amount of vertical padding within each cell.
overflowStrategy — Sets the overflow strategy for Text content within each cell.

Edit in Playroom

const alignYOptions = React.useMemo(
  () => [
    { label: 'Top', value: 'top' },
    { label: 'Center', value: 'center' },
    { label: 'Bottom', value: 'bottom' },
  ],
  []
);
const densityOptions = React.useMemo(
  () => [
    { label: 'Compact', value: 'compact' },
    { label: 'Regular', value: 'regular' },
    { label: 'Spacious', value: 'spacious' },
  ],
  []
);
const overflowStrategyOptions = React.useMemo(
  () => [
    { label: 'Truncate', value: 'truncate' },
    { label: 'Wrap', value: 'wrap' },
  ],
  []
);
const [alignY, setAlignY] = useState(alignYOptions[0].value);
const [density, setDensity] = useState(densityOptions[2].value);
const [overflowStrategy, setOverflowStrategy] = useState(
  overflowStrategyOptions[1].value
);
return (
  <Stack gap="large">
    <Columns gap="large">
      <Fieldset legend="Align-Y">
        <SegmentedControl
          block
          onChange={setAlignY}
          value={alignY}
          options={alignYOptions}
        />
      </Fieldset>
      <Fieldset legend="Density">
        <SegmentedControl
          block
          onChange={setDensity}
          value={density}
          options={densityOptions}
        />
      </Fieldset>
      <Fieldset legend="Overflow strategy">
        <SegmentedControl
          block
          onChange={setOverflowStrategy}
          value={overflowStrategy}
          options={overflowStrategyOptions}
        />
      </Fieldset>
    </Columns>
    <Table
      aria-label="Example with table appearance props"
      alignY={alignY}
      density={density}
      overflowStrategy={overflowStrategy}
    >
      <TableHeader>
        <TableColumnHeader>Name</TableColumnHeader>
        <TableColumnHeader width={400}>Notes</TableColumnHeader>
        <TableColumnHeader>Created</TableColumnHeader>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell role="rowheader">Ludovico Wixey</TableCell>
          <TableCell width={400}>
            Risus praesent lectus vestibulum quam sapien varius ut blandit
          </TableCell>
          <TableCell>2021-07-23</TableCell>
        </TableRow>
        <TableRow>
          <TableCell role="rowheader">Christa Starkie</TableCell>
          <TableCell width={400}>
            Quam pharetra magna ac consequat metus sapien ut nunc vestibulum
            ante ipsum primis in faucibus orci luctus et ultrices
          </TableCell>
          <TableCell>2021-12-08</TableCell>
        </TableRow>
        <TableRow>
          <TableCell role="rowheader">Herc Orneles</TableCell>
          <TableCell width={400}>
            Morbi ut odio cras mi pede malesuada in imperdiet et commodo
            vulputate justo in blandit ultrices enim lorem ipsum dolor sit amet
            consectetuer adipiscing elit
          </TableCell>
          <TableCell>2021-07-23</TableCell>
        </TableRow>
      </TableBody>
    </Table>
  </Stack>
);

Sticky behaviour

The stickyOffset property applies "sticky" positioning to the element, offset relative to its nearest scrolling ancestor.

Edit in Playroom

const rows = React.useMemo(() => getData(100), []);
const total = React.useMemo(() => {
  return rows.reduce(
    (acc, item) => {
      return {
        income: acc.income + item.income,
        super: acc.super + item.super,
        tax: acc.tax + item.tax,
      };
    },
    { income: 0, super: 0, tax: 0 }
  );
}, [rows]);
return (
  <Box overflowX="auto" height={300}>
    <Table aria-label="Example table with sticky behaviour">
      <TableHeader stickyOffset={0}>
        <TableColumnHeader width={60}>ID</TableColumnHeader>
        <TableColumnHeader stickyOffset={0} width={160}>
          Name
        </TableColumnHeader>
        <TableColumnHeader minWidth={360}>Email</TableColumnHeader>
        <TableColumnHeader width={160} align="end">
          Income
        </TableColumnHeader>
        <TableColumnHeader width={160} align="end">
          Super
        </TableColumnHeader>
        <TableColumnHeader width={160} align="end">
          Tax
        </TableColumnHeader>
        <TableColumnHeader width={160} align="end" stickyOffset={-0}>
          Net
        </TableColumnHeader>
      </TableHeader>
      <TableBody>
        {rows.map((item, idx) => {
          return (
            <TableRow key={item.id}>
              <TableCell width={60}>{item.id}</TableCell>
              <TableCell role="rowheader" width={160} stickyOffset={0}>
                {`${item.first_name} ${item.last_name}`}
              </TableCell>
              <TableCell minWidth={360}>{item.email}</TableCell>
              <TableCell width={160} align="end">
                {formatCurrency(item.income)}
              </TableCell>
              <TableCell width={160} align="end">
                {formatCurrency(item.super)}
              </TableCell>
              <TableCell width={160} align="end">
                {formatCurrency(item.tax)}
              </TableCell>
              <TableCell width={160} align="end" stickyOffset={-0}>
                {formatCurrency(item.income - item.super - item.tax)}
              </TableCell>
            </TableRow>
          );
        })}
      </TableBody>
      <TableFooter stickyOffset={0}>
        <TableCell width={60}>
          <VisuallyHidden>N/A</VisuallyHidden>
        </TableCell>
        <TableCell role="rowheader" width={160} stickyOffset={0}>
          <Text weight="bold">Totals</Text>
        </TableCell>
        <TableCell minWidth={360}>
          <VisuallyHidden>N/A</VisuallyHidden>
        </TableCell>
        <TableCell width={160} align="end">
          <Text weight="bold">{formatCurrency(total.income)}</Text>
        </TableCell>
        <TableCell width={160} align="end">
          <Text weight="bold">{formatCurrency(total.super)}</Text>
        </TableCell>
        <TableCell width={160} align="end">
          <Text weight="bold">{formatCurrency(total.tax)}</Text>
        </TableCell>
        <TableCell width={160} align="end" stickyOffset={-0}>
          <Text weight="bold">
            {formatCurrency(total.income - total.super - total.tax)}
          </Text>
        </TableCell>
      </TableFooter>
    </Table>
  </Box>
);

Sticky rows

The TableHeader and TableFooter may be "sticky" along the vertical axis:

The TableHeader will be offset against the top.
The TableFooter will be offset against the bottom.

Sticky cells

The TableColumnHeader and TableCell may be "sticky" along the horizontal axis:

Positive values e.g. 0, 240 will offset the cell against the left.
Negative values e.g. -0, -240 will offset the cell against the right.

Providing a stickyOffset will default the showDivider property to true.

Custom content

There's some optimisations provided out-of-the-box that are only supported with default usage. When providing ReactText (string and number) content to cells TableColumnHeader and TableCell everything will behave as expected.

Text behaviour

Custom implementations, depending on design requirements, can adjust Text appearance and behaviour to match the table defaults.

Edit in Playroom

<Table aria-label="Example of custom text content" alignY="top">
  <TableHeader>
    <TableColumnHeader>Standard</TableColumnHeader>
    <TableColumnHeader>
      <Text>Non-standard</Text>
    </TableColumnHeader>
    <TableColumnHeader>
      <Text color="dim" weight="medium" transform="uppercase">
        Adjusted
      </Text>
    </TableColumnHeader>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell role="rowheader">
        Risus praesent lectus vestibulum quam sapien varius ut blandit
      </TableCell>
      <TableCell>
        <Text>
          Risus praesent lectus vestibulum quam sapien varius ut blandit
        </Text>
      </TableCell>
      <TableCell>
        <Text overflowStrategy="truncate">
          Risus praesent lectus vestibulum quam sapien varius ut blandit
        </Text>
      </TableCell>
    </TableRow>
  </TableBody>
</Table>

Memoization

Custom cell content should be memoized with useMemo for simple cases and memo for complex component cases.

Sorting

The TableColumnHeader accepts an onClick prop, which should be used for sorting. When a click handler is provided you must also provide aria-sort to the actively sorted column, which will render the appropriate arrow indicator and let users of assistive tech know how the data within the table is sorted.

Edit in Playroom

const defaultRows = React.useMemo(() => getData(50), []);
// initialise the sort descriptor state
const [sortDescriptor, setSortDescriptor] = useState({
  column: 'first_name',
  direction: 'ascending',
});
// creates the click handler for a given column key
const createSortHandler = React.useCallback(
  (column) => () => {
    setSortDescriptor((prevSort) => {
      const isActive = column === prevSort?.column;
      const direction =
        isActive && prevSort?.direction === 'ascending'
          ? 'descending'
          : 'ascending';
      return { column, direction };
    });
  },
  []
);
// gets the appropriate `aria-sort` attribute by column key
const getSortDirection = React.useCallback(
  (column) => {
    if (sortDescriptor) {
      return sortDescriptor.column === column
        ? sortDescriptor.direction
        : undefined;
    }
  },
  [sortDescriptor]
);
// resolve rows when the sort descriptor changes
const sortedRows = React.useMemo(() => {
  if (sortDescriptor) {
    return defaultRows.sort(createDefaultSort(sortDescriptor));
  }
  return defaultRows;
}, [defaultRows, sortDescriptor]);
return (
  <Box overflowX="auto" height={300}>
    <Table aria-label="Example with sorting" density="compact">
      <TableHeader stickyOffset={0}>
        <TableColumnHeader
          onClick={createSortHandler('first_name')}
          aria-sort={getSortDirection('first_name')}
        >
          Name
        </TableColumnHeader>
        <TableColumnHeader
          onClick={createSortHandler('email')}
          aria-sort={getSortDirection('email')}
        >
          Email
        </TableColumnHeader>
        <TableColumnHeader
          width={160}
          align="right"
          onClick={createSortHandler('income')}
          aria-sort={getSortDirection('income')}
        >
          Income
        </TableColumnHeader>
        <TableColumnHeader width={60} align="right">
          <VisuallyHidden>Row actions</VisuallyHidden>
        </TableColumnHeader>
      </TableHeader>
      <TableBody>
        {sortedRows.map((item) => (
          <TableRow key={item.id}>
            <TableCell role="rowheader">
              {`${item.first_name} ${item.last_name}`}
            </TableCell>
            <TableCell>{item.email}</TableCell>
            <TableCell width={160} align="right">
              {formatCurrency(item.income)}
            </TableCell>
            <TableCell width={60} align="right">
              <IconButton
                icon={MoreHorizontalIcon}
                label="Actions"
                size="small"
                colorScheme="tertiary"
                variant="text"
              />
            </TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  </Box>
);

Default Sort

The table package exposes a createDefaultSort utility, which will handle most sorting cases.

type SortDescriptor = {
  column: string;
  direction: 'ascending' | 'descending';
};

The utility takes a SortDescriptor as its only argument and returns a compare function that should be provided to the sort method of your data array.

const rowData = [
  { name: 'Brig Joderli', email: 'bjoderli0@nymag.com', },
  { name: 'Jill Rowledge', email: 'jrowledge1@amazon.co.uk', },
];
rowData.sort(createDefaultSort({
  column: 'name';
  direction: 'descending';
}));

Selection

Use the TableSelectionCell to implement checkbox selection of rows—internally it composes a TableCell of standard width and checkbox for consistent appearance and behaviour across products.

Edit in Playroom

const getCheckedState = React.useCallback((selected, total) => {
  if (selected === 0) return false;
  if (selected === total) return true;
  return 'mixed';
}, []);
const rows = React.useMemo(() => getData(20), []);
const [selectedIds, setSelectedIds] = React.useState([]);
const allChecked = getCheckedState(selectedIds.length, rows.length);
const allSelectionHandler = React.useCallback(() => {
  setSelectedIds((prev) => {
    const all = getCheckedState(prev.length, rows.length);
    return all === true ? [] : rows.map((r) => r.id.toString());
  });
}, [rows]);
const rowSelectionHandler = React.useCallback((event) => {
  const rowId = event.target.name;
  setSelectedIds((prev) => {
    if (prev.includes(rowId)) {
      return prev.filter((existingId) => existingId !== rowId);
    }
    return [...prev, rowId];
  });
}, []);
const tones = ['neutral', 'informative', 'positive', 'cautious', 'critical'];
return (
  <Stack gap="small">
    <Inline gap="small" alignY="center">
      <Text size="small" weight="medium">
        Selected rows
      </Text>
      <Badge
        tone={tones[Math.round(selectedIds.length / tones.length)]}
        label={selectedIds.length}
      />
    </Inline>
    <Box overflow="auto" height={300}>
      <Table aria-label="Example with selection">
        <TableHeader stickyOffset={0}>
          <TableSelectionCell
            role="columnheader"
            aria-label="Select all"
            checked={allChecked}
            onChange={allSelectionHandler}
          />
          <TableColumnHeader>Name</TableColumnHeader>
          <TableColumnHeader>Email</TableColumnHeader>
          <TableColumnHeader width={160} align="right">
            Income
          </TableColumnHeader>
        </TableHeader>
        <TableBody>
          {rows.map((item) => {
            const stringId = item.id.toString();
            const selected = selectedIds.includes(stringId);
            const fullName = `${item.first_name} ${item.last_name}`;
            return (
              <TableRow key={item.id}>
                <TableSelectionCell
                  aria-label={`Select ${fullName}`}
                  name={stringId}
                  onChange={rowSelectionHandler}
                  checked={selected}
                />
                <TableCell role="rowheader">{fullName}</TableCell>
                <TableCell>{item.email}</TableCell>
                <TableCell width={160} align="right">
                  {formatCurrency(item.income)}
                </TableCell>
              </TableRow>
            );
          })}
        </TableBody>
      </Table>
    </Box>
  </Stack>
);

Indeterminate state

The indeterminate state of a checkbox input element is controlled by JavaScript, not HTML attribution. To make things more declarative and less confusing Balance checkboxes accept a "tri-state"; the checked value for a checkbox may be true | false | 'mixed', where "mixed" indicates an indeterminate state aligning with the aria-checked attribute.

Conditional elements

Some tables may have many columns and/or many rows. Loading a subset of columns or rows, via mechanisms like virtualization and pagination, can improve performance and user experience.

Edit in Playroom

// column configuration
const columnConstants = {
  name: { label: 'Name', minWidth: 200 },
  email: { label: 'Email', minWidth: 240 },
  createdDate: { label: 'Created', width: 140 },
  status: { label: 'Status', width: 120 },
  notes: { label: 'Notes', minWidth: 240, maxWidth: 420 },
  income: { label: 'Income', width: 160, align: 'right' },
  super: { label: 'Super', width: 160, align: 'right' },
  tax: { label: 'Tax', width: 160, align: 'right' },
};
const makeMenuOptions = (keys) => {
  return keys.map((key) => ({
    value: key,
    label: columnConstants[key].label,
    disabled: key === 'name',
  }));
};
// page prep
const rowsPerPage = 5;
const defaultRows = React.useMemo(() => getData(25), []);
const [page, setPage] = useState(0);
const totalPages = defaultRows.length / rowsPerPage;
const tableDescriptionId = 'table-description';
const rows = React.useMemo(() => {
  const from = page * rowsPerPage;
  const to = from + rowsPerPage;
  return defaultRows.slice(from, to);
}, [defaultRows, page]);
// column prep
const [keyOrder, setKeyOrder] = useState(Object.keys(columnConstants));
const [visibleKeys, setVisibleKeys] = useState(['name', 'email', 'income']);
const menuOptions = React.useMemo(() => makeMenuOptions(keyOrder), [keyOrder]);
const visibleCount = visibleKeys.length;
const totalCount = keyOrder.length;
const visibleLabel =
  visibleCount === totalCount ? 'All' : `${visibleCount} of ${totalCount}`;
const onReorder = React.useCallback((options) => {
  setKeyOrder(options.map((opt) => opt.value));
}, []);
// helpers
const getBodyRowIndex = React.useCallback(
  (index) => {
    const floor = page * rowsPerPage;
    // NOTE: +2 accounts for the table's header row (aria indexes are one-based)
    return floor + index + 2;
  },
  [page]
);
return (
  <Stack>
    <Inline gap="medium">
      <ConfigMenu
        trigger={`${visibleLabel} columns`}
        hasValue={visibleKeys.length > 0}
        selectionCount={visibleKeys.length}
      >
        <ConfigMenuGroup
          title="Manage columns"
          onChange={setVisibleKeys}
          onReorder={onReorder}
          options={makeMenuOptions(keyOrder)}
          value={visibleKeys}
        />
      </ConfigMenu>
      <Inline gap="small" alignY="center">
        <Text
          size="small"
          weight="medium"
          id={tableDescriptionId}
          tabularNumbers
        >
          Page {page + 1} of {totalPages}
        </Text>
        <IconButton
          size="small"
          label="Previous page"
          variant="text"
          icon={ChevronLeftIcon}
          disabled={page === 0}
          onClick={() => {
            setPage((p) => p - 1);
          }}
        />
        <IconButton
          size="small"
          label="Next page"
          variant="text"
          icon={ChevronRightIcon}
          disabled={page === 4}
          onClick={() => {
            setPage((p) => p + 1);
          }}
        />
      </Inline>
    </Inline>
    <Box overflowX="auto">
      <Table
        aria-label="Example with pagination and dynamic columns"
        aria-describedby={tableDescriptionId}
        // NOTE: the extra row accounts for the table's header row
        aria-rowcount={defaultRows.length + 1}
        aria-colcount={totalCount}
        alignY="top"
      >
        <TableHead stickyOffset={0}>
          {/* manually assign the table header row index */}
          <TableRow aria-rowindex={1}>
            {keyOrder.map((key, colIndex) => {
              if (visibleKeys.indexOf(key) === -1) {
                return null;
              }
              const column = columnConstants[key];
              return (
                <TableColumnHeader
                  key={key}
                  aria-colindex={colIndex + 1}
                  align={column.align}
                  minWidth={column.minWidth}
                  maxWidth={column.maxWidth}
                  width={column.width}
                >
                  {column.label}
                </TableColumnHeader>
              );
            })}
          </TableRow>
        </TableHead>
        <TableBody>
          {rows.map((item, rowIndex) => {
            return (
              <TableRow key={item.id} aria-rowindex={getBodyRowIndex(rowIndex)}>
                {keyOrder.map((key, colIndex) => {
                  if (visibleKeys.indexOf(key) === -1) {
                    return null;
                  }
                  const column = columnConstants[key];
                  return (
                    <TableCell
                      key={key}
                      aria-colindex={colIndex + 1}
                      role={colIndex === 0 ? 'rowheader' : undefined}
                      align={column.align}
                      minWidth={column.minWidth}
                      maxWidth={column.maxWidth}
                      width={column.width}
                    >
                      {(() => {
                        switch (key) {
                          case 'name':
                            return `${item.first_name} ${item.last_name}`;
                          case 'income':
                          case 'super':
                          case 'tax':
                            return formatCurrency(item[key]);
                          case 'notes':
                            return <Text numberOfLines={2}>{item[key]}</Text>;
                          default:
                            return item[key];
                        }
                      })()}
                    </TableCell>
                  );
                })}
              </TableRow>
            );
          })}
        </TableBody>
      </Table>
    </Box>
  </Stack>
);

Low-level primitives

The TableHeader and TableFooter are provided as convenience components for the most common cases. Internally they compose the TableHead and TableFoot with TableRow, which are exposed for cases like conditionally rendered elements.

<TableHead>
  <TableRow>
    ...
  </TableRow>
</TableHead>
...
<TableFoot>
  <TableRow>
    ...
  </TableRow>
</TableFoot>

Conditional rows

When only a subset of rows are loaded, you need to let all users know which rows are being displayed.

On the Table, use the aria-rowcount attribute to let assistive technologies know how many rows the table would have if all rows were present. For paginated results, consider providing an aria-description or aria-describedby attribute to announced the current state.

On the TableRow, use the aria-rowindex attribute to let assistive technologies know where each row is in relation to the total possible rows.

Conditional columns

When only a subset of rows are loaded, you need to let all users know which columns are being displayed.

On the Table, use the aria-colcount attribute to let assistive technologies know how many columns the table would have if all columns were present.

On the TableCell and TableColumnHeader, use the aria-colindex attribute to let assistive technologies know where each column is in relation to the total possible columns.

Groups

Groups are non-standard table structure and should be used sparingly.

Tables that implement groups have no TableBody, instead a number of TableGroup components should be rendered as siblings of the TableHeader.

The TableGroupHeader must be given an aria-colspan matching the total number of columns.

Edit in Playroom

const companyData = React.useMemo(() => {
  const companyKeys = [
    'Babbleopia',
    'Feedspan',
    'Jetpulse',
    'Skynoodle',
    'Zoomdog',
  ];
  return companyKeys.map((name) => {
    const items = getData(1000).filter((entry) => entry.company === name);
    return { name, items };
  });
}, []);
const headerRenderer = React.useCallback(
  (name) => ({ expanded, triggerProps }) => {
    const Indicator = expanded ? ChevronUpIcon : ChevronDownIcon;
    return (
      <TableGroupHeader aria-colspan={3}>
        <Box as="h3">
          <Inline
            as="button"
            type="button"
            gap="small"
            alignItems="center"
            {...triggerProps}
          >
            <Indicator color="base" size="small" />
            <Text weight="bold">{name}</Text>
          </Inline>
        </Box>
      </TableGroupHeader>
    );
  },
  []
);
return (
  <Table aria-label="Example with groups">
    <TableHeader>
      <TableColumnHeader>Name</TableColumnHeader>
      <TableColumnHeader>Email</TableColumnHeader>
      <TableColumnHeader width={140} align="right">
        Income
      </TableColumnHeader>
    </TableHeader>
    {companyData.map(({ name, items }, index) => {
      return (
        <TableGroup header={headerRenderer(name)} initialExpanded={index === 0}>
          {items.map((row) => (
            <TableRow>
              <TableCell>{`${row.first_name} ${row.last_name}`}</TableCell>
              <TableCell>{row.email}</TableCell>
              <TableCell width={140} align="right">
                {formatCurrency(row.income)}
              </TableCell>
            </TableRow>
          ))}
        </TableGroup>
      );
    })}
  </Table>
);

Empty state

The TableEmptyState component can be used instead of TableBody when there is no data available.

Edit in Playroom

<Table aria-label="Empty table example">
  <TableHeader>
    <TableColumnHeader>Name</TableColumnHeader>
    <TableColumnHeader>Type</TableColumnHeader>
    <TableColumnHeader>Date modified</TableColumnHeader>
  </TableHeader>
  <TableEmptyState>
    <Stack gap="medium" align="center">
      <Heading level="4">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>
  </TableEmptyState>
</Table>