Table

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">
  <Table
    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>
  </Table>
</Flex>

<Flex flexGrow={1} maxWidth="size-6000">
  <Table
    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>
  </Table>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-6000">
  <Table
    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>
  </Table>
</Flex>

Content#

Table 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 Table, 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 Table 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 Table 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.

function Example() {
  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'}
  ];

  return (
    <Flex flexGrow={1} maxWidth="size-6000">
      <Table
        aria-label="Example table with dynamic content"
        width="100%"
        height="100%">
        <TableHeader columns={columns}>
          {(column) => (
            <Column
              key={column.uid}
              align={column.uid === 'date' ? 'end' : 'start'}>
              {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>
    </Flex>
  );
}

function Example() {
  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'
    }
  ];

  return (
    <Flex flexGrow={1} maxWidth="size-6000">
      <Table
        aria-label="Example table with dynamic content"
        width="100%"
        height="100%">
        <TableHeader columns={columns}>
          {(column) => (
            <Column
              key={column.uid}
              align={
                column.uid === 'date' ? 'end' : 'start'
              }>
              {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>
    </Flex>
  );
}

function Example() {
  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'
    }
  ];

  return (
    <Flex
      flexGrow={1}
      maxWidth="size-6000">
      <Table
        aria-label="Example table with dynamic content"
        width="100%"
        height="100%">
        <TableHeader
          columns={
            columns
          }>
          {(column) => (
            <Column
              key={
                column.uid
              }
              align={
                column.uid ===
                'date'
                  ? 'end'
                  : 'start'
              }>
              {
                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>
    </Flex>
  );
}

Internationalization#

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

Labeling#

Accessibility#

An aria-label must be provided to the Table for accessibility. If the Table 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 Table 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 Table.

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">
  <Table
    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>
  </Table>
</Flex>

<Flex flexGrow={1} maxWidth="size-3000">
  <Table
    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>
  </Table>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-3000">
  <Table
    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>
  </Table>
</Flex>

Asynchronous loading#

Table supports loading data asynchronously, and will display a progress circle reflecting the current load state, set by the isLoading 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">
      <Table
        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}
          isLoading={list.isLoading}
          onLoadMore={list.loadMore}>
          {(item) => (
            <Row key={item.name}>{(key) => <Cell>{item[key]}</Cell>}</Row>
          )}
        </TableBody>
      </Table>
    </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">
      <Table
        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}
          isLoading={list.isLoading}
          onLoadMore={list.loadMore}>
          {(item) => (
            <Row key={item.name}>
              {(key) => <Cell>{item[key]}</Cell>}
            </Row>
          )}
        </TableBody>
      </Table>
    </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">
      <Table
        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
          }
          isLoading={
            list.isLoading
          }
          onLoadMore={
            list.loadMore
          }>
          {(item) => (
            <Row
              key={
                item.name
              }>
              {(key) => (
                <Cell>
                  {
                    item[
                      key
                    ]
                  }
                </Cell>
              )}
            </Row>
          )}
        </TableBody>
      </Table>
    </Flex>
  );
}

Events#

Selection#

Table supports multiple selection modes. By default, selection is disabled, 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".

<Flex flexGrow={1} maxWidth="size-6000">
  <Table
    aria-label="Example table with single selection (uncontrolled)"
    width="100%"
    height="100%"
    selectionMode="single"
    defaultSelectedKeys={['2']}>
    <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>
  </Table>
</Flex>

<Flex flexGrow={1} maxWidth="size-6000">
  <Table
    aria-label="Example table with single selection (uncontrolled)"
    width="100%"
    height="100%"
    selectionMode="single"
    defaultSelectedKeys={['2']}>
    <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>
  </Table>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-6000">
  <Table
    aria-label="Example table with single selection (uncontrolled)"
    width="100%"
    height="100%"
    selectionMode="single"
    defaultSelectedKeys={[
      '2'
    ]}>
    <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>
  </Table>
