TableView

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

Example#

<TableView
  aria-label="Example table with static contents"
  selectionMode="multiple"
>
  <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>

<TableView
  aria-label="Example table with static contents"
  selectionMode="multiple"
>
  <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>

<TableView
  aria-label="Example table with static contents"
  selectionMode="multiple"
>
  <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>

Content#

TableView is a complex collection component that is built up from many child elements including columns, rows, and cells. Columns are defined within a TableHeader element and rows are defined within a TableBody element. Rows contain Cell elements that correspond to each column. Cells can contain any element, allowing you to have focusable children within the TableView.

Basic usage of TableView, seen in the example above, shows the use of a static collection where the contents of the TableView is hard coded. Dynamic collections, as shown below, can be used when the options come from an external data source such as an API, or update over time. Providing the data in this way allows TableView to automatically cache the rendering of each item, which dramatically improves performance.

Columns and rows can be statically defined as children, or generated dynamically using a function based on the data passed to the columns or items prop respectively. Cells can also be statically defined as children, or generated dynamically based on the columns defined in the TableHeader.

Each column and row has a unique key defined by the data. In the example below, the uid property of the column object is used as the key for the Column element within the TableHeader. The key of each row element is implicitly defined by the id property of the row object. See collections to learn more keys in dynamic collections.

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"
  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"
  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"
  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>

Layout#

TableViews are often contained within a page layout that defines the size of the table. For example, a page might have a header or toolbar with a TableView below that fills the remaining vertical space. TableView is designed to scroll internally while the column headers remain fixed. Because of this, TableViews should not be placed within a scrollable container.

The example below shows how to use a Flex component to achieve the layout described above. Note the TableView uses the flex prop to fill the remainder of the available space.

<Flex height="size-5000" width="100%" direction="column" gap="size-150">
  <ActionButton alignSelf="start">Add</ActionButton>
  <TableView
    flex
    aria-label="Example table with dynamic content"
  >
    <TableHeader columns={columns}>
      {(column) => (
        <Column
          key={column.id}
        >
          {column.name}
        </Column>
      )}
    </TableHeader>
    <TableBody items={rows}>
      {(item) => (
        <Row>
          {(columnKey) => <Cell>{item[columnKey]}</Cell>}
        </Row>
      )}
    </TableBody>
  </TableView>
</Flex>

<Flex
  height="size-5000"
  width="100%"
  direction="column"
  gap="size-150"
>
  <ActionButton alignSelf="start">Add</ActionButton>
  <TableView
    flex
    aria-label="Example table with dynamic content"
  >
    <TableHeader columns={columns}>
      {(column) => (
        <Column
          key={column.id}
        >
          {column.name}
        </Column>
      )}
    </TableHeader>
    <TableBody items={rows}>
      {(item) => (
        <Row>
          {(columnKey) => <Cell>{item[columnKey]}</Cell>}
        </Row>
      )}
    </TableBody>
  </TableView>
</Flex>

<Flex
  height="size-5000"
  width="100%"
  direction="column"
  gap="size-150"
>
  <ActionButton alignSelf="start">
    Add
  </ActionButton>
  <TableView
    flex
    aria-label="Example table with dynamic content"
  >
    <TableHeader
      columns={columns}
    >
      {(column) => (
        <Column
          key={column
            .id}
        >
          {column.name}
        </Column>
      )}
    </TableHeader>
    <TableBody
      items={rows}
    >
      {(item) => (
        <Row>
          {(columnKey) => (
            <Cell>
              {item[
                columnKey
              ]}
            </Cell>
          )}
        </Row>
      )}
    </TableBody>
  </TableView>
</Flex>

Internationalization#

To internationalize a TableView, all text content within the TableView should be localized. 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").

<TableView aria-label="Example table with static contents">
  <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>

<TableView aria-label="Example table with static contents">
  <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>

<TableView aria-label="Example table with static contents">
  <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>

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';

interface Character {
  name: string;
  height: number;
  mass: number;
  birth_year: number;
}

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

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

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

  return (
    <TableView aria-label="example async loading table" height="size-3000">
      <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>
  );
}

