TableView

Tables are containers for displaying information. They allow users to quickly scan, sort, compare, and take action on large amounts of data.

Example#

<Flex flexGrow={1} maxWidth="size-6000">
  <TableView
    aria-label="Example table with static contents"
    width="100%"
    height="100%">
    <TableHeader>
      <Column>Name</Column>
      <Column>Type</Column>
      <Column align="end">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>
  </TableView>
</Flex>

<Flex flexGrow={1} maxWidth="size-6000">
  <TableView
    aria-label="Example table with static contents"
    width="100%"
    height="100%">
    <TableHeader>
      <Column>Name</Column>
      <Column>Type</Column>
      <Column align="end">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>
  </TableView>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-6000">
  <TableView
    aria-label="Example table with static contents"
    width="100%"
    height="100%">
    <TableHeader>
      <Column>
        Name
      </Column>
      <Column>
        Type
      </Column>
      <Column align="end">
        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>
  </TableView>
</Flex>

Content#

TableView expects a TableHeader and a TableBody as children. In turn, TableHeader and TableBody follow the Collection Components API. The TableHeader accepts either static Columns or a columns prop with a renderer function for dynamic rendering. Similarly, TableBody accepts either static Rows or a items prop with a renderer function. Row follows the same pattern, accepting Cells as children instead.

Basic usage of TableView, seen in the example above, shows multiple Columns and Rows populated with strings and Cells respectively. Static collections, as in this example, can be used when the contents of the TableView is known ahead of time.

Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time. Providing the data in this way allows TableView to automatically cache the rendering of each item, which dramatically improves performance. Make sure that each rendered property in the Row object matches with a Column's key. In the example below, the uid of each Column is set as its key and matches with a property within each Row object.

let columns = [
  {name: 'Name', uid: 'name'},
  {name: 'Type', uid: 'type'},
  {name: 'Date Modified', uid: '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'}
];

<TableView
  aria-label="Example table with dynamic content"
  height="size-3000"
  maxWidth="size-6000">
  <TableHeader columns={columns}>
    {(column) => (
      <Column
        key={column.uid}
        align={column.uid === 'date' ? 'end' : 'start'}>
        {column.name}
      </Column>
    )}
  </TableHeader>
  <TableBody items={rows}>
    {(item) => <Row>{(columnKey) => <Cell>{item[columnKey]}</Cell>}</Row>}
  </TableBody>
</TableView>

let columns = [
  {name: 'Name', uid: 'name'},
  {name: 'Type', uid: 'type'},
  {name: 'Date Modified', uid: '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'
  }
];

<TableView
  aria-label="Example table with dynamic content"
  height="size-3000"
  maxWidth="size-6000">
  <TableHeader columns={columns}>
    {(column) => (
      <Column
        key={column.uid}
        align={column.uid === 'date' ? 'end' : 'start'}>
        {column.name}
      </Column>
    )}
  </TableHeader>
  <TableBody items={rows}>
    {(item) => (
      <Row>
        {(columnKey) => <Cell>{item[columnKey]}</Cell>}
      </Row>
    )}
  </TableBody>
</TableView>

let columns = [
  {
    name: 'Name',
    uid: 'name'
  },
  {
    name: 'Type',
    uid: 'type'
  },
  {
    name:
      'Date Modified',
    uid: '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'
  }
];

<TableView
  aria-label="Example table with dynamic content"
  height="size-3000"
  maxWidth="size-6000">
  <TableHeader
    columns={columns}>
    {(column) => (
      <Column
        key={
          column.uid
        }
        align={
          column.uid ===
          'date'
            ? 'end'
            : 'start'
        }>
        {column.name}
      </Column>
    )}
  </TableHeader>
  <TableBody
    items={rows}>
    {(item) => (
      <Row>
        {(
          columnKey
        ) => (
          <Cell>
            {
              item[
                columnKey
              ]
            }
          </Cell>
        )}
      </Row>
    )}
  </TableBody>
</TableView>

Internationalization#

