alpha

useTable

Provides the behavior and accessibility implementation for a table component. A table displays data in one or more rows and columns and enables a user to navigate its contents via directional navigation keys.

install	`yarn add @react-aria/table`
version	3.0.0-alpha.11
usage	`import {useTable, useTableCell, useTableColumnHeader, useTableRow, useTableRowGroup, useTableRowHeader, useTableSelectAllCheckbox, useTableSelectionCheckbox} from '@react-aria/table'`

View ARIA spec

API#

useTable<T>(
  (props: TableProps<T>,
  , state: TableState<T>
)): GridAria

useTableColumnHeader<T>(
  (props: ColumnHeaderProps,
  , state: TableState<T>
)): ColumnHeaderAria

useTableRow<T>(
  (props: GridRowProps<T>,
  , state: TableState<T>
)): GridRowAria

useTableRowGroup(): GridRowGroupAria

useTableRowHeader<T>(
  (props: RowHeaderProps,
  , state: TableState<T>
)): RowHeaderAria

useTableCell<T, C>(
  (props: GridCellProps,
  , state: GridState<T, C>
)): GridCellAria

useTableSelectionCheckbox<T>(
  (props: SelectionCheckboxProps,
  , state: TableState<T>
)): SelectionCheckboxAria

useTableSelectAllCheckbox<T>(
  (state: TableState<T>
)): SelectAllCheckboxAria

Features#

A table can be built using the <table>, <thead>, <tbody>, and other table specific HTML elements, but is very limited in functionality especially when it comes to user interactions. useTable helps achieve accessible and interactive table components that can be styled as needed.

Exposed to assistive technology as a grid using ARIA
Support for single, multiple, or no row selection
Support for disabled rows
Labeling support for accessibility
Support for mouse, touch, and keyboard interactions
Support for keyboard navigation between columns, rows, cells, and in-cell focusable items
Column sorting
Multiple row header support
Automatic scrolling support during keyboard navigation
Typeahead to allow focusing rows by typing text
Virtualized scrolling support for performance with large tables

Anatomy#

A table consists of a container element, with columns and rows of cells containing data inside. The cells within a table may contain focusable elements or plain text content. If the table supports row selection, each row includes a selection checkbox in the first column. Additionally, a "select all" checkbox is displayed as the first column header if the table supports multiple row selection.

useTable, useTableCell, useTableColumnHeader, useTableRow, and useTableRowHeader handle keyboard, mouse, and other interactions to support row selection, in table navigation, and overall focus behavior. Those hooks, along with useTableRowGroup, also handle exposing the table and its contents to assistive technology using ARIA. useTableSelectAllCheckbox and useTableSelectionCheckbox handle row selection and associating each checkbox with its respective rows for assistive technology.

useTable returns props that you should spread onto the table container element:

Name	Type	Description
`gridProps`	`HTMLAttributes<HTMLElement>`	Props for the grid element.

useTableColumnHeader returns props for an individual table column header:

Name	Type	Description
`columnHeaderProps`	`HTMLAttributes<HTMLElement>`	Props for the column header element.

useTableRow returns props for an individual table row:

Name	Type	Description
`rowProps`	`HTMLAttributes<HTMLElement>`	Props for the grid row element.

useTableRowGroup returns props for a element containing one or more rows of column headers or cells. This is often equivalent to the header, body, and footer of the table:

Name	Type	Description
`rowGroupProps`	`HTMLAttributes<HTMLElement>`	Props for the row group element.

useTableRowHeader returns props for the table cell that serves as a row's header:

Name	Type	Description
`rowHeaderProps`	`HTMLAttributes<HTMLElement>`	Props for the row header element.

useTableCell returns props for an individual table cell:

Name	Type	Description
`gridCellProps`	`HTMLAttributes<HTMLElement>`	Props for the grid cell element.

useTableSelectionCheckbox returns props for an individual table row selection checkbox:

Name	Type	Description
`checkboxProps`	`AriaCheckboxProps`	Props for the row selection checkbox element.

useTableSelectAllCheckbox returns props for the table's "select all" checkbox:

Name	Type	Description
`checkboxProps`	`AriaCheckboxProps`	Props for the select all checkbox element.

State is managed by the useTableState hook from @react-stately/table. The state object should be passed as an option to each of the above hooks where applicable.

Note that an aria-label or aria-labelledby must be passed to the table to identify the element to assistive technology.

State management#

useTable requires knowledge of the rows, cells, and columns in the table in order to handle keyboard navigation and other interactions. It does this using the Collection interface, which is a generic interface to access sequential unique keyed data. You can implement this interface yourself, e.g. by using a prop to pass a list of item objects, but useTableState from @react-stately/table implements a JSX based interface for building collections instead. See Collection Components for more information, and Collection Interface for internal details.

In addition, useTableState manages the state necessary for multiple selection and exposes a SelectionManager, which makes use of the collection to provide an interface to update the selection state. For more information, see Selection.

Example#

This example uses HTML <div> elements to construct the table. It uses useTableState to construct the table's collection of rows and columns, applying the appropriate attributes to each <div> using the various table hooks listed above paired with the div's role in the table. The table follows the Collection Components API, accepting both static and dynamic collections.

The example below shows a static collection, which can be used when the full set of table contents is known ahead of time. Be sure to note the usage of Cell, Column, Row, TableBody, and TableHeader to construct the table structure. These elements are similar to Item and Section used in other components following the Collection Components API mentioned previously, serving as node generators for the table collection. See useTableState for more info on the props they support.