import {useAsyncList} from 'react-stately';

interface Character {
  name: string;
  height: number;
  mass: number;
  birth_year: number;
}

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

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

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

  return (
    <TableView
      aria-label="example async loading table"
      height="size-3000"
    >
      <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>
  );
}

import {useAsyncList} from 'react-stately';

interface Character {
  name: string;
  height: number;
  mass: number;
  birth_year: number;
}

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

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

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

  return (
    <TableView
      aria-label="example async loading table"
      height="size-3000"
    >
      <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>
  );
}

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"
  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"
  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"
  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.

import type {Selection} from '@adobe/react-spectrum';

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<Selection>(new Set([2]));

  return (
    <TableView
      aria-label="Table with controlled selection"
      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>
  );
}

import type {Selection} from '@adobe/react-spectrum';

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<
    Selection
  >(new Set([2]));

  return (
    <TableView
      aria-label="Table with controlled selection"
      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>
  );
}

import type {Selection} from '@adobe/react-spectrum';

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<
    Selection
  >(new Set([2]));

  return (
    <TableView
      aria-label="Table with controlled selection"
      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]}
/>

Highlight selection#

By default, TableView uses the checkbox selection style, which includes a checkbox in each row for selection. When the selectionStyle prop is set to "highlight", the checkboxes are hidden, and the selected rows are displayed with a highlighted background instead.

In addition to changing the appearance, the selection behavior also changes depending on the selectionStyle prop. In the default checkbox selection style, clicking, tapping, or pressing the Space or Enter keys toggles selection for the focused row. Using the arrow keys moves focus but does not change selection.

In the highlight selection style, however, clicking a row with the mouse replaces the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as Ctrl, Cmd, and Shift can be used. On touch screen devices, selection always behaves as toggle since modifier keys may not be available.

These selection styles implement the behaviors defined in Aria Practices.

<PokemonTable selectionMode="multiple" selectionStyle="highlight" />

<PokemonTable
  selectionMode="multiple"
  selectionStyle="highlight"
/>

<PokemonTable
  selectionMode="multiple"
  selectionStyle="highlight"
/>

Row actions#

TableView supports row actions via the onAction prop, which is useful for functionality such as navigation. When nothing is selected, the TableView performs actions by default when clicking or tapping a row. Items may be selected using the checkbox, or by long pressing on touch devices. When at least one item is selected, the TableView is in selection mode, and clicking or tapping a row toggles the selection. Actions may also be triggered via the Enter key, and selection using the Space key.

This behavior is slightly different in the highlight selection style, where single clicking selects the row and actions are performed via double click. Touch and keyboard behaviors are unaffected.

<Flex direction="column" gap="size-300">
  <PokemonTable
    aria-label="Pokemon table with row actions and checkbox selection"
    selectionMode="multiple"
    onAction={(key) => alert(`Opening item ${key}...`)}
  />
  <PokemonTable
    aria-label="Pokemon table with row actions and highlight selection"
    selectionMode="multiple"
    selectionStyle="highlight"
    onAction={(key) => alert(`Opening item ${key}...`)}
  />
</Flex>

<Flex direction="column" gap="size-300">
  <PokemonTable
    aria-label="Pokemon table with row actions and checkbox selection"
    selectionMode="multiple"
    onAction={(key) => alert(`Opening item ${key}...`)}
  />
  <PokemonTable
    aria-label="Pokemon table with row actions and highlight selection"
    selectionMode="multiple"
    selectionStyle="highlight"
    onAction={(key) => alert(`Opening item ${key}...`)}
  />
</Flex>

<Flex
  direction="column"
  gap="size-300"
>
  <PokemonTable
    aria-label="Pokemon table with row actions and checkbox selection"
    selectionMode="multiple"
    onAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}
  />
  <PokemonTable
    aria-label="Pokemon table with row actions and highlight selection"
    selectionMode="multiple"
    selectionStyle="highlight"
    onAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}
  />
</Flex>

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.

import {useCollator} from '@adobe/react-spectrum';