To internationalize a TableView, all text content within the TableView should be replaced with localized strings. This includes the aria-label provided to the TableView if any. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of TableView is automatically flipped.

Labeling#

Accessibility#

An aria-label must be provided to the TableView for accessibility. If the TableView is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

By default, the first column of the TableView is used as the row header and is announced by assistive technology when navigating through the rows. You can override this behavior by providing the isRowHeader prop to one or more Columns, allowing you to customize which columns should label the rows of the TableView.

The example below applies isRowHeader to the "First Name" and "Last Name" columns so that each row is announced with the person's full name (e.g. "John Doe").

<Flex flexGrow={1} maxWidth="size-3000">
  <TableView
    aria-label="Example table with static contents"
    width="100%"
    height="100%">
    <TableHeader>
      <Column isRowHeader>First Name</Column>
      <Column isRowHeader>Last Name</Column>
      <Column align="end">Age</Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>John</Cell>
        <Cell>Doe</Cell>
        <Cell>45</Cell>
      </Row>
      <Row>
        <Cell>Jane</Cell>
        <Cell>Doe</Cell>
        <Cell>37</Cell>
      </Row>
      <Row>
        <Cell>Joe</Cell>
        <Cell>Schmoe</Cell>
        <Cell>67</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex flexGrow={1} maxWidth="size-3000">
  <TableView
    aria-label="Example table with static contents"
    width="100%"
    height="100%">
    <TableHeader>
      <Column isRowHeader>First Name</Column>
      <Column isRowHeader>Last Name</Column>
      <Column align="end">Age</Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>John</Cell>
        <Cell>Doe</Cell>
        <Cell>45</Cell>
      </Row>
      <Row>
        <Cell>Jane</Cell>
        <Cell>Doe</Cell>
        <Cell>37</Cell>
      </Row>
      <Row>
        <Cell>Joe</Cell>
        <Cell>Schmoe</Cell>
        <Cell>67</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-3000">
  <TableView
    aria-label="Example table with static contents"
    width="100%"
    height="100%">
    <TableHeader>
      <Column
        isRowHeader>
        First Name
      </Column>
      <Column
        isRowHeader>
        Last Name
      </Column>
      <Column align="end">
        Age
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>
          John
        </Cell>
        <Cell>
          Doe
        </Cell>
        <Cell>45</Cell>
      </Row>
      <Row>
        <Cell>
          Jane
        </Cell>
        <Cell>
          Doe
        </Cell>
        <Cell>37</Cell>
      </Row>
      <Row>
        <Cell>
          Joe
        </Cell>
        <Cell>
          Schmoe
        </Cell>
        <Cell>67</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

Asynchronous loading#

TableView supports loading data asynchronously, and will display a progress circle reflecting the current load state, set by the loadingState prop. It also supports infinite scrolling to load more data on demand as the user scrolls, via the onLoadMore prop.

This example uses the useAsyncList hook to handle loading the data. See the docs for more information.

import {useAsyncList} from '@react-stately/data';

function AsyncTable() {
  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, cursor}) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      let res = await fetch(cursor || `https://swapi.dev/api/people/?search=`, {
        signal
      });
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <Flex height="size-2000" flexGrow={1} maxWidth="size-6000">
      <TableView
        aria-label="example async loading table"
        height="100%"
        width="100%">
        <TableHeader columns={columns}>
          {(column) => (
            <Column align={column.key !== 'name' ? 'end' : 'start'}>
              {column.name}
            </Column>
          )}
        </TableHeader>
        <TableBody
          items={list.items}
          loadingState={list.loadingState}
          onLoadMore={list.loadMore}>
          {(item) => (
            <Row key={item.name}>{(key) => <Cell>{item[key]}</Cell>}</Row>
          )}
        </TableBody>
      </TableView>
    </Flex>
  );
}

import {useAsyncList} from '@react-stately/data';