</Flex>

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 (
    <Flex flexGrow={1} maxWidth="size-6000">
      <Table
        aria-label="Example table with single selection (controlled)"
        width="100%"
        height="100%"
        selectionMode="single"
        selectedKeys={selected}
        onSelectionChange={setSelected}
        {...props}>
        <TableHeader columns={columns}>
          {(column) => (
            <Column
              key={column.uid}
              align={column.uid === 'level' ? 'end' : 'start'}>
              {column.name}
            </Column>
          )}
        </TableHeader>
        <TableBody items={rows}>
          {(item) => (
            <Row key={item.id}>{(key) => <Cell>{item[key]}</Cell>}</Row>
          )}
        </TableBody>
      </Table>
    </Flex>
  );
}

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 (
    <Flex flexGrow={1} maxWidth="size-6000">
      <Table
        aria-label="Example table with single selection (controlled)"
        width="100%"
        height="100%"
        selectionMode="single"
        selectedKeys={selected}
        onSelectionChange={setSelected}
        {...props}>
        <TableHeader columns={columns}>
          {(column) => (
            <Column
              key={column.uid}
              align={
                column.uid === 'level' ? 'end' : 'start'
              }>
              {column.name}
            </Column>
          )}
        </TableHeader>
        <TableBody items={rows}>
          {(item) => (
            <Row key={item.id}>
              {(key) => <Cell>{item[key]}</Cell>}
            </Row>
          )}
        </TableBody>
      </Table>
    </Flex>
  );
}

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 (
    <Flex
      flexGrow={1}
      maxWidth="size-6000">
      <Table
        aria-label="Example table with single selection (controlled)"
        width="100%"
        height="100%"
        selectionMode="single"
        selectedKeys={
          selected
        }
        onSelectionChange={
          setSelected
        }
        {...props}>
        <TableHeader
          columns={
            columns
          }>
          {(column) => (
            <Column
              key={
                column.uid
              }
              align={
                column.uid ===
                'level'
                  ? 'end'
                  : 'start'
              }>
              {
                column.name
              }
            </Column>
          )}
        </TableHeader>
        <TableBody
          items={rows}>
          {(item) => (
            <Row
              key={
                item.id
              }>
              {(key) => (
                <Cell>
                  {
                    item[
                      key
                    ]
                  }
                </Cell>
              )}
            </Row>
          )}
        </TableBody>
      </Table>
    </Flex>
  );
}

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

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.

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, 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
      };
    },
    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 (
    <Flex height="size-2000" flexGrow={1} maxWidth="size-6000">
      <Table
        aria-label="Example table with client side sorting"
        height="100%"
        width="100%"
        sortDescriptor={list.sortDescriptor}
        onSortChange={list.sort}>
        <TableHeader columns={columns}>
          {(column) => (
            <Column
              allowsSorting
              align={column.key !== 'name' ? 'end' : 'start'}>
              {column.name}
            </Column>
          )}
        </TableHeader>
        <TableBody
          items={list.items}
          isLoading={list.isLoading}
          onLoadMore={list.loadMore}>
          {(item) => (
            <Row key={item.name}>{(key) => <Cell>{item[key]}</Cell>}</Row>
          )}
        </TableBody>
      </Table>
    </Flex>
  );
}

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, 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
      };
    },
    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 (
    <Flex
      height="size-2000"
      flexGrow={1}
      maxWidth="size-6000">
      <Table
        aria-label="Example table with client side sorting"
        height="100%"
        width="100%"
        sortDescriptor={list.sortDescriptor}
        onSortChange={list.sort}>
        <TableHeader columns={columns}>
          {(column) => (
            <Column
              allowsSorting
              align={
                column.key !== 'name' ? 'end' : 'start'
              }>
              {column.name}
            </Column>
          )}
        </TableHeader>
        <TableBody
          items={list.items}
          isLoading={list.isLoading}
          onLoadMore={list.loadMore}>
          {(item) => (
            <Row key={item.name}>
              {(key) => <Cell>{item[key]}</Cell>}
            </Row>
          )}
        </TableBody>
      </Table>
    </Flex>
  );
}

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,
        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
        };
      },
      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 (
    <Flex
      height="size-2000"
      flexGrow={1}
      maxWidth="size-6000">
      <Table
        aria-label="Example table with client side sorting"
        height="100%"
        width="100%"
        sortDescriptor={
          list.sortDescriptor
        }
        onSortChange={
          list.sort
        }>
        <TableHeader
          columns={
            columns
          }>
          {(column) => (
            <Column
              allowsSorting
              align={
                column.key !==
                'name'
                  ? 'end'
                  : 'start'
              }>
              {
                column.name
              }
            </Column>
          )}
        </TableHeader>
        <TableBody
          items={
            list.items
          }
          isLoading={
            list.isLoading
          }
          onLoadMore={
            list.loadMore
          }>
          {(item) => (
            <Row
              key={
                item.name
              }>
              {(key) => (
                <Cell>
                  {
                    item[
                      key
                    ]
                  }
                </Cell>
              )}
            </Row>
          )}
        </TableBody>
      </Table>
    </Flex>
  );
}

Props#

Table props#

Table header props#

Column props#

Table body props#

Row props#

Cell props#

Visual options#

Column alignment#

View guidelines

<Flex flexGrow={1} maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>

<Flex flexGrow={1} maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>

Column widths#

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

<Flex flexGrow={1} maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>

<Flex flexGrow={1} maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>

<Flex
  flexGrow={1}
  maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>

Column dividers#

View guidelines

<Flex flexGrow={1} maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>

<Flex flexGrow={1} maxWidth="size-4600">
  <Table
    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>
  </Table>
</Flex>