interface Character {
  name: string;
  height: number;
  mass: number;
  birth_year: number;
}

function AsyncSortTable() {
  let collator = useCollator({ numeric: true });

  let list = useAsyncList<Character>({
    async load({ signal }) {
      let res = await fetch(`https://swapi.py4e.com/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 = collator.compare(first, second);
          if (sortDescriptor.direction === 'descending') {
            cmp *= -1;
          }
          return cmp;
        })
      };
    }
  });

  return (
    <TableView
      aria-label="Example table with client side sorting"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}
      height="size-3000"
    >
      <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>
  );
}

import {useCollator} from '@adobe/react-spectrum';

interface Character {
  name: string;
  height: number;
  mass: number;
  birth_year: number;
}

function AsyncSortTable() {
  let collator = useCollator({ numeric: true });

  let list = useAsyncList<Character>({
    async load({ signal }) {
      let res = await fetch(
        `https://swapi.py4e.com/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 = collator.compare(first, second);
          if (sortDescriptor.direction === 'descending') {
            cmp *= -1;
          }
          return cmp;
        })
      };
    }
  });

  return (
    <TableView
      aria-label="Example table with client side sorting"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}
      height="size-3000"
    >
      <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>
  );
}

import {useCollator} from '@adobe/react-spectrum';

interface Character {
  name: string;
  height: number;
  mass: number;
  birth_year: number;
}