function AsyncTable() {
  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, cursor}) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      let res = await fetch(
        cursor || `https://swapi.dev/api/people/?search=`,
        {signal}
      );
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <Flex
      height="size-2000"
      flexGrow={1}
      maxWidth="size-6000">
      <TableView
        aria-label="example async loading table"
        height="100%"
        width="100%">
        <TableHeader columns={columns}>
          {(column) => (
            <Column
              align={
                column.key !== 'name' ? 'end' : 'start'
              }>
              {column.name}
            </Column>
          )}
        </TableHeader>
        <TableBody
          items={list.items}
          loadingState={list.loadingState}
          onLoadMore={list.loadMore}>
          {(item) => (
            <Row key={item.name}>
              {(key) => <Cell>{item[key]}</Cell>}
            </Row>
          )}
        </TableBody>
      </TableView>
    </Flex>
  );
}

import {useAsyncList} from '@react-stately/data';

function AsyncTable() {
  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,
        cursor
      }) {
        if (cursor) {
          cursor = cursor.replace(
            /^http:\/\//i,
            'https://'
          );
        }

        let res = await fetch(
          cursor ||
            `https://swapi.dev/api/people/?search=`,
          {signal}
        );
        let json = await res.json();

        return {
          items:
            json.results,
          cursor:
            json.next
        };
      }
    }
  );

  return (
    <Flex
      height="size-2000"
      flexGrow={1}
      maxWidth="size-6000">
      <TableView
        aria-label="example async loading table"
        height="100%"
        width="100%">
        <TableHeader
          columns={
            columns
          }>
          {(column) => (
            <Column
              align={
                column.key !==
                'name'
                  ? 'end'
                  : 'start'
              }>
              {
                column.name
              }
            </Column>
          )}
        </TableHeader>
        <TableBody
          items={
            list.items
          }
          loadingState={
            list.loadingState
          }
          onLoadMore={
            list.loadMore
          }>
          {(item) => (
            <Row
              key={
                item.name
              }>
              {(key) => (
                <Cell>
                  {
                    item[
                      key
                    ]
                  }
                </Cell>
              )}
            </Row>
          )}
        </TableBody>
      </TableView>
    </Flex>
  );
}

Selection#

By default, TableView doesn't allow row selection but this can be enabled 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 enables multiple selection mode, and uses defaultSelectedKeys to select the rows with keys "2" and "4".

<TableView
  aria-label="Example table with multiple selection"
  maxWidth="size-6000"
  height="size-3000"
  selectionMode="multiple"
  defaultSelectedKeys={['2', '4']}>
  <TableHeader>
    <Column>Name</Column>
    <Column>Type</Column>
    <Column align="end">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>
</TableView>

<TableView
  aria-label="Example table with multiple selection"
  maxWidth="size-6000"
  height="size-3000"
  selectionMode="multiple"
  defaultSelectedKeys={['2', '4']}>
  <TableHeader>
    <Column>Name</Column>
    <Column>Type</Column>
    <Column align="end">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>
</TableView>

<TableView
  aria-label="Example table with multiple selection"
  maxWidth="size-6000"
  height="size-3000"
  selectionMode="multiple"
  defaultSelectedKeys={[
    '2',
    '4'
  ]}>
  <TableHeader>
    <Column>
      Name
    </Column>
    <Column>
      Type
    </Column>
    <Column align="end">
      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>
</TableView>

Controlled selection#