import {
  Cell,
  Column,
  Row,
  TableBody,
  TableHeader,
  useTableState
} from '@react-stately/table';
import {mergeProps} from '@react-aria/utils';
import {useCheckbox} from '@react-aria/checkbox';
import {useContext, useRef} from 'react';
import {useFocusRing} from '@react-aria/focus';
import {useToggleState} from '@react-stately/toggle';
const TableContext = React.createContext(null);
function useTableContext() {
  return useContext(TableContext);
}
function Table(props) {
  let state = useTableState({...props, showSelectionCheckboxes: true});
  let ref = useRef();
  let scrollViewRef = useRef();
  let {collection} = state;
  let {gridProps} = useTable(
    {
      ...props,
      ref: ref
    },
    state
  );
  let headerRows = collection.rows.filter(
    (item) => item.type === 'headerrow' && item
  );
  let rows = collection.rows.filter((item) => item.type === 'item' && item);
  let renderColumnNode = (node) => {
    if (node.props.isSelectionCell) {
      return <TableSelectAllCell column={node} />;
    }
    return <TableColumnHeader column={node} />;
  };
  let renderRowNode = (node) => {
    if (node.props.isSelectionCell) {
      return <TableCheckboxCell cell={node} />;
    }
    if (collection.rowHeaderColumnKeys.has(node.column.key)) {
      return <TableRowHeader cell={node} />;
    }
    return <TableCell cell={node} />;
  };
  return (
    <TableContext.Provider value={state}>
      <div
        {...gridProps}
        style={{...props.style, display: 'flex', flexDirection: 'column'}}
        ref={ref}>
        <TableHeaderGroup>
          {[...headerRows].map((headerRow) => (
            <TableHeaderRow item={headerRow}>
              {[...headerRow.childNodes].map((column) =>
                renderColumnNode(column)
              )}
            </TableHeaderRow>
          ))}
        </TableHeaderGroup>
        <div
          style={{
            borderTop: '2px solid black',
            borderBottom: '2px solid black',
            padding: '0px 1px 0px 1px',
            flex: '1 1 0%',
            overflow: 'auto'
          }}>
          <TableRowGroup>
            {[...rows].map((row) => (
              <TableRow item={row}>
                {[...row.childNodes].map((node) => renderRowNode(node))}
              </TableRow>
            ))}
          </TableRowGroup>
        </div>
      </div>
    </TableContext.Provider>
  );
}
function TableHeaderGroup({children, ...otherProps}) {
  let {rowGroupProps} = useTableRowGroup();
  return (
    <div {...rowGroupProps} {...otherProps}>
      {children}
    </div>
  );
}
function TableColumnHeader({column}) {
  let ref = useRef();
  let state = useTableContext();
  let {columnHeaderProps} = useTableColumnHeader(
    {
      node: column,
      ref,
      colspan: column.colspan
    },
    state
  );
  let {isFocusVisible, focusProps} = useFocusRing();
  let columnProps = column.props;
  let arrowIcon = state.sortDescriptor?.direction === 'ascending' ? '▲' : '▼';
  return (
    <div
      {...mergeProps(columnHeaderProps, focusProps)}
      style={{
        height: '16px',
        lineHeight: '16px',
        width: '100px',
        padding: '10px 10px 10px 10px',
        outline: isFocusVisible ? '2px solid -webkit-focus-ring-color' : 'none'
      }}
      ref={ref}>
      {column.rendered}
      {columnProps.allowsSorting &&
        state.sortDescriptor?.column === column.key && (
          <span aria-hidden="true" style={{padding: '0 2px'}}>
            {arrowIcon}
          </span>
        )}
    </div>
  );
}
function TableSelectAllCell({column}) {
  let ref = useRef();
  let state = useTableContext();
  let isSingleSelectionMode = state.selectionManager.selectionMode === 'single';
  let {columnHeaderProps} = useTableColumnHeader(
    {
      node: column,
      ref,
      colspan: column.colspan,
      isDisabled: isSingleSelectionMode
    },
    state
  );
  let {checkboxProps} = useTableSelectAllCheckbox(state);
  let inputRef = useRef(null);
  let {inputProps} = useCheckbox(
    checkboxProps,
    useToggleState(checkboxProps),
    inputRef
  );
  return (
    <div
      {...columnHeaderProps}
      style={{
        height: '16px',
        padding: '10px 10px 10px 10px'
      }}
      aria-disabled={isSingleSelectionMode}
      ref={ref}>
      <input
        {...inputProps}
        ref={inputRef}
        disabled={isSingleSelectionMode}
        style={{visibility: isSingleSelectionMode ? 'hidden' : 'visible'}}
      />
    </div>
  );
}
function TableRowGroup({children, ...otherProps}) {
  let {rowGroupProps} = useTableRowGroup();
  return (
    <div {...rowGroupProps} {...otherProps}>
      {children}
    </div>
  );
}
function TableRow({item, children, ...otherProps}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(item.key);
  let isSelected = state.selectionManager.isSelected(item.key) && !isDisabled;
  let {rowProps} = useTableRow(
    {
      node: item,
      isSelected,
      ref,
      isDisabled
    },
    state
  );
  let props = mergeProps(rowProps, otherProps);
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'row',
        padding: '1px 1px 2px 1px',
        borderTop: '1px solid lightgrey'
      }}
      {...props}
      ref={ref}>
      {children}
    </div>
  );
}
function TableHeaderRow({item, children, ...otherProps}) {
  return (
    <div
      role="row"
      aria-rowindex={item.index + 1}
      {...otherProps}
      style={{display: 'flex', flexDirection: 'row', paddingBottom: '4px'}}>
      {children}
    </div>
  );
}
function TableCheckboxCell({cell}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(cell.parentKey);
  let {gridCellProps} = useTableCell(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  let {checkboxProps} = useTableSelectionCheckbox(
    {
      key: cell.parentKey,
      isDisabled
    },
    state
  );
  let inputRef = useRef(null);
  let {inputProps} = useCheckbox(
    {...checkboxProps, isDisabled},
    useToggleState(checkboxProps),
    inputRef
  );
  return (
    <div
      {...gridCellProps}
      style={{
        height: '16px',
        padding: '10px 10px 10px 10px'
      }}
      ref={ref}>
      {state.selectionManager.selectionMode !== 'none' && (
        <input {...inputProps} />
      )}
    </div>
  );
}
function TableCell({cell}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(cell.parentKey);
  let {gridCellProps} = useTableCell(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  return <TableCellBase {...gridCellProps} cell={cell} cellRef={ref} />;
}
function TableRowHeader({cell}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(cell.parentKey);
  let {rowHeaderProps} = useTableRowHeader(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  return <TableCellBase {...rowHeaderProps} cell={cell} cellRef={ref} />;
}
function TableCellBase({cell, cellRef, ...otherProps}) {
  let {isFocusVisible, focusProps} = useFocusRing();
  return (
    <div
      {...mergeProps(otherProps, focusProps)}
      style={{
        height: '16px',
        lineHeight: '16px',
        width: '100px',
        padding: '10px 10px 10px 10px',
        outline: isFocusVisible ? '2px solid -webkit-focus-ring-color' : 'none'
      }}
      ref={cellRef}>
      <span
        style={{
          overflow: 'hidden',
          whiteSpace: 'nowrap',
          textOverflow: 'ellipsis'
        }}>
        {cell.rendered}
      </span>
    </div>
  );
}
<Table
  aria-label="Example static collection table"
  style={{height: '210px', maxWidth: '400px'}}>
  <TableHeader>
    <Column>Name</Column>
    <Column>Type</Column>
    <Column>Date Modified</Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>Games</Cell>
      <Cell>File folder</Cell>
      <Cell>6/7/2020</Cell>
    </Row>
    <Row>
      <Cell>Program Files</Cell>
      <Cell>File folder</Cell>
      <Cell>4/7/2021</Cell>
    </Row>
    <Row>
      <Cell>bootmgr</Cell>
      <Cell>System file</Cell>
      <Cell>11/20/2010</Cell>
    </Row>
    <Row>
      <Cell>log.txt</Cell>
      <Cell>Text Document</Cell>
      <Cell>1/18/2016</Cell>
    </Row>
  </TableBody>
</Table>

import {
  Cell,
  Column,
  Row,
  TableBody,
  TableHeader,
  useTableState
} from '@react-stately/table';
import {mergeProps} from '@react-aria/utils';
import {useCheckbox} from '@react-aria/checkbox';
import {useContext, useRef} from 'react';
import {useFocusRing} from '@react-aria/focus';
import {useToggleState} from '@react-stately/toggle';
const TableContext = React.createContext(null);
function useTableContext() {
  return useContext(TableContext);
}
function Table(props) {
  let state = useTableState({
    ...props,
    showSelectionCheckboxes: true
  });
  let ref = useRef();
  let scrollViewRef = useRef();
  let {collection} = state;
  let {gridProps} = useTable(
    {
      ...props,
      ref: ref
    },
    state
  );
  let headerRows = collection.rows.filter(
    (item) => item.type === 'headerrow' && item
  );
  let rows = collection.rows.filter(
    (item) => item.type === 'item' && item
  );
  let renderColumnNode = (node) => {
    if (node.props.isSelectionCell) {
      return <TableSelectAllCell column={node} />;
    }
    return <TableColumnHeader column={node} />;
  };
  let renderRowNode = (node) => {
    if (node.props.isSelectionCell) {
      return <TableCheckboxCell cell={node} />;
    }
    if (
      collection.rowHeaderColumnKeys.has(node.column.key)
    ) {
      return <TableRowHeader cell={node} />;
    }
    return <TableCell cell={node} />;
  };
  return (
    <TableContext.Provider value={state}>
      <div
        {...gridProps}
        style={{
          ...props.style,
          display: 'flex',
          flexDirection: 'column'
        }}
        ref={ref}>
        <TableHeaderGroup>
          {[...headerRows].map((headerRow) => (
            <TableHeaderRow item={headerRow}>
              {[...headerRow.childNodes].map((column) =>
                renderColumnNode(column)
              )}
            </TableHeaderRow>
          ))}
        </TableHeaderGroup>
        <div
          style={{
            borderTop: '2px solid black',
            borderBottom: '2px solid black',
            padding: '0px 1px 0px 1px',
            flex: '1 1 0%',
            overflow: 'auto'
          }}>
          <TableRowGroup>
            {[...rows].map((row) => (
              <TableRow item={row}>
                {[...row.childNodes].map((node) =>
                  renderRowNode(node)
                )}
              </TableRow>
            ))}
          </TableRowGroup>
        </div>
      </div>
    </TableContext.Provider>
  );
}
function TableHeaderGroup({children, ...otherProps}) {
  let {rowGroupProps} = useTableRowGroup();
  return (
    <div {...rowGroupProps} {...otherProps}>
      {children}
    </div>
  );
}
function TableColumnHeader({column}) {
  let ref = useRef();
  let state = useTableContext();
  let {columnHeaderProps} = useTableColumnHeader(
    {
      node: column,
      ref,
      colspan: column.colspan
    },
    state
  );
  let {isFocusVisible, focusProps} = useFocusRing();
  let columnProps = column.props;
  let arrowIcon =
    state.sortDescriptor?.direction === 'ascending'
      ? '▲'
      : '▼';
  return (
    <div
      {...mergeProps(columnHeaderProps, focusProps)}
      style={{
        height: '16px',
        lineHeight: '16px',
        width: '100px',
        padding: '10px 10px 10px 10px',
        outline: isFocusVisible
          ? '2px solid -webkit-focus-ring-color'
          : 'none'
      }}
      ref={ref}>
      {column.rendered}
      {columnProps.allowsSorting &&
        state.sortDescriptor?.column === column.key && (
          <span
            aria-hidden="true"
            style={{padding: '0 2px'}}>
            {arrowIcon}
          </span>
        )}
    </div>
  );
}
function TableSelectAllCell({column}) {
  let ref = useRef();
  let state = useTableContext();
  let isSingleSelectionMode =
    state.selectionManager.selectionMode === 'single';
  let {columnHeaderProps} = useTableColumnHeader(
    {
      node: column,
      ref,
      colspan: column.colspan,
      isDisabled: isSingleSelectionMode
    },
    state
  );
  let {checkboxProps} = useTableSelectAllCheckbox(state);
  let inputRef = useRef(null);
  let {inputProps} = useCheckbox(
    checkboxProps,
    useToggleState(checkboxProps),
    inputRef
  );
  return (
    <div
      {...columnHeaderProps}
      style={{
        height: '16px',
        padding: '10px 10px 10px 10px'
      }}
      aria-disabled={isSingleSelectionMode}
      ref={ref}>
      <input
        {...inputProps}
        ref={inputRef}
        disabled={isSingleSelectionMode}
        style={{
          visibility: isSingleSelectionMode
            ? 'hidden'
            : 'visible'
        }}
      />
    </div>
  );
}
function TableRowGroup({children, ...otherProps}) {
  let {rowGroupProps} = useTableRowGroup();
  return (
    <div {...rowGroupProps} {...otherProps}>
      {children}
    </div>
  );
}
function TableRow({item, children, ...otherProps}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(item.key);
  let isSelected =
    state.selectionManager.isSelected(item.key) &&
    !isDisabled;
  let {rowProps} = useTableRow(
    {
      node: item,
      isSelected,
      ref,
      isDisabled
    },
    state
  );
  let props = mergeProps(rowProps, otherProps);
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'row',
        padding: '1px 1px 2px 1px',
        borderTop: '1px solid lightgrey'
      }}
      {...props}
      ref={ref}>
      {children}
    </div>
  );
}
function TableHeaderRow({item, children, ...otherProps}) {
  return (
    <div
      role="row"
      aria-rowindex={item.index + 1}
      {...otherProps}
      style={{
        display: 'flex',
        flexDirection: 'row',
        paddingBottom: '4px'
      }}>
      {children}
    </div>
  );
}
function TableCheckboxCell({cell}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(cell.parentKey);
  let {gridCellProps} = useTableCell(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  let {checkboxProps} = useTableSelectionCheckbox(
    {
      key: cell.parentKey,
      isDisabled
    },
    state
  );
  let inputRef = useRef(null);
  let {inputProps} = useCheckbox(
    {...checkboxProps, isDisabled},
    useToggleState(checkboxProps),
    inputRef
  );
  return (
    <div
      {...gridCellProps}
      style={{
        height: '16px',
        padding: '10px 10px 10px 10px'
      }}
      ref={ref}>
      {state.selectionManager.selectionMode !== 'none' && (
        <input {...inputProps} />
      )}
    </div>
  );
}
function TableCell({cell}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(cell.parentKey);
  let {gridCellProps} = useTableCell(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  return (
    <TableCellBase
      {...gridCellProps}
      cell={cell}
      cellRef={ref}
    />
  );
}
function TableRowHeader({cell}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(cell.parentKey);
  let {rowHeaderProps} = useTableRowHeader(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  return (
    <TableCellBase
      {...rowHeaderProps}
      cell={cell}
      cellRef={ref}
    />
  );
}
function TableCellBase({cell, cellRef, ...otherProps}) {
  let {isFocusVisible, focusProps} = useFocusRing();
  return (
    <div
      {...mergeProps(otherProps, focusProps)}
      style={{
        height: '16px',
        lineHeight: '16px',
        width: '100px',
        padding: '10px 10px 10px 10px',
        outline: isFocusVisible
          ? '2px solid -webkit-focus-ring-color'
          : 'none'
      }}
      ref={cellRef}>
      <span
        style={{
          overflow: 'hidden',
          whiteSpace: 'nowrap',
          textOverflow: 'ellipsis'
        }}>
        {cell.rendered}
      </span>
    </div>
  );
}
<Table
  aria-label="Example static collection table"
  style={{height: '210px', maxWidth: '400px'}}>
  <TableHeader>
    <Column>Name</Column>
    <Column>Type</Column>
    <Column>Date Modified</Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>Games</Cell>
      <Cell>File folder</Cell>
      <Cell>6/7/2020</Cell>
    </Row>
    <Row>
      <Cell>Program Files</Cell>
      <Cell>File folder</Cell>
      <Cell>4/7/2021</Cell>
    </Row>
    <Row>
      <Cell>bootmgr</Cell>
      <Cell>System file</Cell>
      <Cell>11/20/2010</Cell>
    </Row>
    <Row>
      <Cell>log.txt</Cell>
      <Cell>Text Document</Cell>
      <Cell>1/18/2016</Cell>
    </Row>
  </TableBody>
</Table>

import {
  Cell,
  Column,
  Row,
  TableBody,
  TableHeader,
  useTableState
} from '@react-stately/table';
import {mergeProps} from '@react-aria/utils';
import {useCheckbox} from '@react-aria/checkbox';
import {
  useContext,
  useRef
} from 'react';
import {useFocusRing} from '@react-aria/focus';
import {useToggleState} from '@react-stately/toggle';
const TableContext = React.createContext(
  null
);
function useTableContext() {
  return useContext(
    TableContext
  );
}
function Table(props) {
  let state = useTableState(
    {
      ...props,
      showSelectionCheckboxes: true
    }
  );
  let ref = useRef();
  let scrollViewRef = useRef();
  let {
    collection
  } = state;
  let {
    gridProps
  } = useTable(
    {
      ...props,
      ref: ref
    },
    state
  );
  let headerRows = collection.rows.filter(
    (item) =>
      item.type ===
        'headerrow' &&
      item
  );
  let rows = collection.rows.filter(
    (item) =>
      item.type ===
        'item' && item
  );
  let renderColumnNode = (
    node
  ) => {
    if (
      node.props
        .isSelectionCell
    ) {
      return (
        <TableSelectAllCell
          column={node}
        />
      );
    }
    return (
      <TableColumnHeader
        column={node}
      />
    );
  };
  let renderRowNode = (
    node
  ) => {
    if (
      node.props
        .isSelectionCell
    ) {
      return (
        <TableCheckboxCell
          cell={node}
        />
      );
    }
    if (
      collection.rowHeaderColumnKeys.has(
        node.column.key
      )
    ) {
      return (
        <TableRowHeader
          cell={node}
        />
      );
    }
    return (
      <TableCell
        cell={node}
      />
    );
  };
  return (
    <TableContext.Provider
      value={state}>
      <div
        {...gridProps}
        style={{
          ...props.style,
          display:
            'flex',
          flexDirection:
            'column'
        }}
        ref={ref}>
        <TableHeaderGroup>
          {[
            ...headerRows
          ].map(
            (
              headerRow
            ) => (
              <TableHeaderRow
                item={
                  headerRow
                }>
                {[
                  ...headerRow.childNodes
                ].map(
                  (
                    column
                  ) =>
                    renderColumnNode(
                      column
                    )
                )}
              </TableHeaderRow>
            )
          )}
        </TableHeaderGroup>
        <div
          style={{
            borderTop:
              '2px solid black',
            borderBottom:
              '2px solid black',
            padding:
              '0px 1px 0px 1px',
            flex:
              '1 1 0%',
            overflow:
              'auto'
          }}>
          <TableRowGroup>
            {[
              ...rows
            ].map(
              (row) => (
                <TableRow
                  item={
                    row
                  }>
                  {[
                    ...row.childNodes
                  ].map(
                    (
                      node
                    ) =>
                      renderRowNode(
                        node
                      )
                  )}
                </TableRow>
              )
            )}
          </TableRowGroup>
        </div>
      </div>
    </TableContext.Provider>
  );
}
function TableHeaderGroup({
  children,
  ...otherProps
}) {
  let {
    rowGroupProps
  } = useTableRowGroup();
  return (
    <div
      {...rowGroupProps}
      {...otherProps}>
      {children}
    </div>
  );
}
function TableColumnHeader({
  column
}) {
  let ref = useRef();
  let state = useTableContext();
  let {
    columnHeaderProps
  } = useTableColumnHeader(
    {
      node: column,
      ref,
      colspan:
        column.colspan
    },
    state
  );
  let {
    isFocusVisible,
    focusProps
  } = useFocusRing();
  let columnProps =
    column.props;
  let arrowIcon =
    state.sortDescriptor
      ?.direction ===
    'ascending'
      ? '▲'
      : '▼';
  return (
    <div
      {...mergeProps(
        columnHeaderProps,
        focusProps
      )}
      style={{
        height: '16px',
        lineHeight:
          '16px',
        width: '100px',
        padding:
          '10px 10px 10px 10px',
        outline: isFocusVisible
          ? '2px solid -webkit-focus-ring-color'
          : 'none'
      }}
      ref={ref}>
      {column.rendered}
      {columnProps.allowsSorting &&
        state
          .sortDescriptor
          ?.column ===
          column.key && (
          <span
            aria-hidden="true"
            style={{
              padding:
                '0 2px'
            }}>
            {arrowIcon}
          </span>
        )}
    </div>
  );
}
function TableSelectAllCell({
  column
}) {
  let ref = useRef();
  let state = useTableContext();
  let isSingleSelectionMode =
    state
      .selectionManager
      .selectionMode ===
    'single';
  let {
    columnHeaderProps
  } = useTableColumnHeader(
    {
      node: column,
      ref,
      colspan:
        column.colspan,
      isDisabled: isSingleSelectionMode
    },
    state
  );
  let {
    checkboxProps
  } = useTableSelectAllCheckbox(
    state
  );
  let inputRef = useRef(
    null
  );
  let {
    inputProps
  } = useCheckbox(
    checkboxProps,
    useToggleState(
      checkboxProps
    ),
    inputRef
  );
  return (
    <div
      {...columnHeaderProps}
      style={{
        height: '16px',
        padding:
          '10px 10px 10px 10px'
      }}
      aria-disabled={
        isSingleSelectionMode
      }
      ref={ref}>
      <input
        {...inputProps}
        ref={inputRef}
        disabled={
          isSingleSelectionMode
        }
        style={{
          visibility: isSingleSelectionMode
            ? 'hidden'
            : 'visible'
        }}
      />
    </div>
  );
}
function TableRowGroup({
  children,
  ...otherProps
}) {
  let {
    rowGroupProps
  } = useTableRowGroup();
  return (
    <div
      {...rowGroupProps}
      {...otherProps}>
      {children}
    </div>
  );
}
function TableRow({
  item,
  children,
  ...otherProps
}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(
    item.key
  );
  let isSelected =
    state.selectionManager.isSelected(
      item.key
    ) && !isDisabled;
  let {
    rowProps
  } = useTableRow(
    {
      node: item,
      isSelected,
      ref,
      isDisabled
    },
    state
  );
  let props = mergeProps(
    rowProps,
    otherProps
  );
  return (
    <div
      style={{
        display: 'flex',
        flexDirection:
          'row',
        padding:
          '1px 1px 2px 1px',
        borderTop:
          '1px solid lightgrey'
      }}
      {...props}
      ref={ref}>
      {children}
    </div>
  );
}
function TableHeaderRow({
  item,
  children,
  ...otherProps
}) {
  return (
    <div
      role="row"
      aria-rowindex={
        item.index + 1
      }
      {...otherProps}
      style={{
        display: 'flex',
        flexDirection:
          'row',
        paddingBottom:
          '4px'
      }}>
      {children}
    </div>
  );
}
function TableCheckboxCell({
  cell
}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(
    cell.parentKey
  );
  let {
    gridCellProps
  } = useTableCell(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  let {
    checkboxProps
  } = useTableSelectionCheckbox(
    {
      key:
        cell.parentKey,
      isDisabled
    },
    state
  );
  let inputRef = useRef(
    null
  );
  let {
    inputProps
  } = useCheckbox(
    {
      ...checkboxProps,
      isDisabled
    },
    useToggleState(
      checkboxProps
    ),
    inputRef
  );
  return (
    <div
      {...gridCellProps}
      style={{
        height: '16px',
        padding:
          '10px 10px 10px 10px'
      }}
      ref={ref}>
      {state
        .selectionManager
        .selectionMode !==
        'none' && (
        <input
          {...inputProps}
        />
      )}
    </div>
  );
}
function TableCell({
  cell
}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(
    cell.parentKey
  );
  let {
    gridCellProps
  } = useTableCell(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  return (
    <TableCellBase
      {...gridCellProps}
      cell={cell}
      cellRef={ref}
    />
  );
}
function TableRowHeader({
  cell
}) {
  let ref = useRef();
  let state = useTableContext();
  let isDisabled = state.disabledKeys.has(
    cell.parentKey
  );
  let {
    rowHeaderProps
  } = useTableRowHeader(
    {
      node: cell,
      ref,
      isDisabled
    },
    state
  );
  return (
    <TableCellBase
      {...rowHeaderProps}
      cell={cell}
      cellRef={ref}
    />
  );
}
function TableCellBase({
  cell,
  cellRef,
  ...otherProps
}) {
  let {
    isFocusVisible,
    focusProps
  } = useFocusRing();
  return (
    <div
      {...mergeProps(
        otherProps,
        focusProps
      )}
      style={{
        height: '16px',
        lineHeight:
          '16px',
        width: '100px',
        padding:
          '10px 10px 10px 10px',
        outline: isFocusVisible
          ? '2px solid -webkit-focus-ring-color'
          : 'none'
      }}
      ref={cellRef}>
      <span
        style={{
          overflow:
            'hidden',
          whiteSpace:
            'nowrap',
          textOverflow:
            'ellipsis'
        }}>
        {cell.rendered}
      </span>
    </div>
  );
}
<Table
  aria-label="Example static collection table"
  style={{
    height: '210px',
    maxWidth: '400px'
  }}>
  <TableHeader>
    <Column>
      Name
    </Column>
    <Column>
      Type
    </Column>
    <Column>
      Date Modified
    </Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>
        Games
      </Cell>
      <Cell>
        File folder
      </Cell>
      <Cell>
        6/7/2020
      </Cell>
    </Row>
    <Row>
      <Cell>
        Program Files
      </Cell>
      <Cell>
        File folder
      </Cell>
      <Cell>
        4/7/2021
      </Cell>
    </Row>
    <Row>
      <Cell>
        bootmgr
      </Cell>
      <Cell>
        System file
      </Cell>
      <Cell>
        11/20/2010
      </Cell>
    </Row>
    <Row>
      <Cell>
        log.txt
      </Cell>
      <Cell>
        Text Document
      </Cell>
      <Cell>
        1/18/2016
      </Cell>
    </Row>
  </TableBody>
</Table>

Usage#

Dynamic collections#

Dynamic collections, as shown below, can be used when the table data comes from an external data source such as an API call, or update over time. In the example below, both the columns and the rows are provided to the table via a render function.

function Example() {
  let columns = [
    {name: 'Name', key: 'name'},
    {name: 'Type', key: 'type'},
    {name: 'Date Modified', key: 'date'}
  ];
  let rows = [
    {id: '1', name: 'Games', date: '6/7/2020', type: 'File folder'},
    {id: '2', name: 'Program Files', date: '4/7/2021', type: 'File folder'},
    {id: '3', name: 'bootmgr', date: '11/20/2010', type: 'System file'},
    {id: '4', name: 'log.txt', date: '1/18/2016', type: 'Text Document'}
  ];
  return (
    <Table
      aria-label="Example dynamic collection table"
      style={{height: '210px', maxWidth: '400px'}}>
      <TableHeader columns={columns}>
        {(column) => <Column key={column.key}>{column.name}</Column>}
      </TableHeader>
      <TableBody items={rows}>
        {(item) => (
          <Row key={item.id}>
            {/* Note this key is equal to the key of the the column,
            not the key set on the Row prior */}
            {(key) => <Cell>{item[key]}</Cell>}
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

function Example() {
  let columns = [
    {name: 'Name', key: 'name'},
    {name: 'Type', key: 'type'},
    {name: 'Date Modified', key: 'date'}
  ];
  let rows = [
    {
      id: '1',
      name: 'Games',
      date: '6/7/2020',
      type: 'File folder'
    },
    {
      id: '2',
      name: 'Program Files',
      date: '4/7/2021',
      type: 'File folder'
    },
    {
      id: '3',
      name: 'bootmgr',
      date: '11/20/2010',
      type: 'System file'
    },
    {
      id: '4',
      name: 'log.txt',
      date: '1/18/2016',
      type: 'Text Document'
    }
  ];
  return (
    <Table
      aria-label="Example dynamic collection table"
      style={{height: '210px', maxWidth: '400px'}}>
      <TableHeader columns={columns}>
        {(column) => (
          <Column key={column.key}>{column.name}</Column>
        )}
      </TableHeader>
      <TableBody items={rows}>
        {(item) => (
          <Row key={item.id}>
            {/* Note this key is equal to the key of the the column,
            not the key set on the Row prior */}
            {(key) => <Cell>{item[key]}</Cell>}
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

function Example() {
  let columns = [
    {
      name: 'Name',
      key: 'name'
    },
    {
      name: 'Type',
      key: 'type'
    },
    {
      name:
        'Date Modified',
      key: 'date'
    }
  ];
  let rows = [
    {
      id: '1',
      name: 'Games',
      date: '6/7/2020',
      type: 'File folder'
    },
    {
      id: '2',
      name:
        'Program Files',
      date: '4/7/2021',
      type: 'File folder'
    },
    {
      id: '3',
      name: 'bootmgr',
      date: '11/20/2010',
      type: 'System file'
    },
    {
      id: '4',
      name: 'log.txt',
      date: '1/18/2016',
      type:
        'Text Document'
    }
  ];
  return (
    <Table
      aria-label="Example dynamic collection table"
      style={{
        height: '210px',
        maxWidth: '400px'
      }}>
      <TableHeader
        columns={
          columns
        }>
        {(column) => (
          <Column
            key={
              column.key
            }>
            {column.name}
          </Column>
        )}
      </TableHeader>
      <TableBody
        items={rows}>
        {(item) => (
          <Row
            key={
              item.id
            }>
            {/* Note this key is equal to the key of the the column,
            not the key set on the Row prior */}
            {(key) => (
              <Cell>
                {
                  item[
                    key
                  ]
                }
              </Cell>
            )}
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

Selection#

By default, useTableState doesn't allow row selection but this can be modified using the selectionMode prop. Use defaultSelectedKeys to provide a default set of selected rows. Note that the value of the selected keys must match the key prop of the row.

The example below uses defaultSelectedKeys to select the row with key equal to "2".

<Table
  aria-label="Example table with single selection (uncontrolled)"
  selectionMode="single"
  defaultSelectedKeys={['2']}
  style={{height: '210px', maxWidth: '400px'}}>
  <TableHeader>
    <Column>Name</Column>
    <Column>Type</Column>
    <Column>Level</Column>
  </TableHeader>
  <TableBody>
    <Row key="1">
      <Cell>Charizard</Cell>
      <Cell>Fire, Flying</Cell>
      <Cell>67</Cell>
    </Row>
    <Row key="2">
      <Cell>Blastoise</Cell>
      <Cell>Water</Cell>
      <Cell>56</Cell>
    </Row>
    <Row key="3">
      <Cell>Venusaur</Cell>
      <Cell>Grass, Poison</Cell>
      <Cell>83</Cell>
    </Row>
    <Row key="4">
      <Cell>Pikachu</Cell>
      <Cell>Electric</Cell>
      <Cell>100</Cell>
    </Row>
  </TableBody>
</Table>

<Table
  aria-label="Example table with single selection (uncontrolled)"
  selectionMode="single"
  defaultSelectedKeys={['2']}
  style={{height: '210px', maxWidth: '400px'}}>
  <TableHeader>
    <Column>Name</Column>
    <Column>Type</Column>
    <Column>Level</Column>
  </TableHeader>
  <TableBody>
    <Row key="1">
      <Cell>Charizard</Cell>
      <Cell>Fire, Flying</Cell>
      <Cell>67</Cell>
    </Row>
    <Row key="2">
      <Cell>Blastoise</Cell>
      <Cell>Water</Cell>
      <Cell>56</Cell>
    </Row>
    <Row key="3">
      <Cell>Venusaur</Cell>
      <Cell>Grass, Poison</Cell>
      <Cell>83</Cell>
    </Row>
    <Row key="4">
      <Cell>Pikachu</Cell>
      <Cell>Electric</Cell>
      <Cell>100</Cell>
    </Row>
  </TableBody>
</Table>

<Table
  aria-label="Example table with single selection (uncontrolled)"
  selectionMode="single"
  defaultSelectedKeys={[
    '2'
  ]}
  style={{
    height: '210px',
    maxWidth: '400px'
  }}>
  <TableHeader>
    <Column>
      Name
    </Column>
    <Column>
      Type
    </Column>
    <Column>
      Level
    </Column>
  </TableHeader>
  <TableBody>
    <Row key="1">
      <Cell>
        Charizard
      </Cell>
      <Cell>
        Fire, Flying
      </Cell>
      <Cell>67</Cell>
    </Row>
    <Row key="2">
      <Cell>
        Blastoise
      </Cell>
      <Cell>
        Water
      </Cell>
      <Cell>56</Cell>
    </Row>
    <Row key="3">
      <Cell>
        Venusaur
      </Cell>
      <Cell>
        Grass, Poison
      </Cell>
      <Cell>83</Cell>
    </Row>
    <Row key="4">
      <Cell>
        Pikachu
      </Cell>
      <Cell>
        Electric
      </Cell>
      <Cell>100</Cell>
    </Row>
  </TableBody>
</Table>

To programmatically control row selection, use the selectedKeys prop paired with the onSelectionChange callback. The key prop from the selected row will be passed into the callback when the row is pressed, allowing you to update selectedKeys accordingly.

Here is how you would control selection for the above example.

function PokemonTable(props) {
  let columns = [
    {name: 'Name', uid: 'name'},
    {name: 'Type', uid: 'type'},
    {name: 'Level', uid: 'level'}
  ];
  let rows = [
    {id: '1', name: 'Charizard', type: 'Fire, Flying', level: '67'},
    {id: '2', name: 'Blastoise', type: 'Water', level: '56'},
    {id: '3', name: 'Venusaur', type: 'Grass, Poison', level: '83'},
    {id: '4', name: 'Pikachu', type: 'Electric', level: '100'}
  ];
  let [selected, setSelected] = React.useState(new Set(['2']));
  return (
    <Table
      aria-label="Example table with single selection (controlled)"
      selectionMode="single"
      selectedKeys={selected}
      onSelectionChange={setSelected}
      style={{height: '210px', maxWidth: '400px'}}
      {...props}>
      <TableHeader columns={columns}>
        {(column) => <Column key={column.uid}>{column.name}</Column>}
      </TableHeader>
      <TableBody items={rows}>
        {(item) => <Row key={item.id}>{(key) => <Cell>{item[key]}</Cell>}</Row>}
      </TableBody>
    </Table>
  );
}

function PokemonTable(props) {
  let columns = [
    {name: 'Name', uid: 'name'},
    {name: 'Type', uid: 'type'},
    {name: 'Level', uid: 'level'}
  ];
  let rows = [
    {
      id: '1',
      name: 'Charizard',
      type: 'Fire, Flying',
      level: '67'
    },
    {
      id: '2',
      name: 'Blastoise',
      type: 'Water',
      level: '56'
    },
    {
      id: '3',
      name: 'Venusaur',
      type: 'Grass, Poison',
      level: '83'
    },
    {
      id: '4',
      name: 'Pikachu',
      type: 'Electric',
      level: '100'
    }
  ];
  let [selected, setSelected] = React.useState(
    new Set(['2'])
  );
  return (
    <Table
      aria-label="Example table with single selection (controlled)"
      selectionMode="single"
      selectedKeys={selected}
      onSelectionChange={setSelected}
      style={{height: '210px', maxWidth: '400px'}}
      {...props}>
      <TableHeader columns={columns}>
        {(column) => (
          <Column key={column.uid}>{column.name}</Column>
        )}
      </TableHeader>
      <TableBody items={rows}>
        {(item) => (
          <Row key={item.id}>
            {(key) => <Cell>{item[key]}</Cell>}
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

function PokemonTable(
  props
) {
  let columns = [
    {
      name: 'Name',
      uid: 'name'
    },
    {
      name: 'Type',
      uid: 'type'
    },
    {
      name: 'Level',
      uid: 'level'
    }
  ];
  let rows = [
    {
      id: '1',
      name: 'Charizard',
      type:
        'Fire, Flying',
      level: '67'
    },
    {
      id: '2',
      name: 'Blastoise',
      type: 'Water',
      level: '56'
    },
    {
      id: '3',
      name: 'Venusaur',
      type:
        'Grass, Poison',
      level: '83'
    },
    {
      id: '4',
      name: 'Pikachu',
      type: 'Electric',
      level: '100'
    }
  ];
  let [
    selected,
    setSelected
  ] = React.useState(
    new Set(['2'])
  );
  return (
    <Table
      aria-label="Example table with single selection (controlled)"
      selectionMode="single"
      selectedKeys={
        selected
      }
      onSelectionChange={
        setSelected
      }
      style={{
        height: '210px',
        maxWidth: '400px'
      }}
      {...props}>
      <TableHeader
        columns={
          columns
        }>
        {(column) => (
          <Column
            key={
              column.uid
            }>
            {column.name}
          </Column>
        )}
      </TableHeader>
      <TableBody
        items={rows}>
        {(item) => (
          <Row
            key={
              item.id
            }>
            {(key) => (
              <Cell>
                {
                  item[
                    key
                  ]
                }
              </Cell>
            )}
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

Multiple selection can be enabled by setting selectionMode to multiple.

// Using the same table as above
<PokemonTable selectionMode="multiple" />

// Using the same table as above
<PokemonTable selectionMode="multiple" />

// Using the same table as above
<PokemonTable selectionMode="multiple" />

Table also supports a disallowEmptySelection prop which forces the user to have at least one row in the Table selected at all times.

// Using the same table as above
<PokemonTable selectionMode="single" disallowEmptySelection />

// Using the same table as above
<PokemonTable
  selectionMode="single"
  disallowEmptySelection
/>

// Using the same table as above
<PokemonTable
  selectionMode="single"
  disallowEmptySelection
/>

Disabled rows#

You can disable specific rows by providing an array of keys to useTableState via the disabledKeys prop. This will prevent rows from being selectable as shown in the example below. Note that you are responsible for the styling of disabled rows.

// Using the same table as above
<PokemonTable selectionMode="multiple" disabledKeys={['2']} />

// Using the same table as above
<PokemonTable
  selectionMode="multiple"
  disabledKeys={['2']}
/>

// Using the same table as above
<PokemonTable
  selectionMode="multiple"
  disabledKeys={['2']}
/>

Sorting#

Table supports sorting its data when a column header is pressed. To designate that a Column should support sorting, provide it with the allowsSorting prop. The Table accepts a SortDescriptor prop that defines the current column key to sort by and the sort direction (ascending/descending). When the user presses a column's sort icon, the column's key and sort direction is passed into the onSortChange callback, allowing you to update the SortDescriptor appropriately.

This example performs client side sorting by passing a sort function to the useAsyncList hook. See the docs for more information on how to perform server side sorting.

import {useAsyncList} from '@react-stately/data';
function AsyncSortTable() {
  let columns = [
    {name: 'Name', key: 'name'},
    {name: 'Height', key: 'height'},
    {name: 'Mass', key: 'mass'},
    {name: 'Birth Year', key: 'birth_year'}
  ];
  let list = useAsyncList({
    async load({signal}) {
      let res = await fetch(`https://swapi.dev/api/people/?search`, {signal});
      let json = await res.json();
      return {
        items: json.results
      };
    },
    async sort({items, sortDescriptor}) {
      let sorted = items.sort((a, b) => {
        let cmp;
        let first = a[sortDescriptor.column].replace('BBY', '');
        let second = b[sortDescriptor.column].replace('BBY', '');
        if (+first || +second) {
          cmp = +first < +second ? -1 : 1;
        } else {
          cmp = first <= second ? -1 : 1;
        }
        if (sortDescriptor.direction === 'descending') {
          cmp *= -1;
        }
        return cmp;
      });
      return {
        items: sorted
      };
    }
  });
  return (
    <Table
      aria-label="Example table with client side sorting"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}
      style={{height: '300px', maxWidth: '600px'}}>
      <TableHeader columns={columns}>
        {(column) => <Column allowsSorting>{column.name}</Column>}
      </TableHeader>
      <TableBody items={list.items}>
        {(item) => (
          <Row key={item.name}>{(key) => <Cell>{item[key]}</Cell>}</Row>
        )}
      </TableBody>
    </Table>
  );
}

import {useAsyncList} from '@react-stately/data';
function AsyncSortTable() {
  let columns = [
    {name: 'Name', key: 'name'},
    {name: 'Height', key: 'height'},
    {name: 'Mass', key: 'mass'},
    {name: 'Birth Year', key: 'birth_year'}
  ];
  let list = useAsyncList({
    async load({signal}) {
      let res = await fetch(
        `https://swapi.dev/api/people/?search`,
        {signal}
      );
      let json = await res.json();
      return {
        items: json.results
      };
    },
    async sort({items, sortDescriptor}) {
      let sorted = items.sort((a, b) => {
        let cmp;
        let first = a[sortDescriptor.column].replace(
          'BBY',
          ''
        );
        let second = b[sortDescriptor.column].replace(
          'BBY',
          ''
        );
        if (+first || +second) {
          cmp = +first < +second ? -1 : 1;
        } else {
          cmp = first <= second ? -1 : 1;
        }
        if (sortDescriptor.direction === 'descending') {
          cmp *= -1;
        }
        return cmp;
      });
      return {
        items: sorted
      };
    }
  });
  return (
    <Table
      aria-label="Example table with client side sorting"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}
      style={{height: '300px', maxWidth: '600px'}}>
      <TableHeader columns={columns}>
        {(column) => (
          <Column allowsSorting>{column.name}</Column>
        )}
      </TableHeader>
      <TableBody items={list.items}>
        {(item) => (
          <Row key={item.name}>
            {(key) => <Cell>{item[key]}</Cell>}
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

import {useAsyncList} from '@react-stately/data';
function AsyncSortTable() {
  let columns = [
    {
      name: 'Name',
      key: 'name'
    },
    {
      name: 'Height',
      key: 'height'
    },
    {
      name: 'Mass',
      key: 'mass'
    },
    {
      name: 'Birth Year',
      key: 'birth_year'
    }
  ];
  let list = useAsyncList(
    {
      async load({
        signal
      }) {
        let res = await fetch(
          `https://swapi.dev/api/people/?search`,
          {signal}
        );
        let json = await res.json();
        return {
          items:
            json.results
        };
      },
      async sort({
        items,
        sortDescriptor
      }) {
        let sorted = items.sort(
          (a, b) => {
            let cmp;
            let first = a[
              sortDescriptor
                .column
            ].replace(
              'BBY',
              ''
            );
            let second = b[
              sortDescriptor
                .column
            ].replace(
              'BBY',
              ''
            );
            if (
              +first ||
              +second
            ) {
              cmp =
                +first <
                +second
                  ? -1
                  : 1;
            } else {
              cmp =
                first <=
                second
                  ? -1
                  : 1;
            }
            if (
              sortDescriptor.direction ===
              'descending'
            ) {
              cmp *= -1;
            }
            return cmp;
          }
        );
        return {
          items: sorted
        };
      }
    }
  );
  return (
    <Table
      aria-label="Example table with client side sorting"
      sortDescriptor={
        list.sortDescriptor
      }
      onSortChange={
        list.sort
      }
      style={{
        height: '300px',
        maxWidth: '600px'
      }}>
      <TableHeader
        columns={
          columns
        }>
        {(column) => (
          <Column
            allowsSorting>
            {column.name}
          </Column>
        )}
      </TableHeader>
      <TableBody
        items={
          list.items
        }>
        {(item) => (
          <Row
            key={
              item.name
            }>
            {(key) => (
              <Cell>
                {
                  item[
                    key
                  ]
                }
              </Cell>
            )}
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

Internationalization#

useTable handles some aspects of internationalization automatically. For example, type to select is implemented with an Intl.Collator for internationalized string matching. You are responsible for localizing all text content within the table. Make sure that some types of content (e.g. file extensions) are not translated.

RTL#

In right-to-left languages, the table layout should be mirrored. The columns should be ordered from right to left and the individual column text alignment should be inverted. Ensure that your CSS accounts for this.

Name	Type	Default	Description
`ref`	`RefObject<HTMLElement>`	—	The ref attached to the grid element.
`layout`	`Layout<Node<T>>`	—	The layout object for the table. Computes what content is visible and how to position and style them.
`isVirtualized`	`boolean`	—	Whether the grid uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`	—	An optional keyboard delegate implementation for type to select, to override the default.
`focusMode`	`'row' \| 'cell'`	`'row'`	Whether initial grid focus should be placed on the grid row or grid cell.
`getRowText`	`( (key: Key )) => string`	`(key) => state.collection.getItem(key)?.textValue`	A function that returns the text that should be announced by assistive technology when a row is added or removed from selection.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

[CollectionView]{@link CollectionView} supports arbitrary layout objects, which compute what views are visible, and how to position and style them. However, layouts do not create the views themselves directly. Instead, layouts produce lightweight {@link LayoutInfo} objects which describe various properties of a view, such as its position and size. The {@link CollectionView} is then responsible for creating the actual views as needed, based on this layout information.

Every layout extends from the {@link Layout} abstract base class. Layouts must implement a minimum of the two methods listed below. All other methods can be optionally overridden to implement custom behavior.

Properties

Name	Type	Description
`virtualizer`	`Virtualizer<T, any, any>`	The CollectionView the layout is currently attached to.

Methods

Method	Description
`shouldInvalidate( (newRect: Rect, , oldRect: Rect )): boolean`	Returns whether the layout should invalidate in response to visible rectangle changes. By default, it only invalidates when the collection view's size changes. Return true always to make the layout invalidate while scrolling (e.g. sticky headers).
`validate( (invalidationContext: InvalidationContext<T, any> )): void`	This method allows the layout to perform any pre-computation it needs to in order to prepare {@link LayoutInfo}s for retrieval. Called by the collection view before {@link getVisibleLayoutInfos} or {@link getLayoutInfo} are called.
`getVisibleLayoutInfos( (rect: Rect )): LayoutInfo[]`	Returns an array of {@link LayoutInfo} objects which are inside the given rectangle. Should be implemented by subclasses.
`getLayoutInfo( (key: Key )): LayoutInfo`	Returns a {@link LayoutInfo} for the given key. Should be implemented by subclasses.
`getContentSize(): Size`	Returns size of the content. By default, it returns collectionView's size.
`getInitialLayoutInfo( (layoutInfo: LayoutInfo )): LayoutInfo`	Returns a {@link DragTarget} describing a view at the given point to be dragged. Return `null` to cancel the drag. The default implementation returns the view at the given point.
`getFinalLayoutInfo( (layoutInfo: LayoutInfo )): LayoutInfo`	Returns the ending attributes for an animated removal. The view is animated from the {@link LayoutInfo} returned by {@link getLayoutInfo} to the one returned by this method. The default implementation returns its input.

Represents a rectangle.

Properties

Name	Type	Description
`x`	`number`	The x-coordinate of the rectangle.
`y`	`number`	The y-coordinate of the rectangle.
`width`	`number`	The width of the rectangle.
`height`	`number`	The height of the rectangle.
`maxX`	`number`	The maximum x-coordinate in the rectangle.
`maxY`	`number`	The maximum y-coordinate in the rectangle.
`area`	`number`	The area of the rectangle.
`topLeft`	`Point`	The top left corner of the rectangle.
`topRight`	`Point`	The top right corner of the rectangle.
`bottomLeft`	`Point`	The bottom left corner of the rectangle.
`bottomRight`	`Point`	The bottom right corner of the rectangle.

Methods

Method	Description
`intersects( (rect: Rect )): boolean`	Returns whether this rectangle intersects another rectangle.
`containsRect( (rect: Rect )): boolean`	Returns whether this rectangle fully contains another rectangle.
`containsPoint( (point: Point )): boolean`	Returns whether the rectangle contains the given point.
`getCornerInRect( (rect: Rect )): RectCorner \| null`	Returns the first corner of this rectangle (from top to bottom, left to right) that is contained in the given rectangle, or null of the rectangles do not intersect.
`equals( (rect: Rect )): void`
`pointEquals( (point: Point \| \| Rect )): void`
`sizeEquals( (size: Size \| \| Rect )): void`
`copy(): Rect`	Returns a copy of this rectangle.

Properties

Name	Type	Description
`x`	`number`	The x-coordinate of the point.
`y`	`number`	The y-coordinate of the point.

Methods

Method	Description
`copy(): Point`	Returns a copy of this point.
`equals( (point: Point )): boolean`	Checks if two points are equal.
`isOrigin(): boolean`	Returns true if this point is the origin.

'topLeft'
  | 'topRight'
  | 'bottomLeft'
  | 'bottomRight'

Properties

Name	Type	Description
`width`	`number`
`height`	`number`

Methods

Method	Description
`copy(): Size`	Returns a copy of this size.
`equals( (other: Size )): boolean`	Returns whether this size is equal to another one.

Instances of this lightweight class are created by {@link Layout} subclasses to represent each view in the {@link CollectionView}. LayoutInfo objects describe various properties of a view, such as its position and size, and style information. The collection view uses this information when creating actual views to display.

Properties

Name	Type	Description
`type`	`string`	A string representing the view type. Should be `'item'` for item views. Other types are used by supplementary views.
`key`	`Key`	A unique key for this view. For item views, it should match the content key.
`parentKey`	`Key \| null`	The key for a parent layout info, if any.
`rect`	`Rect`	The rectangle describing the size and position of this view.
`estimatedSize`	`boolean`	Whether the size is estimated. `false` by default.
`isSticky`	`boolean`	Whether the layout info sticks to the viewport when scrolling.
`opacity`	`number`	The view's opacity. 1 by default.
`transform`	`string \| null`	A CSS transform string to apply to the view. `null` by default.
`zIndex`	`number`	The z-index of the view. 0 by default.

Methods

Method	Description
`copy(): LayoutInfo`	Returns a copy of the LayoutInfo.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the heirarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`childNodes`	`Iterable<Node<T>>`	The loaded children of this node.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key`	The key of the parent node.
`prevKey`	`Key`	The key of the node before this node.
`nextKey`	`Key`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.

Method	Description
`getKeyBelow( (key: Key )): Key`	Returns the key visually below the given one, or `null` for none.
`getKeyAbove( (key: Key )): Key`	Returns the key visually above the given one, or `null` for none.
`getKeyLeftOf( (key: Key )): Key`	Returns the key visually to the left of the given one, or `null` for none.
`getKeyRightOf( (key: Key )): Key`	Returns the key visually to the right of the given one, or `null` for none.
`getKeyPageBelow( (key: Key )): Key`	Returns the key visually one page below the given one, or `null` for none.
`getKeyPageAbove( (key: Key )): Key`	Returns the key visually one page above the given one, or `null` for none.
`getFirstKey( (key: Key, , global: boolean )): Key`	Returns the first key, or `null` for none.
`getLastKey( (key: Key, , global: boolean )): Key`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey: Key )): Key`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

Properties

Name	Type	Description
`collection`	`TableCollection<T>`	A collection of rows and columns in the table.
`showSelectionCheckboxes`	`boolean`	Whether the row selection checkboxes should be displayed.
`sortDescriptor`	`SortDescriptor`	The current sorted column and direction.
`disabledKeys`	`Set<Key>`	A set of keys for rows that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update row selection state.

Methods

Method	Description
`sort( (columnKey: Key )): void`	Calls the provided onSortChange handler with the provided column key and sort direction.

Properties

Name	Type	Description
`headerRows`	`GridNode<T>[]`	A list of header row nodes in the table.
`columns`	`GridNode<T>[]`	A list of column nodes in the table.
`rowHeaderColumnKeys`	`Set<Key>`	A set of column keys that serve as the row header.
`body`	`GridNode<T>`	The node that makes up the body of the table.
`columnCount`	`number`	The number of columns in the grid.
`rows`	`GridNode<T>[]`	A list of rows in the grid.
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): Node`	Get an item by its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the heirarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`childNodes`	`Iterable<Node<T>>`	The loaded children of this node.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`column`	`GridNode<T>`
`colspan`	`number`
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key`	The key of the parent node.
`prevKey`	`Key`	The key of the node before this node.
`nextKey`	`Key`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.

Name	Type	Description
`column`	`Key`	The key of the column to sort by.
`direction`	`SortDirection`	The direction to sort by.

'ascending' | 'descending'

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`rawSelection`	`Selection`	The raw selection value for the collection. Either 'all' for select all, or a set of keys.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`

Methods

Method	Description
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , childFocusStrategy: FocusStrategy )): void`	Sets the focused key.
`isSelected( (key: Key )): void`	Returns whether a key is selected.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e: PressEvent \| \| PointerEvent )): void`
`isSelectionEqual( (selection: Set<Key> )): void`	Returns whether the current selection is equal to the given selection.

A generic interface to access a readonly sequential collection of unique keyed items.

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T`	Get an item by its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectedKeys( (keys: Selection \| \| ( (v: Selection )) => Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , child: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'none'
  | 'single'
  | 'multiple'

'all' | Set<Key>

'first' | 'last'

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`gridProps`	`HTMLAttributes<HTMLElement>`	Props for the grid element.

Name	Type	Description
`node`	`Node<unknown>`	An object representing the column header. Contains all the relevant information that makes up the column header.
`ref`	`RefObject<HTMLElement>`	The ref attached to the column header.
`isVirtualized`	`boolean`	Whether the column header is contained in a virtual scroller.
`colspan`	`number`	The number of columns the column header should span.
`isDisabled`	`boolean`	Whether the column header is disabled.

Name	Type	Description
`columnHeaderProps`	`HTMLAttributes<HTMLElement>`	Props for the column header element.

Name	Type	Description
`node`	`Node<T>`	An object representing the grid row. Contains all the relevant information that makes up the grid row.
`ref`	`RefObject<HTMLElement>`	The ref attached to the grid row.
`isVirtualized`	`boolean`	Whether the grid row is contained in a virtual scroller.
`isSelected`	`boolean`	Whether the grid row is selected.
`isDisabled`	`boolean`	Whether the grid row is disabled.
`shouldSelectOnPressUp`	`boolean`	Whether selection should occur on press up instead of press down.

Name	Type	Description
`rowProps`	`HTMLAttributes<HTMLElement>`	Props for the grid row element.

Name	Type	Description
`rowGroupProps`	`HTMLAttributes<HTMLElement>`	Props for the row group element.

Name	Type	Description
`node`	`GridNode<unknown>`	An object representing the row header. Contains all the relevant information that makes up the row header.
`ref`	`RefObject<HTMLElement>`	The ref attached to the row header.
`isVirtualized`	`boolean`	Whether the row header is contained in a virtual scroller.
`isDisabled`	`boolean`	Whether the row header is disabled.

Name	Type	Description
`rowHeaderProps`	`HTMLAttributes<HTMLElement>`	Props for the row header element.

Name	Type	Description
`node`	`Node<unknown>`	An object representing the grid cell. Contains all the relevant information that makes up the grid cell.
`ref`	`RefObject<HTMLElement>`	The ref attached to the grid cell element.
`isVirtualized`	`boolean`	Whether the grid cell is contained in a virtual scroller.
`isDisabled`	`boolean`	Whether the grid cell is disabled.
`focusMode`	`'child' \| 'cell'`	Whether the cell or its first focusable child element should be focused when the grid cell is focused.
`shouldSelectOnPressUp`	`boolean`	Whether selection should occur on press up instead of press down.

Name	Type	Description
`collection`	`C`
`disabledKeys`	`Set<Key>`	A set of keys for rows that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update row selection state.

Name	Type	Description
`gridCellProps`	`HTMLAttributes<HTMLElement>`	Props for the grid cell element.

Name	Type	Description
`key`	`Key`	A unique key for the checkbox.
`isDisabled`	`boolean`	Whether the checkbox is disabled.

Name	Type	Description
`checkboxProps`	`AriaCheckboxProps`	Props for the row selection checkbox element.

Name	Type	Description
`isIndeterminate`	`boolean`	Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.
`children`	`ReactNode`	The label for the element.
`defaultSelected`	`boolean`	Whether the element should be selected (uncontrolled).
`isSelected`	`boolean`	Whether the element should be selected (controlled).
`onChange`	`( (isSelected: boolean )) => void`	Handler that is called when the element's selection state changes.
`value`	`string`	The value of the input element, used when submitting an HTML form. See MDN.
`name`	`string`	The name of the input element, used when submitting an HTML form. See MDN.
`isDisabled`	`boolean`	Whether the input is disabled.
`isReadOnly`	`boolean`	Whether the input can be selected but not changed by the user.
`validationState`	`ValidationState`	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is released.
`aria-controls`	`string`	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`excludeFromTabOrder`	`boolean`	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-errormessage`	`string`	Identifies the element that provides an error message for the object.

'valid' | 'invalid'

BaseEvent<ReactKeyboardEvent<any>>

T & {stopPropagation: () => void,
continuePropagation: () => void
}

Name	Type	Description
`checkboxProps`	`AriaCheckboxProps`	Props for the select all checkbox element.

Provides state management for a table component. Handles building a collection of columns and rows from props. In addition, it tracks row selection and manages sort order changes.

useTableState<T>(
  (props: TableStateProps<T>
)): TableState<T>

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`showSelectionCheckboxes`	`boolean`	Whether the row selection checkboxes should be displayed.
`items`	`Iterable<T>`	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`'all' \| Iterable<Key>`	The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`( (keys: Selection )) => any`	Handler that is called when the selection changes.
`sortDescriptor`	`SortDescriptor`	The current sorted column and direction.
`onSortChange`	`( (descriptor: SortDescriptor )) => any`	Handler that is called when the sorted column or direction changes.

CollectionElement<T>
  | CollectionElement<T>[]
  | (
    (item: T
  )) => CollectionElement<T>

SectionElement<T> | ItemElement<T>

ReactElement<SectionProps<T>>

Name	Type	Description
`children`	`ItemElement<T> \| ItemElement<T>[] \| ItemRenderer<T>`	Static child items or a function to render children.
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`items`	`Iterable<T>`	Item objects in the section.

ReactElement<ItemProps<T>>

Name	Type	Description
`children`	`ReactNode`	Rendered contents of the item or child items.
`title`	`ReactNode`	Rendered contents of the item if `children` contains child items.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this item.
`childItems`	`Iterable<T>`	A list of child item objects. Used for dynamic collections.
`hasChildItems`	`boolean`	Whether this item has children, even if not loaded yet.

(
  (item: T
)) => ItemElement<T>