function AsyncSortTable() {
  let collator =
    useCollator({
      numeric: true
    });

  let list =
    useAsyncList<
      Character
    >({
      async load(
        { signal }
      ) {
        let res =
          await fetch(
            `https://swapi.py4e.com/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 =
                  collator
                    .compare(
                      first,
                      second
                    );
                if (
                  sortDescriptor
                    .direction ===
                    'descending'
                ) {
                  cmp *=
                    -1;
                }
                return cmp;
              }
            )
        };
      }
    });

  return (
    <TableView
      aria-label="Example table with client side sorting"
      sortDescriptor={list
        .sortDescriptor}
      onSortChange={list
        .sort}
      height="size-3000"
    >
      <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>
  );
}

Column widths#

By default, TableView divides the available space evenly among the columns. The Column component also supports four different width props that allow you to control column sizing behavior: defaultWidth, width, minWidth, and maxWidth.

The width and defaultWidth props define the width of a column. The former defines a controlled width, and the latter defines an uncontrolled width when the column is resizable. These props accept fixed pixel values, percentages of the total table width, or fractional values (the fr unit), which represent a fraction of the available space. Columns without a defined width are equivalent to 1fr.

The minWidth and maxWidth props define constraints on the size of a column, which may be defined either as fixed pixel values or as percentages of the total table width. These are respected when calculating the size of a column, and also provide limits for column resizing.

<TableView aria-label="Example table for column widths" maxWidth={320}>
  <TableHeader>
    <Column defaultWidth="1fr" align="start">Name</Column>
    <Column maxWidth={80}>Type</Column>
    <Column width={80}>Size</Column>
    <Column minWidth={100} align="end">Date Modified</Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>2021406_Proposal</Cell>
      <Cell>PDF</Cell>
      <Cell>86 KB</Cell>
      <Cell>April 12</Cell>
    </Row>
    <Row>
      <Cell>Budget Template</Cell>
      <Cell>XLS</Cell>
      <Cell>120 KB</Cell>
      <Cell>November 27</Cell>
    </Row>
    <Row>
      <Cell>Onboarding</Cell>
      <Cell>PPT</Cell>
      <Cell>472 KB</Cell>
      <Cell>January 7</Cell>
    </Row>
    <Row>
      <Cell>Welcome</Cell>
      <Cell>TXT</Cell>
      <Cell>24 KB</Cell>
      <Cell>February 11</Cell>
    </Row>
  </TableBody>
</TableView>

<TableView
  aria-label="Example table for column widths"
  maxWidth={320}
>
  <TableHeader>
    <Column defaultWidth="1fr" align="start">Name</Column>
    <Column maxWidth={80}>Type</Column>
    <Column width={80}>Size</Column>
    <Column minWidth={100} align="end">
      Date Modified
    </Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>2021406_Proposal</Cell>
      <Cell>PDF</Cell>
      <Cell>86 KB</Cell>
      <Cell>April 12</Cell>
    </Row>
    <Row>
      <Cell>Budget Template</Cell>
      <Cell>XLS</Cell>
      <Cell>120 KB</Cell>
      <Cell>November 27</Cell>
    </Row>
    <Row>
      <Cell>Onboarding</Cell>
      <Cell>PPT</Cell>
      <Cell>472 KB</Cell>
      <Cell>January 7</Cell>
    </Row>
    <Row>
      <Cell>Welcome</Cell>
      <Cell>TXT</Cell>
      <Cell>24 KB</Cell>
      <Cell>February 11</Cell>
    </Row>
  </TableBody>
</TableView>

<TableView
  aria-label="Example table for column widths"
  maxWidth={320}
>
  <TableHeader>
    <Column
      defaultWidth="1fr"
      align="start"
    >
      Name
    </Column>
    <Column
      maxWidth={80}
    >
      Type
    </Column>
    <Column width={80}>
      Size
    </Column>
    <Column
      minWidth={100}
      align="end"
    >
      Date Modified
    </Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>
        2021406_Proposal
      </Cell>
      <Cell>PDF</Cell>
      <Cell>
        86 KB
      </Cell>
      <Cell>
        April 12
      </Cell>
    </Row>
    <Row>
      <Cell>
        Budget Template
      </Cell>
      <Cell>XLS</Cell>
      <Cell>
        120 KB
      </Cell>
      <Cell>
        November 27
      </Cell>
    </Row>
    <Row>
      <Cell>
        Onboarding
      </Cell>
      <Cell>PPT</Cell>
      <Cell>
        472 KB
      </Cell>
      <Cell>
        January 7
      </Cell>
    </Row>
    <Row>
      <Cell>
        Welcome
      </Cell>
      <Cell>TXT</Cell>
      <Cell>
        24 KB
      </Cell>
      <Cell>
        February 11
      </Cell>
    </Row>
  </TableBody>
</TableView>

Column Resizing beta#

TableView supports resizable columns, allowing users to dynamically adjust the width of a column. To designate that a Column is resizable, provide it with the allowsResizing prop. This will render a draggable resizer handle that becomes visible on hover. Keyboard, touch, and screen reader users can start resizing by interacting with the target column's header and selecting the "Resize column" option from the dropdown.

Width values#

An initial, uncontrolled width can be provided to a Column using the defaultWidth prop. This allows the column width to freely shrink and grow in relation to other column widths. Alternatively, a controlled value can be provided by the width prop. The minWidth and maxWidth props allow you to restrict a Column's size. See column widths above for more details.

The example below illustrates how each of the column width props affects their respective column's resize behavior.

<TableView
  aria-label="TableView with resizable columns"
  maxWidth={320}
  height={200} >
  <TableHeader>
    <Column key="file" allowsResizing maxWidth={500}>File Name</Column>
    <Column key="size" width={80}>Size</Column>
    <Column key="date" allowsResizing minWidth={100}>Date Modified</Column>  </TableHeader>
  <TableBody>
    <Row>
      <Cell>2022-Roadmap-Proposal-Revision-012822-Copy(2)</Cell>
      <Cell>214 KB</Cell>
      <Cell>November 27, 2022 at 4:56PM</Cell>
    </Row>
    <Row>
      <Cell>62259692_p0_master1200</Cell>
      <Cell>120 KB</Cell>
      <Cell>January 27, 2021 at 1:56AM</Cell>
    </Row>
  </TableBody>
</TableView>

<TableView
  aria-label="TableView with resizable columns"
  maxWidth={320}
  height={200}
>
  <TableHeader>
    <Column key="file" allowsResizing maxWidth={500}>
      File Name
    </Column>
    <Column key="size" width={80}>Size</Column>
    <Column key="date" allowsResizing minWidth={100}>
      Date Modified
    </Column>  </TableHeader>
  <TableBody>
    <Row>
      <Cell>
        2022-Roadmap-Proposal-Revision-012822-Copy(2)
      </Cell>
      <Cell>214 KB</Cell>
      <Cell>November 27, 2022 at 4:56PM</Cell>
    </Row>
    <Row>
      <Cell>62259692_p0_master1200</Cell>
      <Cell>120 KB</Cell>
      <Cell>January 27, 2021 at 1:56AM</Cell>
    </Row>
  </TableBody>
</TableView>

<TableView
  aria-label="TableView with resizable columns"
  maxWidth={320}
  height={200}
>
  <TableHeader>
    <Column
      key="file"
      allowsResizing
      maxWidth={500}
    >
      File Name
    </Column>
    <Column
      key="size"
      width={80}
    >
      Size
    </Column>
    <Column
      key="date"
      allowsResizing
      minWidth={100}
    >
      Date Modified
    </Column>  </TableHeader>
  <TableBody>
    <Row>
      <Cell>
        2022-Roadmap-Proposal-Revision-012822-Copy(2)
      </Cell>
      <Cell>
        214 KB
      </Cell>
      <Cell>
        November 27,
        2022 at 4:56PM
      </Cell>
    </Row>
    <Row>
      <Cell>
        62259692_p0_master1200
      </Cell>
      <Cell>
        120 KB
      </Cell>
      <Cell>
        January 27,
        2021 at 1:56AM
      </Cell>
    </Row>
  </TableBody>
</TableView>

Resize events#

TableView accepts an onResize prop which is triggered whenever a column resizer is moved by the user. This can be used in combination with the width prop to update a Column's width in a controlled fashion. TableView also accepts an onResizeEnd prop, which is triggered when the user finishes a column resize operation. Both events receive a Map object containing the widths of every column in the TableView.

The example below uses onResize to update each of the TableView's controlled column widths. It also saves the finalized column widths to localStorage in onResizeEnd, allowing the TableView's state to be preserved between page loads and refreshes.

let items = [
  {
    id: '1',
    file: '2022-Roadmap-Proposal-Revision-012822-Copy(2)',
    size: '214 KB',
    date: 'November 27, 2022 at 4:56PM'
  },
  {
    id: '2',
    file: '62259692_p0_master1200',
    size: '120 KB',
    date: 'January 27, 2021 at 1:56AM'
  }
];

let columnsData = [
  { name: 'File Name', id: 'file', width: '1fr' },
  { name: 'Size', id: 'size', width: 80 },
  { name: 'Date', id: 'date', width: 100 }
];

function ResizableTable() {
  let [columns, setColumns] = React.useState(() => {
    let localStorageWidths = localStorage.getItem('RSPWidths');
    if (localStorageWidths) {
      let widths = JSON.parse(localStorageWidths);
      return columnsData.map((col) => ({ ...col, width: widths[col.id] }));
    } else {
      return columnsData;
    }
  });

  let onResize = (widths) => {
    setColumns((columns) =>
      columns.map((col) => ({ ...col, width: widths.get(col.id) }))
    );
  };

  let onResizeEnd = (widths) => {
    localStorage.setItem(
      'RSPWidths',
      JSON.stringify(Object.fromEntries(widths))
    );
  };
  return (
    <TableView
      onResize={onResize}
      onResizeEnd={onResizeEnd}      aria-label="TableView with controlled, resizable columns saved in local storage"
      maxWidth={320}
      height={200}
    >
      <TableHeader columns={columns}>
        {(column) => {
          const { name, id, width } = column;
          return <Column allowsResizing key={id} width={width}>{name}</Column>;
        }}
      </TableHeader>
      <TableBody items={items}>
        {(item) => <Row key={item.id}>{(key) => <Cell>{item[key]}</Cell>}</Row>}
      </TableBody>
    </TableView>
  );
}

<ResizableTable />

let items = [
  {
    id: '1',
    file: '2022-Roadmap-Proposal-Revision-012822-Copy(2)',
    size: '214 KB',
    date: 'November 27, 2022 at 4:56PM'
  },
  {
    id: '2',
    file: '62259692_p0_master1200',
    size: '120 KB',
    date: 'January 27, 2021 at 1:56AM'
  }
];

let columnsData = [
  { name: 'File Name', id: 'file', width: '1fr' },
  { name: 'Size', id: 'size', width: 80 },
  { name: 'Date', id: 'date', width: 100 }
];

function ResizableTable() {
  let [columns, setColumns] = React.useState(() => {
    let localStorageWidths = localStorage.getItem(
      'RSPWidths'
    );
    if (localStorageWidths) {
      let widths = JSON.parse(localStorageWidths);
      return columnsData.map((col) => ({
        ...col,
        width: widths[col.id]
      }));
    } else {
      return columnsData;
    }
  });

  let onResize = (widths) => {
    setColumns((columns) =>
      columns.map((col) => ({
        ...col,
        width: widths.get(col.id)
      }))
    );
  };

  let onResizeEnd = (widths) => {
    localStorage.setItem(
      'RSPWidths',
      JSON.stringify(Object.fromEntries(widths))
    );
  };
  return (
    <TableView
      onResize={onResize}
      onResizeEnd={onResizeEnd}      aria-label="TableView with controlled, resizable columns saved in local storage"
      maxWidth={320}
      height={200}
    >
      <TableHeader columns={columns}>
        {(column) => {
          const { name, id, width } = column;
          return (
            <Column allowsResizing key={id} width={width}>
              {name}
            </Column>
          );
        }}
      </TableHeader>
      <TableBody items={items}>
        {(item) => (
          <Row key={item.id}>
            {(key) => <Cell>{item[key]}</Cell>}
          </Row>
        )}
      </TableBody>
    </TableView>
  );
}

<ResizableTable />

let items = [
  {
    id: '1',
    file:
      '2022-Roadmap-Proposal-Revision-012822-Copy(2)',
    size: '214 KB',
    date:
      'November 27, 2022 at 4:56PM'
  },
  {
    id: '2',
    file:
      '62259692_p0_master1200',
    size: '120 KB',
    date:
      'January 27, 2021 at 1:56AM'
  }
];

let columnsData = [
  {
    name: 'File Name',
    id: 'file',
    width: '1fr'
  },
  {
    name: 'Size',
    id: 'size',
    width: 80
  },
  {
    name: 'Date',
    id: 'date',
    width: 100
  }
];

function ResizableTable() {
  let [
    columns,
    setColumns
  ] = React.useState(
    () => {
      let localStorageWidths =
        localStorage
          .getItem(
            'RSPWidths'
          );
      if (
        localStorageWidths
      ) {
        let widths = JSON
          .parse(
            localStorageWidths
          );
        return columnsData
          .map(
            (col) => ({
              ...col,
              width:
                widths[
                  col.id
                ]
            })
          );
      } else {
        return columnsData;
      }
    }
  );

  let onResize = (
    widths
  ) => {
    setColumns(
      (columns) =>
        columns.map(
          (col) => ({
            ...col,
            width: widths
              .get(
                col.id
              )
          })
        )
    );
  };

  let onResizeEnd = (
    widths
  ) => {
    localStorage.setItem(
      'RSPWidths',
      JSON.stringify(
        Object
          .fromEntries(
            widths
          )
      )
    );
  };
  return (
    <TableView
      onResize={onResize}
      onResizeEnd={onResizeEnd}      aria-label="TableView with controlled, resizable columns saved in local storage"
      maxWidth={320}
      height={200}
    >
      <TableHeader
        columns={columns}
      >
        {(column) => {
          const {
            name,
            id,
            width
          } = column;
          return (
            <Column
              allowsResizing
              key={id}
              width={width}
            >
              {name}
            </Column>
          );
        }}
      </TableHeader>
      <TableBody
        items={items}
      >
        {(item) => (
          <Row
            key={item.id}
          >
            {(key) => (
              <Cell>
                {item[
                  key
                ]}
              </Cell>
            )}
          </Row>
        )}
      </TableBody>
    </TableView>
  );
}

<ResizableTable />

Props#

TableView props#