To programmatically control row selection, use the selectedKeys prop paired with the onSelectionChange callback. The key prop from the selected rows will be passed into the callback when the row is pressed, allowing you to update state 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 [selectedKeys, setSelectedKeys] = React.useState(new Set([2]));

  return (
    <TableView
      aria-label="Table with controlled selection"
      maxWidth="size-6000"
      height="size-3000"
      selectionMode="multiple"
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}
      {...props}>
      <TableHeader columns={columns}>
        {(column) => (
          <Column
            key={column.uid}
            align={column.uid === 'level' ? 'end' : 'start'}>
            {column.name}
          </Column>
        )}
      </TableHeader>
      <TableBody items={rows}>
        {(item) => <Row>{(columnKey) => <Cell>{item[columnKey]}</Cell>}</Row>}
      </TableBody>
    </TableView>
  );
}

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 [selectedKeys, setSelectedKeys] = React.useState(
    new Set([2])
  );

  return (
    <TableView
      aria-label="Table with controlled selection"
      maxWidth="size-6000"
      height="size-3000"
      selectionMode="multiple"
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}
      {...props}>
      <TableHeader columns={columns}>
        {(column) => (
          <Column
            key={column.uid}
            align={
              column.uid === 'level' ? 'end' : 'start'
            }>
            {column.name}
          </Column>
        )}
      </TableHeader>
      <TableBody items={rows}>
        {(item) => (
          <Row>
            {(columnKey) => <Cell>{item[columnKey]}</Cell>}
          </Row>
        )}
      </TableBody>
    </TableView>
  );
}

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 [
    selectedKeys,
    setSelectedKeys
  ] = React.useState(
    new Set([2])
  );

  return (
    <TableView
      aria-label="Table with controlled selection"
      maxWidth="size-6000"
      height="size-3000"
      selectionMode="multiple"
      selectedKeys={
        selectedKeys
      }
      onSelectionChange={
        setSelectedKeys
      }
      {...props}>
      <TableHeader
        columns={
          columns
        }>
        {(column) => (
          <Column
            key={
              column.uid
            }
            align={
              column.uid ===
              'level'
                ? 'end'
                : 'start'
            }>
            {column.name}
          </Column>
        )}
      </TableHeader>
      <TableBody
        items={rows}>
        {(item) => (
          <Row>
            {(
              columnKey
            ) => (
              <Cell>
                {
                  item[
                    columnKey
                  ]
                }
              </Cell>
            )}
          </Row>
        )}
      </TableBody>
    </TableView>
  );
}

Single selection#

To limit users to selecting only a single item at a time, selectionMode can be set to single.

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

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

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

Disallow empty selection#

TableView also supports a disallowEmptySelection prop which forces the user to have at least one row in the TableView selected at all times. In this mode, if a single row is selected and the user presses it, it will not be deselected.

// Using the same table as above
<PokemonTable disallowEmptySelection />

// Using the same table as above
<PokemonTable disallowEmptySelection />

// Using the same table as above
<PokemonTable
  disallowEmptySelection
/>

Disabled rows#

You can disable specific rows by providing an array of keys to TableView via the disabledKeys prop. This will prevent rows from being selectable as shown in the example below.

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

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

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

Sorting#

TableView 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 TableView accepts a sortDescriptor prop that defines the current column key to sort by and the sort direction (ascending/descending). When the user presses a sortable column header, 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.

function AsyncSortTable() {
  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}) {
      return {
        items: items.sort((a, b) => {
          let first = a[sortDescriptor.column];
          let second = b[sortDescriptor.column];
          let cmp =
            (parseInt(first) || first) < (parseInt(second) || second) ? -1 : 1;
          if (sortDescriptor.direction === 'descending') {
            cmp *= -1;
          }
          return cmp;
        })
      };
    }
  });

  return (
    <TableView
      aria-label="Example table with client side sorting"
      height="size-3000"
      maxWidth="size-6000"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}>
      <TableHeader>
        <Column key="name" allowsSorting>
          Name
        </Column>
        <Column key="height" allowsSorting>
          Height
        </Column>
        <Column key="mass" allowsSorting>
          Mass
        </Column>
        <Column key="birth_year" allowsSorting>
          Birth Year
        </Column>
      </TableHeader>
      <TableBody items={list.items} loadingState={list.loadingState}>
        {(item) => (
          <Row key={item.name}>
            {(columnKey) => <Cell>{item[columnKey]}</Cell>}
          </Row>
        )}
      </TableBody>
    </TableView>
  );
}

function AsyncSortTable() {
  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}) {
      return {
        items: items.sort((a, b) => {
          let first = a[sortDescriptor.column];
          let second = b[sortDescriptor.column];
          let cmp =
            (parseInt(first) || first) <
            (parseInt(second) || second)
              ? -1
              : 1;
          if (sortDescriptor.direction === 'descending') {
            cmp *= -1;
          }
          return cmp;
        })
      };
    }
  });

  return (
    <TableView
      aria-label="Example table with client side sorting"
      height="size-3000"
      maxWidth="size-6000"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}>
      <TableHeader>
        <Column key="name" allowsSorting>
          Name
        </Column>
        <Column key="height" allowsSorting>
          Height
        </Column>
        <Column key="mass" allowsSorting>
          Mass
        </Column>
        <Column key="birth_year" allowsSorting>
          Birth Year
        </Column>
      </TableHeader>
      <TableBody
        items={list.items}
        loadingState={list.loadingState}>
        {(item) => (
          <Row key={item.name}>
            {(columnKey) => <Cell>{item[columnKey]}</Cell>}
          </Row>
        )}
      </TableBody>
    </TableView>
  );
}

function AsyncSortTable() {
  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
      }) {
        return {
          items: items.sort(
            (a, b) => {
              let first =
                a[
                  sortDescriptor
                    .column
                ];
              let second =
                b[
                  sortDescriptor
                    .column
                ];
              let cmp =
                (parseInt(
                  first
                ) ||
                  first) <
                (parseInt(
                  second
                ) ||
                  second)
                  ? -1
                  : 1;
              if (
                sortDescriptor.direction ===
                'descending'
              ) {
                cmp *= -1;
              }
              return cmp;
            }
          )
        };
      }
    }
  );

  return (
    <TableView
      aria-label="Example table with client side sorting"
      height="size-3000"
      maxWidth="size-6000"
      sortDescriptor={
        list.sortDescriptor
      }
      onSortChange={
        list.sort
      }>
      <TableHeader>
        <Column
          key="name"
          allowsSorting>
          Name
        </Column>
        <Column
          key="height"
          allowsSorting>
          Height
        </Column>
        <Column
          key="mass"
          allowsSorting>
          Mass
        </Column>
        <Column
          key="birth_year"
          allowsSorting>
          Birth Year
        </Column>
      </TableHeader>
      <TableBody
        items={
          list.items
        }
        loadingState={
          list.loadingState
        }>
        {(item) => (
          <Row
            key={
              item.name
            }>
            {(
              columnKey
            ) => (
              <Cell>
                {
                  item[
                    columnKey
                  ]
                }
              </Cell>
            )}
          </Row>
        )}
      </TableBody>
    </TableView>
  );
}

Props#

TableView props#

TableHeader props#

Column props#

TableBody props#

Row props#

Cell props#

Visual options#

Column alignment#

View guidelines

<Flex flexGrow={1} maxWidth="size-4600">
  <TableView
    aria-label="Example table for column alignment"
    width="100%"
    height="100%">
    <TableHeader>
      <Column align="start">Name</Column>
      <Column align="center">Type</Column>
      <Column align="end">Size</Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>2021406_Proposal</Cell>
        <Cell>PDF</Cell>
        <Cell>86 KB</Cell>
      </Row>
      <Row>
        <Cell>Budget Template</Cell>
        <Cell>XLS</Cell>
        <Cell>120 KB</Cell>
      </Row>
      <Row>
        <Cell>Onboarding</Cell>
        <Cell>PPT</Cell>
        <Cell>472 KB</Cell>
      </Row>
      <Row>
        <Cell>Welcome</Cell>
        <Cell>TXT</Cell>
        <Cell>24 KB</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex flexGrow={1} maxWidth="size-4600">
  <TableView
    aria-label="Example table for column alignment"
    width="100%"
    height="100%">
    <TableHeader>
      <Column align="start">Name</Column>
      <Column align="center">Type</Column>
      <Column align="end">Size</Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>2021406_Proposal</Cell>
        <Cell>PDF</Cell>
        <Cell>86 KB</Cell>
      </Row>
      <Row>
        <Cell>Budget Template</Cell>
        <Cell>XLS</Cell>
        <Cell>120 KB</Cell>
      </Row>
      <Row>
        <Cell>Onboarding</Cell>
        <Cell>PPT</Cell>
        <Cell>472 KB</Cell>
      </Row>
      <Row>
        <Cell>Welcome</Cell>
        <Cell>TXT</Cell>
        <Cell>24 KB</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-4600">
  <TableView
    aria-label="Example table for column alignment"
    width="100%"
    height="100%">
    <TableHeader>
      <Column align="start">
        Name
      </Column>
      <Column align="center">
        Type
      </Column>
      <Column align="end">
        Size
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>
          2021406_Proposal
        </Cell>
        <Cell>
          PDF
        </Cell>
        <Cell>
          86 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Budget
          Template
        </Cell>
        <Cell>
          XLS
        </Cell>
        <Cell>
          120 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Onboarding
        </Cell>
        <Cell>
          PPT
        </Cell>
        <Cell>
          472 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Welcome
        </Cell>
        <Cell>
          TXT
        </Cell>
        <Cell>
          24 KB
        </Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

Column widths#

Columns support three different width props: minWidth, width, and maxWidth.

<Flex flexGrow={1} maxWidth="size-4600">
  <TableView
    aria-label="Example table for column widths"
    width="100%"
    height="100%">
    <TableHeader>
      <Column maxWidth={300} align="start">
        Name
      </Column>
      <Column width={80}>Type</Column>
      <Column minWidth={100} align="end">
        Size
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>2021406_Proposal</Cell>
        <Cell>PDF</Cell>
        <Cell>86 KB</Cell>
      </Row>
      <Row>
        <Cell>Budget Template</Cell>
        <Cell>XLS</Cell>
        <Cell>120 KB</Cell>
      </Row>
      <Row>
        <Cell>Onboarding</Cell>
        <Cell>PPT</Cell>
        <Cell>472 KB</Cell>
      </Row>
      <Row>
        <Cell>Welcome</Cell>
        <Cell>TXT</Cell>
        <Cell>24 KB</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex flexGrow={1} maxWidth="size-4600">
  <TableView
    aria-label="Example table for column widths"
    width="100%"
    height="100%">
    <TableHeader>
      <Column maxWidth={300} align="start">
        Name
      </Column>
      <Column width={80}>Type</Column>
      <Column minWidth={100} align="end">
        Size
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>2021406_Proposal</Cell>
        <Cell>PDF</Cell>
        <Cell>86 KB</Cell>
      </Row>
      <Row>
        <Cell>Budget Template</Cell>
        <Cell>XLS</Cell>
        <Cell>120 KB</Cell>
      </Row>
      <Row>
        <Cell>Onboarding</Cell>
        <Cell>PPT</Cell>
        <Cell>472 KB</Cell>
      </Row>
      <Row>
        <Cell>Welcome</Cell>
        <Cell>TXT</Cell>
        <Cell>24 KB</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-4600">
  <TableView
    aria-label="Example table for column widths"
    width="100%"
    height="100%">
    <TableHeader>
      <Column
        maxWidth={300}
        align="start">
        Name
      </Column>
      <Column
        width={80}>
        Type
      </Column>
      <Column
        minWidth={100}
        align="end">
        Size
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>
          2021406_Proposal
        </Cell>
        <Cell>
          PDF
        </Cell>
        <Cell>
          86 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Budget
          Template
        </Cell>
        <Cell>
          XLS
        </Cell>
        <Cell>
          120 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Onboarding
        </Cell>
        <Cell>
          PPT
        </Cell>
        <Cell>
          472 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Welcome
        </Cell>
        <Cell>
          TXT
        </Cell>
        <Cell>
          24 KB
        </Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

Column dividers#

View guidelines

<Flex flexGrow={1} maxWidth="size-4600">
  <TableView
    aria-label="Example table for column dividers"
    width="100%"
    height="100%">
    <TableHeader>
      <Column align="start" showDivider>
        Name
      </Column>
      <Column showDivider>Type</Column>
      <Column align="end" showDivider>
        Size
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>2021406_Proposal</Cell>
        <Cell>PDF</Cell>
        <Cell>86 KB</Cell>
      </Row>
      <Row>
        <Cell>Budget Template</Cell>
        <Cell>XLS</Cell>
        <Cell>120 KB</Cell>
      </Row>
      <Row>
        <Cell>Onboarding</Cell>
        <Cell>PPT</Cell>
        <Cell>472 KB</Cell>
      </Row>
      <Row>
        <Cell>Welcome</Cell>
        <Cell>TXT</Cell>
        <Cell>24 KB</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex flexGrow={1} maxWidth="size-4600">
  <TableView
    aria-label="Example table for column dividers"
    width="100%"
    height="100%">
    <TableHeader>
      <Column align="start" showDivider>
        Name
      </Column>
      <Column showDivider>Type</Column>
      <Column align="end" showDivider>
        Size
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>2021406_Proposal</Cell>
        <Cell>PDF</Cell>
        <Cell>86 KB</Cell>
      </Row>
      <Row>
        <Cell>Budget Template</Cell>
        <Cell>XLS</Cell>
        <Cell>120 KB</Cell>
      </Row>
      <Row>
        <Cell>Onboarding</Cell>
        <Cell>PPT</Cell>
        <Cell>472 KB</Cell>
      </Row>
      <Row>
        <Cell>Welcome</Cell>
        <Cell>TXT</Cell>
        <Cell>24 KB</Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-4600">
  <TableView
    aria-label="Example table for column dividers"
    width="100%"
    height="100%">
    <TableHeader>
      <Column
        align="start"
        showDivider>
        Name
      </Column>
      <Column
        showDivider>
        Type
      </Column>
      <Column
        align="end"
        showDivider>
        Size
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>
          2021406_Proposal
        </Cell>
        <Cell>
          PDF
        </Cell>
        <Cell>
          86 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Budget
          Template
        </Cell>
        <Cell>
          XLS
        </Cell>
        <Cell>
          120 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Onboarding
        </Cell>
        <Cell>
          PPT
        </Cell>
        <Cell>
          472 KB
        </Cell>
      </Row>
      <Row>
        <Cell>
          Welcome
        </Cell>
        <Cell>
          TXT
        </Cell>
        <Cell>
          24 KB
        </Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>

Focusable cells#

Cells accept any renderable node, allowing you to have focusable children within the TableView.

import Edit from '@spectrum-icons/workflow/Edit';
import Delete from '@spectrum-icons/workflow/Delete';

<Flex maxWidth="size-3000" flexGrow={1}>
  <TableView
    aria-label="Example table for focusable cells"
    width="100%"
    height="100%">
    <TableHeader>
      <Column>Name</Column>
      <Column hideHeader>Add</Column>
      <Column hideHeader>Delete</Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>Red Panda</Cell>
        <Cell>
          <ActionButton isQuiet>
            <Edit />
          </ActionButton>
        </Cell>
        <Cell>
          <ActionButton isQuiet>
            <Delete />
          </ActionButton>
        </Cell>
      </Row>
      <Row>
        <Cell>Harbor Seal</Cell>
        <Cell>
          <ActionButton isQuiet>
            <Edit />
          </ActionButton>
        </Cell>
        <Cell>
          <ActionButton isQuiet>
            <Delete />
          </ActionButton>
        </Cell>
      </Row>
      <Row>
        <Cell>Groundhog</Cell>
        <Cell>
          <ActionButton isQuiet>
            <Edit />
          </ActionButton>
        </Cell>
        <Cell>
          <ActionButton isQuiet>
            <Delete />
          </ActionButton>
        </Cell>
      </Row>
      <Row>
        <Cell>Otter</Cell>
        <Cell>
          <ActionButton isQuiet>
            <Edit />
          </ActionButton>
        </Cell>
        <Cell>
          <ActionButton isQuiet>
            <Delete />
          </ActionButton>
        </Cell>
      </Row>
    </TableBody>
  </TableView>
</Flex>