Table

A table displays data in rows and columns and enables a user to navigate its contents via directional navigation keys, and optionally supports row selection and sorting.

Example#

import {Cell, Column, Row, Table, TableBody, TableHeader} from 'react-aria-components';

<Table aria-label="Files" selectionMode="multiple">
  <TableHeader>
    <Column>
      <MyCheckbox />
    </Column>
    <Column isRowHeader>Name</Column>
    <Column>Type</Column>
    <Column>Date Modified</Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>Games</Cell>
      <Cell>File folder</Cell>
      <Cell>6/7/2020</Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>Program Files</Cell>
      <Cell>File folder</Cell>
      <Cell>4/7/2021</Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>bootmgr</Cell>
      <Cell>System file</Cell>
      <Cell>11/20/2010</Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>log.txt</Cell>
      <Cell>Text Document</Cell>
      <Cell>1/18/2016</Cell>
    </Row>
  </TableBody>
</Table>

import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader
} from 'react-aria-components';

<Table aria-label="Files" selectionMode="multiple">
  <TableHeader>
    <Column>
      <MyCheckbox />
    </Column>
    <Column isRowHeader>Name</Column>
    <Column>Type</Column>
    <Column>Date Modified</Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>Games</Cell>
      <Cell>File folder</Cell>
      <Cell>6/7/2020</Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>Program Files</Cell>
      <Cell>File folder</Cell>
      <Cell>4/7/2021</Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>bootmgr</Cell>
      <Cell>System file</Cell>
      <Cell>11/20/2010</Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>log.txt</Cell>
      <Cell>Text Document</Cell>
      <Cell>1/18/2016</Cell>
    </Row>
  </TableBody>
</Table>

import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader
} from 'react-aria-components';

<Table
  aria-label="Files"
  selectionMode="multiple"
>
  <TableHeader>
    <Column>
      <MyCheckbox />
    </Column>
    <Column
      isRowHeader
    >
      Name
    </Column>
    <Column>
      Type
    </Column>
    <Column>
      Date Modified
    </Column>
  </TableHeader>
  <TableBody>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>
        Games
      </Cell>
      <Cell>
        File folder
      </Cell>
      <Cell>
        6/7/2020
      </Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>
        Program Files
      </Cell>
      <Cell>
        File folder
      </Cell>
      <Cell>
        4/7/2021
      </Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>
        bootmgr
      </Cell>
      <Cell>
        System file
      </Cell>
      <Cell>
        11/20/2010
      </Cell>
    </Row>
    <Row>
      <Cell>
        <MyCheckbox />
      </Cell>
      <Cell>
        log.txt
      </Cell>
      <Cell>
        Text Document
      </Cell>
      <Cell>
        1/18/2016
      </Cell>
    </Row>
  </TableBody>
</Table>

.react-aria-Table {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  padding: 0.286rem;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  border-spacing: 0;
  min-height: 100px;
  align-self: start;
  max-width: 100%;
  word-break: break-word;

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-TableHeader {
    &:after {
      content: '';
      display: table-row;
      height: 2px;
    }

    & tr:last-child .react-aria-Column {
      border-bottom: 1px solid var(--border-color);
      cursor: default;
    }
  }

  .react-aria-Column {
    &[colspan] {
      text-align: center;
    }

    .sort-indicator {
      padding: 0 2px;
    }

    &:not([data-sort-direction]) .sort-indicator {
      visibility: hidden;
    }
  }

  .react-aria-TableBody {
    &[data-empty] {
      text-align: center;
      font-style: italic;
    }
  }

  .react-aria-Row {
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: scale(1);

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }

    &[data-pressed] .react-aria-Cell {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-selected] {
      .react-aria-Cell {
        background: var(--highlight-background);
        color: var(--highlight-foreground);
      }

      &[data-focus-visible],
      .react-aria-Cell[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -4px;
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --focus-ring-color: var(--highlight-foreground);
        --hover-highlight: rgb(255 255 255 / 0.1);
        --active-highlight: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }
  }

  .react-aria-Cell,
  .react-aria-Column {
    padding: 4px 8px;
    text-align: left;
    outline: none;

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }
  }

  .react-aria-Cell {
    transform: translateZ(0);

    &:first-child {
      border-radius: 6px 0 0 6px;
    }

    &:last-child {
      border-radius: 0 6px 6px 0;
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    .react-aria-Row[data-selected]:has(+ [data-selected]) .react-aria-Cell,
    .react-aria-Row[data-selected]:has(+ .react-aria-DropIndicator + [data-selected]) .react-aria-Cell {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-Row[data-selected] + [data-selected] .react-aria-Cell,
    .react-aria-Row[data-selected] + .react-aria-DropIndicator + [data-selected] .react-aria-Cell {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }
}

.react-aria-Checkbox {
  --deselected-color: gray;
  --deselected-color-pressed: dimgray;
  --selected-color: slateblue;
  --selected-color-pressed: lch(from slateblue calc(l - 10%) c h);
  --checkmark-color: white;
  --focus-ring-color: slateblue;

  width: 1rem;
  height: 1rem;
  border: 2px solid var(--deselected-color);
  border-radius: 4px;
  transition: all 200ms;
  display: flex;
  align-items: center;
  justify-content: center;

  & svg {
    width: 0.857rem;
    height: 0.857rem;
    fill: none;
    stroke: var(--checkmark-color);
    stroke-width: 3px;
    stroke-dasharray: 22px;
    stroke-dashoffset: 66;
    transition: all 200ms;
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--spectrum-alias-background-color-default), 0 0 0 4px var(--focus-ring-color);
  }

  &[data-pressed] {
    border-color: var(--deselected-color-pressed);
  }

  &[data-selected],
  &[data-indeterminate] {
    border-color: var(--selected-color);
    background: var(--selected-color);

    &[data-pressed] {
      border-color: var(--selected-color-pressed);
      background: var(--selected-color-pressed);
    }

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px var(--background-color), 0 0 0 4px var(--selected-color);
    }

    & svg {
      stroke-dashoffset: 44;
    }
  }

  &[data-indeterminate] {
    & svg {
      stroke: none;
      fill: var(--checkmark-color);
    }
  }

  &[data-disabled] {
    opacity: 0.4;
  }
}

:where(.react-aria-Row) .react-aria-Checkbox {
  --selected-color: white;
  --selected-color-pressed: #ddd;
  --checkmark-color: slateblue;
  --background-color: var(--highlight-background);
}

.react-aria-Button {
  background: transparent;
  border: none;
  border-radius: 4px;
  appearance: none;
  vertical-align: middle;
  font-size: 1.2rem;
  text-align: center;
  line-height: 1.2em;
  margin: 0;
  outline: none;
  padding: 4px 6px;
  transition: background 200ms;
  --focus-ring-color: slateblue;
  --hover-highlight: var(--spectrum-alias-highlight-hover);
  --active-highlight: var(--spectrum-alias-highlight-active);

  &[data-hovered] {
    background: var(--hover-highlight);
  }

  &[data-pressed] {
    background: var(--active-highlight);
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--focus-ring-color);
  }
}

@media (forced-colors: active) {
  .react-aria-Table {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }

  .react-aria-Checkbox {
    forced-color-adjust: none;

    --deselected-color: ButtonBorder;
    --deselected-color-pressed: ButtonBorder;
    --selected-color: Highlight;
    --selected-color-pressed: Highlight;
    --checkmark-color: HighlightText;
    --spectrum-alias-background-color-default: Canvas;
    --focus-ring-color: Highlight;

    &[data-disabled] {
      opacity: 1;
      --deselected-color: GrayText;
      --selected-color: GrayText;
    }
  }

  .react-aria-Row .react-aria-Checkbox {
    --selected-color: ButtonFace;
    --selected-color-pressed: ButtonFace;
    --checkmark-color: ButtonText;
  }

  .react-aria-Button {
    forced-color-adjust: none;
    --focus-ring-color: Highlight;
  }
}

.react-aria-Table {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  padding: 0.286rem;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  border-spacing: 0;
  min-height: 100px;
  align-self: start;
  max-width: 100%;
  word-break: break-word;

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-TableHeader {
    &:after {
      content: '';
      display: table-row;
      height: 2px;
    }

    & tr:last-child .react-aria-Column {
      border-bottom: 1px solid var(--border-color);
      cursor: default;
    }
  }

  .react-aria-Column {
    &[colspan] {
      text-align: center;
    }

    .sort-indicator {
      padding: 0 2px;
    }

    &:not([data-sort-direction]) .sort-indicator {
      visibility: hidden;
    }
  }

  .react-aria-TableBody {
    &[data-empty] {
      text-align: center;
      font-style: italic;
    }
  }

  .react-aria-Row {
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: scale(1);

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }

    &[data-pressed] .react-aria-Cell {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-selected] {
      .react-aria-Cell {
        background: var(--highlight-background);
        color: var(--highlight-foreground);
      }

      &[data-focus-visible],
      .react-aria-Cell[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -4px;
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --focus-ring-color: var(--highlight-foreground);
        --hover-highlight: rgb(255 255 255 / 0.1);
        --active-highlight: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }
  }

  .react-aria-Cell,
  .react-aria-Column {
    padding: 4px 8px;
    text-align: left;
    outline: none;

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }
  }

  .react-aria-Cell {
    transform: translateZ(0);

    &:first-child {
      border-radius: 6px 0 0 6px;
    }

    &:last-child {
      border-radius: 0 6px 6px 0;
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    .react-aria-Row[data-selected]:has(+ [data-selected]) .react-aria-Cell,
    .react-aria-Row[data-selected]:has(+ .react-aria-DropIndicator + [data-selected]) .react-aria-Cell {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-Row[data-selected] + [data-selected] .react-aria-Cell,
    .react-aria-Row[data-selected] + .react-aria-DropIndicator + [data-selected] .react-aria-Cell {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }
}

.react-aria-Checkbox {
  --deselected-color: gray;
  --deselected-color-pressed: dimgray;
  --selected-color: slateblue;
  --selected-color-pressed: lch(from slateblue calc(l - 10%) c h);
  --checkmark-color: white;
  --focus-ring-color: slateblue;

  width: 1rem;
  height: 1rem;
  border: 2px solid var(--deselected-color);
  border-radius: 4px;
  transition: all 200ms;
  display: flex;
  align-items: center;
  justify-content: center;

  & svg {
    width: 0.857rem;
    height: 0.857rem;
    fill: none;
    stroke: var(--checkmark-color);
    stroke-width: 3px;
    stroke-dasharray: 22px;
    stroke-dashoffset: 66;
    transition: all 200ms;
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--spectrum-alias-background-color-default), 0 0 0 4px var(--focus-ring-color);
  }

  &[data-pressed] {
    border-color: var(--deselected-color-pressed);
  }

  &[data-selected],
  &[data-indeterminate] {
    border-color: var(--selected-color);
    background: var(--selected-color);

    &[data-pressed] {
      border-color: var(--selected-color-pressed);
      background: var(--selected-color-pressed);
    }

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px var(--background-color), 0 0 0 4px var(--selected-color);
    }

    & svg {
      stroke-dashoffset: 44;
    }
  }

  &[data-indeterminate] {
    & svg {
      stroke: none;
      fill: var(--checkmark-color);
    }
  }

  &[data-disabled] {
    opacity: 0.4;
  }
}

:where(.react-aria-Row) .react-aria-Checkbox {
  --selected-color: white;
  --selected-color-pressed: #ddd;
  --checkmark-color: slateblue;
  --background-color: var(--highlight-background);
}

.react-aria-Button {
  background: transparent;
  border: none;
  border-radius: 4px;
  appearance: none;
  vertical-align: middle;
  font-size: 1.2rem;
  text-align: center;
  line-height: 1.2em;
  margin: 0;
  outline: none;
  padding: 4px 6px;
  transition: background 200ms;
  --focus-ring-color: slateblue;
  --hover-highlight: var(--spectrum-alias-highlight-hover);
  --active-highlight: var(--spectrum-alias-highlight-active);

  &[data-hovered] {
    background: var(--hover-highlight);
  }

  &[data-pressed] {
    background: var(--active-highlight);
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--focus-ring-color);
  }
}

@media (forced-colors: active) {
  .react-aria-Table {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }

  .react-aria-Checkbox {
    forced-color-adjust: none;

    --deselected-color: ButtonBorder;
    --deselected-color-pressed: ButtonBorder;
    --selected-color: Highlight;
    --selected-color-pressed: Highlight;
    --checkmark-color: HighlightText;
    --spectrum-alias-background-color-default: Canvas;
    --focus-ring-color: Highlight;

    &[data-disabled] {
      opacity: 1;
      --deselected-color: GrayText;
      --selected-color: GrayText;
    }
  }

  .react-aria-Row .react-aria-Checkbox {
    --selected-color: ButtonFace;
    --selected-color-pressed: ButtonFace;
    --checkmark-color: ButtonText;
  }

  .react-aria-Button {
    forced-color-adjust: none;
    --focus-ring-color: Highlight;
  }
}

.react-aria-Table {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  padding: 0.286rem;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  border-spacing: 0;
  min-height: 100px;
  align-self: start;
  max-width: 100%;
  word-break: break-word;

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-TableHeader {
    &:after {
      content: '';
      display: table-row;
      height: 2px;
    }

    & tr:last-child .react-aria-Column {
      border-bottom: 1px solid var(--border-color);
      cursor: default;
    }
  }

  .react-aria-Column {
    &[colspan] {
      text-align: center;
    }

    .sort-indicator {
      padding: 0 2px;
    }

    &:not([data-sort-direction]) .sort-indicator {
      visibility: hidden;
    }
  }

  .react-aria-TableBody {
    &[data-empty] {
      text-align: center;
      font-style: italic;
    }
  }

  .react-aria-Row {
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: scale(1);

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }

    &[data-pressed] .react-aria-Cell {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-selected] {
      .react-aria-Cell {
        background: var(--highlight-background);
        color: var(--highlight-foreground);
      }

      &[data-focus-visible],
      .react-aria-Cell[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -4px;
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --focus-ring-color: var(--highlight-foreground);
        --hover-highlight: rgb(255 255 255 / 0.1);
        --active-highlight: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }
  }

  .react-aria-Cell,
  .react-aria-Column {
    padding: 4px 8px;
    text-align: left;
    outline: none;

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }
  }

  .react-aria-Cell {
    transform: translateZ(0);

    &:first-child {
      border-radius: 6px 0 0 6px;
    }

    &:last-child {
      border-radius: 0 6px 6px 0;
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    .react-aria-Row[data-selected]:has(+ [data-selected]) .react-aria-Cell,
    .react-aria-Row[data-selected]:has(+ .react-aria-DropIndicator + [data-selected]) .react-aria-Cell {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-Row[data-selected] + [data-selected] .react-aria-Cell,
    .react-aria-Row[data-selected] + .react-aria-DropIndicator + [data-selected] .react-aria-Cell {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }
}

.react-aria-Checkbox {
  --deselected-color: gray;
  --deselected-color-pressed: dimgray;
  --selected-color: slateblue;
  --selected-color-pressed: lch(from slateblue calc(l - 10%) c h);
  --checkmark-color: white;
  --focus-ring-color: slateblue;

  width: 1rem;
  height: 1rem;
  border: 2px solid var(--deselected-color);
  border-radius: 4px;
  transition: all 200ms;
  display: flex;
  align-items: center;
  justify-content: center;

  & svg {
    width: 0.857rem;
    height: 0.857rem;
    fill: none;
    stroke: var(--checkmark-color);
    stroke-width: 3px;
    stroke-dasharray: 22px;
    stroke-dashoffset: 66;
    transition: all 200ms;
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--spectrum-alias-background-color-default), 0 0 0 4px var(--focus-ring-color);
  }

  &[data-pressed] {
    border-color: var(--deselected-color-pressed);
  }

  &[data-selected],
  &[data-indeterminate] {
    border-color: var(--selected-color);
    background: var(--selected-color);

    &[data-pressed] {
      border-color: var(--selected-color-pressed);
      background: var(--selected-color-pressed);
    }

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px var(--background-color), 0 0 0 4px var(--selected-color);
    }

    & svg {
      stroke-dashoffset: 44;
    }
  }

  &[data-indeterminate] {
    & svg {
      stroke: none;
      fill: var(--checkmark-color);
    }
  }

  &[data-disabled] {
    opacity: 0.4;
  }
}

:where(.react-aria-Row) .react-aria-Checkbox {
  --selected-color: white;
  --selected-color-pressed: #ddd;
  --checkmark-color: slateblue;
  --background-color: var(--highlight-background);
}

.react-aria-Button {
  background: transparent;
  border: none;
  border-radius: 4px;
  appearance: none;
  vertical-align: middle;
  font-size: 1.2rem;
  text-align: center;
  line-height: 1.2em;
  margin: 0;
  outline: none;
  padding: 4px 6px;
  transition: background 200ms;
  --focus-ring-color: slateblue;
  --hover-highlight: var(--spectrum-alias-highlight-hover);
  --active-highlight: var(--spectrum-alias-highlight-active);

  &[data-hovered] {
    background: var(--hover-highlight);
  }

  &[data-pressed] {
    background: var(--active-highlight);
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--focus-ring-color);
  }
}

@media (forced-colors: active) {
  .react-aria-Table {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }

  .react-aria-Checkbox {
    forced-color-adjust: none;

    --deselected-color: ButtonBorder;
    --deselected-color-pressed: ButtonBorder;
    --selected-color: Highlight;
    --selected-color-pressed: Highlight;
    --checkmark-color: HighlightText;
    --spectrum-alias-background-color-default: Canvas;
    --focus-ring-color: Highlight;

    &[data-disabled] {
      opacity: 1;
      --deselected-color: GrayText;
      --selected-color: GrayText;
    }
  }

  .react-aria-Row .react-aria-Checkbox {
    --selected-color: ButtonFace;
    --selected-color-pressed: ButtonFace;
    --checkmark-color: ButtonText;
  }

  .react-aria-Button {
    forced-color-adjust: none;
    --focus-ring-color: Highlight;
  }
}

Features#

A table can be built using the <table>, <tr>, <td>, and other table specific HTML elements, but is very limited in functionality especially when it comes to user interactions. HTML tables are meant for static content, rather than tables with rich interactions like focusable elements within cells, keyboard navigation, row selection, sorting, etc. Table helps achieve accessible and interactive table components that can be styled as needed.

• Row selection – Single or multiple selection, with optional checkboxes, disabled rows, and both toggle and replace selection behaviors.
• Columns – Support for column sorting, row header columns, and nested column groups. Columns may optionally allow user resizing via mouse, touch, and keyboard interactions.
• Interactive children – Table cells may include interactive elements such as buttons, menus, etc.
• Actions – Rows and cells support optional actions such as navigation via click, tap, double click, or Enter key.
• Async loading – Support for loading and sorting items asynchronously.
• Keyboard navigation – Table rows, cells, and focusable children can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and selection modifier keys are supported as well.
• Drag and drop – Tables support drag and drop to reorder, insert, or update rows via mouse, touch, keyboard, and screen reader interactions.
• Touch friendly – Selection and actions adapt their behavior depending on the device. For example, selection is activated via long press on touch when row actions are present.
• Accessible – Follows the ARIA grid pattern, with additional selection announcements via an ARIA live region. Extensively tested across many devices and assistive technologies to ensure announcements and behaviors are consistent.

Anatomy#

A table consists of a container element, with columns and rows of cells containing data inside. The cells within a table may contain focusable elements or plain text content. Columns may be nested to create column groups.

If the table supports row selection, each row can optionally include a selection checkbox. Additionally, a "select all" checkbox may be displayed in a column header if the table supports multiple row selection. A drag button may also be included within a cell if the row is draggable.

If a table supports column resizing, then it should also be wrapped in a <ResizableTableContainer>, and a <ColumnResizer> should be included in each resizable column.

import {Button, Cell, Checkbox, Column, ColumnResizer, ResizableTableContainer, Row, Table, TableBody, TableHeader} from 'react-aria-components';

<ResizableTableContainer>
  <Table>
    <TableHeader>
      <Column />
      <Column>
        <Checkbox slot="selection" />
      </Column>
      <Column>
        <ColumnResizer />
      </Column>
      <Column>
        <Column />
        <Column />
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>
          <Button slot="drag" />
        </Cell>
        <Cell>
          <Checkbox slot="selection" />
        </Cell>
        <Cell />
        <Cell />
        <Cell />
      </Row>
    </TableBody>
  </Table>
</ResizableTableContainer>

import {
  Button,
  Cell,
  Checkbox,
  Column,
  ColumnResizer,
  ResizableTableContainer,
  Row,
  Table,
  TableBody,
  TableHeader
} from 'react-aria-components';

<ResizableTableContainer>
  <Table>
    <TableHeader>
      <Column />
      <Column>
        <Checkbox slot="selection" />
      </Column>
      <Column>
        <ColumnResizer />
      </Column>
      <Column>
        <Column />
        <Column />
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>
          <Button slot="drag" />
        </Cell>
        <Cell>
          <Checkbox slot="selection" />
        </Cell>
        <Cell />
        <Cell />
        <Cell />
      </Row>
    </TableBody>
  </Table>
</ResizableTableContainer>

import {
  Button,
  Cell,
  Checkbox,
  Column,
  ColumnResizer,
  ResizableTableContainer,
  Row,
  Table,
  TableBody,
  TableHeader
} from 'react-aria-components';

<ResizableTableContainer>
  <Table>
    <TableHeader>
      <Column />
      <Column>
        <Checkbox slot="selection" />
      </Column>
      <Column>
        <ColumnResizer />
      </Column>
      <Column>
        <Column />
        <Column />
      </Column>
    </TableHeader>
    <TableBody>
      <Row>
        <Cell>
          <Button slot="drag" />
        </Cell>
        <Cell>
          <Checkbox slot="selection" />
        </Cell>
        <Cell />
        <Cell />
        <Cell />
      </Row>
    </TableBody>
  </Table>
</ResizableTableContainer>

Concepts#

Table makes use of the following concepts:

Composed components#

A Table uses the following components, which may also be used standalone or reused in other components.

Examples#

Stock Table

A table with sticky headers, sorting, multiple selection, and column resizing.

Reusable wrappers#

If you will use a Table in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

The following example includes a custom Column component with a sort indicator. It displays an upwards facing arrow when the column is sorted in the ascending direction, and a downward facing arrow otherwise.

import type {ColumnProps} from 'react-aria-components';

function MyColumn<T extends object>(props: ColumnProps<T>) {
  return (
    <Column {...props}>
      {({allowsSorting, sortDirection}) => <>
        {props.children}
        {allowsSorting && (
          <span aria-hidden="true" className="sort-indicator">
            {sortDirection === 'ascending' ? '▲' : '▼'}
          </span>
        )}
      </>}
    </Column>
  );
}

import type {ColumnProps} from 'react-aria-components';

function MyColumn<T extends object>(props: ColumnProps<T>) {
  return (
    <Column {...props}>
      {({ allowsSorting, sortDirection }) => (
        <>
          {props.children}
          {allowsSorting && (
            <span
              aria-hidden="true"
              className="sort-indicator"
            >
              {sortDirection === 'ascending' ? '▲' : '▼'}
            </span>
          )}
        </>
      )}
    </Column>
  );
}

import type {ColumnProps} from 'react-aria-components';

function MyColumn<
  T extends object
>(
  props: ColumnProps<T>
) {
  return (
    <Column {...props}>
      {(
        {
          allowsSorting,
          sortDirection
        }
      ) => (
        <>
          {props
            .children}
          {allowsSorting &&
            (
              <span
                aria-hidden="true"
                className="sort-indicator"
              >
                {sortDirection ===
                    'ascending'
                  ? '▲'
                  : '▼'}
              </span>
            )}
        </>
      )}
    </Column>
  );
}

The TableHeader and Row components can also be wrapped to automatically include checkboxes for selection, and a drag handle when drag and drop is enabled, allowing consumers to avoid repeating them in each row. In this example, the select all checkbox is displayed when multiple selection is enabled and the selection behavior is "toggle". These options can be retrieved from the table using the useTableOptions hook. We also use the Collection component to generate children from either static or dynamic collections the same way as the default TableHeader and Row components.

import type {RowProps, TableHeaderProps} from 'react-aria-components';
import {Checkbox, Collection, useTableOptions} from 'react-aria-components';

function MyTableHeader<T extends object>(
  { columns, children }: TableHeaderProps<T>
) {
  let { selectionBehavior, selectionMode, allowsDragging } = useTableOptions();

  return (
    <TableHeader>
      {/* Add extra columns for drag and drop and selection. */}
      {allowsDragging && <Column />}
      {selectionBehavior === 'toggle' && (
        <Column>{selectionMode === 'multiple' && <MyCheckbox />}</Column>
      )}
      <Collection items={columns}>
        {children}
      </Collection>
    </TableHeader>
  );
}

function MyRow<T extends object>(
  { id, columns, children, ...otherProps }: RowProps<T>
) {
  let { selectionBehavior, allowsDragging } = useTableOptions();

  return (
    <Row id={id} {...otherProps}>
      {allowsDragging && (
        <Cell>
          <Button slot="drag">≡</Button>
        </Cell>
      )}
      {selectionBehavior === 'toggle' && (
        <Cell>
          <MyCheckbox />
        </Cell>
      )}
      <Collection items={columns}>
        {children}
      </Collection>
    </Row>
  );
}

function MyCheckbox() {
  return (
    <Checkbox slot="selection">
      {({ isIndeterminate }) => (
        <svg viewBox="0 0 18 18" aria-hidden="true">
          {isIndeterminate
            ? <rect x={1} y={7.5} width={15} height={3} />
            : <polyline points="1 9 7 14 15 4" />}
        </svg>
      )}
    </Checkbox>
  );
}

import type {
  RowProps,
  TableHeaderProps
} from 'react-aria-components';
import {
  Checkbox,
  Collection,
  useTableOptions
} from 'react-aria-components';

function MyTableHeader<T extends object>(
  { columns, children }: TableHeaderProps<T>
) {
  let { selectionBehavior, selectionMode, allowsDragging } =
    useTableOptions();

  return (
    <TableHeader>
      {/* Add extra columns for drag and drop and selection. */}
      {allowsDragging && <Column />}
      {selectionBehavior === 'toggle' && (
        <Column>
          {selectionMode === 'multiple' && <MyCheckbox />}
        </Column>
      )}
      <Collection items={columns}>
        {children}
      </Collection>
    </TableHeader>
  );
}

function MyRow<T extends object>(
  { id, columns, children, ...otherProps }: RowProps<T>
) {
  let { selectionBehavior, allowsDragging } =
    useTableOptions();

  return (
    <Row id={id} {...otherProps}>
      {allowsDragging && (
        <Cell>
          <Button slot="drag">≡</Button>
        </Cell>
      )}
      {selectionBehavior === 'toggle' && (
        <Cell>
          <MyCheckbox />
        </Cell>
      )}
      <Collection items={columns}>
        {children}
      </Collection>
    </Row>
  );
}

function MyCheckbox() {
  return (
    <Checkbox slot="selection">
      {({ isIndeterminate }) => (
        <svg viewBox="0 0 18 18" aria-hidden="true">
          {isIndeterminate
            ? <rect x={1} y={7.5} width={15} height={3} />
            : <polyline points="1 9 7 14 15 4" />}
        </svg>
      )}
    </Checkbox>
  );
}

import type {
  RowProps,
  TableHeaderProps
} from 'react-aria-components';
import {
  Checkbox,
  Collection,
  useTableOptions
} from 'react-aria-components';

function MyTableHeader<
  T extends object
>(
  { columns, children }:
    TableHeaderProps<T>
) {
  let {
    selectionBehavior,
    selectionMode,
    allowsDragging
  } = useTableOptions();

  return (
    <TableHeader>
      {/* Add extra columns for drag and drop and selection. */}
      {allowsDragging &&
        <Column />}
      {selectionBehavior ===
          'toggle' && (
        <Column>
          {selectionMode ===
              'multiple' &&
            (
              <MyCheckbox />
            )}
        </Column>
      )}
      <Collection
        items={columns}
      >
        {children}
      </Collection>
    </TableHeader>
  );
}

function MyRow<
  T extends object
>(
  {
    id,
    columns,
    children,
    ...otherProps
  }: RowProps<T>
) {
  let {
    selectionBehavior,
    allowsDragging
  } = useTableOptions();

  return (
    <Row
      id={id}
      {...otherProps}
    >
      {allowsDragging &&
        (
          <Cell>
            <Button slot="drag">
              ≡
            </Button>
          </Cell>
        )}
      {selectionBehavior ===
          'toggle' && (
        <Cell>
          <MyCheckbox />
        </Cell>
      )}
      <Collection
        items={columns}
      >
        {children}
      </Collection>
    </Row>
  );
}

function MyCheckbox() {
  return (
    <Checkbox slot="selection">
      {(
        {
          isIndeterminate
        }
      ) => (
        <svg
          viewBox="0 0 18 18"
          aria-hidden="true"
        >
          {isIndeterminate
            ? (
              <rect
                x={1}
                y={7.5}
                width={15}
                height={3}
              />
            )
            : (
              <polyline points="1 9 7 14 15 4" />
            )}
        </svg>
      )}
    </Checkbox>
  );
}

Now we can render a table with a default selection column built in.

<Table aria-label="Files" selectionMode="multiple">
  <MyTableHeader>
    <MyColumn isRowHeader>Name</MyColumn>
    <MyColumn>Type</MyColumn>
    <MyColumn>Date Modified</MyColumn>
  </MyTableHeader>
  <TableBody>
    <MyRow>
      <Cell>Games</Cell>
      <Cell>File folder</Cell>
      <Cell>6/7/2020</Cell>
    </MyRow>
    <MyRow>
      <Cell>Program Files</Cell>
      <Cell>File folder</Cell>
      <Cell>4/7/2021</Cell>
    </MyRow>
    <MyRow>
      <Cell>bootmgr</Cell>
      <Cell>System file</Cell>
      <Cell>11/20/2010</Cell>
    </MyRow>
  </TableBody>
</Table>

<Table aria-label="Files" selectionMode="multiple">
  <MyTableHeader>
    <MyColumn isRowHeader>Name</MyColumn>
    <MyColumn>Type</MyColumn>
    <MyColumn>Date Modified</MyColumn>
  </MyTableHeader>
  <TableBody>
    <MyRow>
      <Cell>Games</Cell>
      <Cell>File folder</Cell>
      <Cell>6/7/2020</Cell>
    </MyRow>
    <MyRow>
      <Cell>Program Files</Cell>
      <Cell>File folder</Cell>
      <Cell>4/7/2021</Cell>
    </MyRow>
    <MyRow>
      <Cell>bootmgr</Cell>
      <Cell>System file</Cell>
      <Cell>11/20/2010</Cell>
    </MyRow>
  </TableBody>
</Table>

<Table
  aria-label="Files"
  selectionMode="multiple"
>
  <MyTableHeader>
    <MyColumn
      isRowHeader
    >
      Name
    </MyColumn>
    <MyColumn>
      Type
    </MyColumn>
    <MyColumn>
      Date Modified
    </MyColumn>
  </MyTableHeader>
  <TableBody>
    <MyRow>
      <Cell>
        Games
      </Cell>
      <Cell>
        File folder
      </Cell>
      <Cell>
        6/7/2020
      </Cell>
    </MyRow>
    <MyRow>
      <Cell>
        Program Files
      </Cell>
      <Cell>
        File folder
      </Cell>
      <Cell>
        4/7/2021
      </Cell>
    </MyRow>
    <MyRow>
      <Cell>
        bootmgr
      </Cell>
      <Cell>
        System file
      </Cell>
      <Cell>
        11/20/2010
      </Cell>
    </MyRow>
  </TableBody>
</Table>

Content#

So far, our examples have shown static collections, where the data is hard coded. Dynamic collections, as shown below, can be used when the table data comes from an external data source such as an API, or updates over time. In the example below, both the columns and the rows are provided to the table via a render function. You can also make the columns static and only the rows dynamic.

import type {TableProps} from 'react-aria-components';

function FileTable(props: TableProps) {
  let columns = [
    {name: 'Name', key: 'name', isRowHeader: true},
    {name: 'Type', key: 'type'},
    {name: 'Date Modified', key: 'date'}
  ];

  let rows = [
    {id: 1, name: 'Games', date: '6/7/2020', type: 'File folder'},
    {id: 2, name: 'Program Files', date: '4/7/2021', type: 'File folder'},
    {id: 3, name: 'bootmgr', date: '11/20/2010', type: 'System file'},
    {id: 4, name: 'log.txt', date: '1/18/2016', type: 'Text Document'}
  ];

  return (
    <Table aria-label="Files" {...props}>
      <MyTableHeader columns={columns}>
        {column => (
          <Column isRowHeader={column.isRowHeader}>
            {column.name}
          </Column>
        )}
      </MyTableHeader>
      <TableBody items={rows}>
        {item => (
          <MyRow columns={columns}>
            {column => <Cell>{item[column.key]}</Cell>}
          </MyRow>
        )}
      </TableBody>
    </Table>
  );
}

import type {TableProps} from 'react-aria-components';

function FileTable(props: TableProps) {
  let columns = [
    { name: 'Name', key: 'name', isRowHeader: true },
    { name: 'Type', key: 'type' },
    { name: 'Date Modified', key: 'date' }
  ];

  let rows = [
    {
      id: 1,
      name: 'Games',
      date: '6/7/2020',
      type: 'File folder'
    },
    {
      id: 2,
      name: 'Program Files',
      date: '4/7/2021',
      type: 'File folder'
    },
    {
      id: 3,
      name: 'bootmgr',
      date: '11/20/2010',
      type: 'System file'
    },
    {
      id: 4,
      name: 'log.txt',
      date: '1/18/2016',
      type: 'Text Document'
    }
  ];

  return (
    <Table aria-label="Files" {...props}>
      <MyTableHeader columns={columns}>
        {(column) => (
          <Column isRowHeader={column.isRowHeader}>
            {column.name}
          </Column>
        )}
      </MyTableHeader>
      <TableBody items={rows}>
        {(item) => (
          <MyRow columns={columns}>
            {(column) => <Cell>{item[column.key]}</Cell>}
          </MyRow>
        )}
      </TableBody>
    </Table>
  );
}

import type {TableProps} from 'react-aria-components';

function FileTable(
  props: TableProps
) {
  let columns = [
    {
      name: 'Name',
      key: 'name',
      isRowHeader: true
    },
    {
      name: 'Type',
      key: 'type'
    },
    {
      name:
        'Date Modified',
      key: 'date'
    }
  ];

  let rows = [
    {
      id: 1,
      name: 'Games',
      date: '6/7/2020',
      type: 'File folder'
    },
    {
      id: 2,
      name:
        'Program Files',
      date: '4/7/2021',
      type: 'File folder'
    },
    {
      id: 3,
      name: 'bootmgr',
      date: '11/20/2010',
      type: 'System file'
    },
    {
      id: 4,
      name: 'log.txt',
      date: '1/18/2016',
      type:
        'Text Document'
    }
  ];

  return (
    <Table
      aria-label="Files"
      {...props}
    >
      <MyTableHeader
        columns={columns}
      >
        {(column) => (
          <Column
            isRowHeader={column
              .isRowHeader}
          >
            {column.name}
          </Column>
        )}
      </MyTableHeader>
      <TableBody
        items={rows}
      >
        {(item) => (
          <MyRow
            columns={columns}
          >
            {(column) => (
              <Cell>
                {item[
                  column
                    .key
                ]}
              </Cell>
            )}
          </MyRow>
        )}
      </TableBody>
    </Table>
  );
}

Selection#

Single selection#

By default, Table 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 single selection mode, and uses defaultSelectedKeys to select the row with id equal to 2. A user can click on a different row to change the selection, or click on the same row again to deselect it entirely.

// Using the example above
<FileTable selectionMode="single" defaultSelectedKeys={[2]} />

// Using the example above
<FileTable
  selectionMode="single"
  defaultSelectedKeys={[2]}
/>

// Using the example above
<FileTable
  selectionMode="single"
  defaultSelectedKeys={[
    2
  ]}
/>

Multiple selection#

Multiple selection can be enabled by setting selectionMode to multiple.

// Using the example above
<FileTable selectionMode="multiple" defaultSelectedKeys={[2, 4]} />

// Using the example above
<FileTable
  selectionMode="multiple"
  defaultSelectedKeys={[2, 4]}
/>

// Using the example above
<FileTable
  selectionMode="multiple"
  defaultSelectedKeys={[
    2,
    4
  ]}
/>

Disallow empty selection#

Table also supports a disallowEmptySelection prop which forces the user to have at least one row in the Table 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 example above
<FileTable
  selectionMode="single"
  defaultSelectedKeys={[2]}
  disallowEmptySelection
/>

// Using the example above
<FileTable
  selectionMode="single"
  defaultSelectedKeys={[2]}
  disallowEmptySelection
/>

// Using the example above
<FileTable
  selectionMode="single"
  defaultSelectedKeys={[
    2
  ]}
  disallowEmptySelection
/>

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.

import type {Selection} from 'react-aria-components';

interface Pokemon {
  id: number,
  name: string,
  type: string,
  level: string
}

interface PokemonTableProps extends TableProps {
  items?: Pokemon[],
  renderEmptyState?: () => string
}

function PokemonTable(props: PokemonTableProps) {
  let items = props.items || [
    {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());
  return (
    <Table
      aria-label="Pokemon table"
      {...props}
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}    >
      <MyTableHeader>
        <Column isRowHeader>Name</Column>
        <Column>Type</Column>
        <Column>Level</Column>
      </MyTableHeader>
      <TableBody items={items} renderEmptyState={props.renderEmptyState}>
        {item => (
          <MyRow>
            <Cell>{item.name}</Cell>
            <Cell>{item.type}</Cell>
            <Cell>{item.level}</Cell>
          </MyRow>
        )}
      </TableBody>
    </Table>
  );
}

<PokemonTable selectionMode="multiple" />

import type {Selection} from 'react-aria-components';

interface Pokemon {
  id: number;
  name: string;
  type: string;
  level: string;
}

interface PokemonTableProps extends TableProps {
  items?: Pokemon[];
  renderEmptyState?: () => string;
}

function PokemonTable(props: PokemonTableProps) {
  let items = props.items || [
    {
      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());
  return (
    <Table
      aria-label="Pokemon table"
      {...props}
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}    >
      <MyTableHeader>
        <Column isRowHeader>Name</Column>
        <Column>Type</Column>
        <Column>Level</Column>
      </MyTableHeader>
      <TableBody
        items={items}
        renderEmptyState={props.renderEmptyState}
      >
        {(item) => (
          <MyRow>
            <Cell>{item.name}</Cell>
            <Cell>{item.type}</Cell>
            <Cell>{item.level}</Cell>
          </MyRow>
        )}
      </TableBody>
    </Table>
  );
}

<PokemonTable selectionMode="multiple" />

import type {Selection} from 'react-aria-components';

interface Pokemon {
  id: number;
  name: string;
  type: string;
  level: string;
}

interface PokemonTableProps
  extends TableProps {
  items?: Pokemon[];
  renderEmptyState?:
    () => string;
}

function PokemonTable(
  props:
    PokemonTableProps
) {
  let items =
    props.items || [
      {
        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());
  return (
    <Table
      aria-label="Pokemon table"
      {...props}
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}    >
      <MyTableHeader>
        <Column
          isRowHeader
        >
          Name
        </Column>
        <Column>
          Type
        </Column>
        <Column>
          Level
        </Column>
      </MyTableHeader>
      <TableBody
        items={items}
        renderEmptyState={props
          .renderEmptyState}
      >
        {(item) => (
          <MyRow>
            <Cell>
              {item.name}
            </Cell>
            <Cell>
              {item.type}
            </Cell>
            <Cell>
              {item
                .level}
            </Cell>
          </MyRow>
        )}
      </TableBody>
    </Table>
  );
}

<PokemonTable selectionMode="multiple" />

Selection behavior#

By default, Table uses the "toggle" selection behavior, which behaves like a checkbox group: 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. The "toggle" selection mode is often paired with a column of checkboxes in each row as an explicit affordance for selection.

When the selectionBehavior prop is set to "replace", 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. To move focus without moving selection, the Ctrl key on Windows or the Option key on macOS can be held while pressing the arrow keys. Holding this modifier while pressing the Space key toggles selection for the focused row, which allows multiple selection of non-contiguous items. On touch screen devices, selection always behaves as toggle since modifier keys may not be available. This behavior emulates native platforms such as macOS and Windows, and is often used when checkboxes in each row are not desired.

<PokemonTable selectionMode="multiple" selectionBehavior="replace" />

<PokemonTable
  selectionMode="multiple"
  selectionBehavior="replace"
/>

<PokemonTable
  selectionMode="multiple"
  selectionBehavior="replace"
/>

Row actions#

Table supports row actions via the onRowAction prop, which is useful for functionality such as navigation. In the default "toggle" selection behavior, when nothing is selected, clicking or tapping the row triggers the row action. When at least one item is selected, the table 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 "replace" selection behavior, where single clicking selects the row and actions are performed via double click. On touch devices, the action becomes the primary tap interaction, and a long press enters into selection mode, which temporarily swaps the selection behavior to "toggle" to perform selection (you may wish to display checkboxes when this happens). Deselecting all items exits selection mode and reverts the selection behavior back to "replace". Keyboard behaviors are unaffected.

<div style={{display: 'flex', flexWrap: 'wrap', gap: '24px'}}>
  <PokemonTable
    aria-label="Pokemon table with row actions and toggle selection behavior"
    onRowAction={key => alert(`Opening item ${key}...`)}    selectionMode="multiple" />
  <PokemonTable
    aria-label="Pokemon table with row actions and replace selection behavior"
    onRowAction={key => alert(`Opening item ${key}...`)}
    selectionBehavior="replace"    selectionMode="multiple" />
</div>

<div
  style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '24px'
  }}
>
  <PokemonTable
    aria-label="Pokemon table with row actions and toggle selection behavior"
    onRowAction={(key) => alert(`Opening item ${key}...`)}    selectionMode="multiple"
  />
  <PokemonTable
    aria-label="Pokemon table with row actions and replace selection behavior"
    onRowAction={(key) => alert(`Opening item ${key}...`)}
    selectionBehavior="replace"    selectionMode="multiple"
  />
</div>

<div
  style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '24px'
  }}
>
  <PokemonTable
    aria-label="Pokemon table with row actions and toggle selection behavior"
    onRowAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}    selectionMode="multiple"
  />
  <PokemonTable
    aria-label="Pokemon table with row actions and replace selection behavior"
    onRowAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}
    selectionBehavior="replace"    selectionMode="multiple"
  />
</div>

Links#

Table rows may also be links to another page or website. This can be achieved by passing the href prop to the <Row> component. Links behave the same way as described above for row actions depending on the selectionMode and selectionBehavior.

<Table aria-label="Bookmarks" selectionMode="multiple">
  <MyTableHeader>
    <Column isRowHeader>Name</Column>
    <Column>URL</Column>
    <Column>Date added</Column>
  </MyTableHeader>
  <TableBody>
    <MyRow href="https://adobe.com/" target="_blank">
      <Cell>Adobe</Cell>
      <Cell>https://adobe.com/</Cell>
      <Cell>January 28, 2023</Cell>
    </MyRow>
    <MyRow href="https://google.com/" target="_blank">
      <Cell>Google</Cell>
      <Cell>https://google.com/</Cell>
      <Cell>April 5, 2023</Cell>
    </MyRow>
    <MyRow href="https://nytimes.com/" target="_blank">
      <Cell>New York Times</Cell>
      <Cell>https://nytimes.com/</Cell>
      <Cell>July 12, 2023</Cell>
    </MyRow>
  </TableBody>
</Table>

<Table aria-label="Bookmarks" selectionMode="multiple">
  <MyTableHeader>
    <Column isRowHeader>Name</Column>
    <Column>URL</Column>
    <Column>Date added</Column>
  </MyTableHeader>
  <TableBody>
    <MyRow href="https://adobe.com/" target="_blank">
      <Cell>Adobe</Cell>
      <Cell>https://adobe.com/</Cell>
      <Cell>January 28, 2023</Cell>
    </MyRow>
    <MyRow href="https://google.com/" target="_blank">
      <Cell>Google</Cell>
      <Cell>https://google.com/</Cell>
      <Cell>April 5, 2023</Cell>
    </MyRow>
    <MyRow href="https://nytimes.com/" target="_blank">
      <Cell>New York Times</Cell>
      <Cell>https://nytimes.com/</Cell>
      <Cell>July 12, 2023</Cell>
    </MyRow>
  </TableBody>
</Table>

<Table
  aria-label="Bookmarks"
  selectionMode="multiple"
>
  <MyTableHeader>
    <Column
      isRowHeader
    >
      Name
    </Column>
    <Column>
      URL
    </Column>
    <Column>
      Date added
    </Column>
  </MyTableHeader>
  <TableBody>
    <MyRow
      href="https://adobe.com/"
      target="_blank"
    >
      <Cell>
        Adobe
      </Cell>
      <Cell>
        https://adobe.com/
      </Cell>
      <Cell>
        January 28,
        2023
      </Cell>
    </MyRow>
    <MyRow
      href="https://google.com/"
      target="_blank"
    >
      <Cell>
        Google
      </Cell>
      <Cell>
        https://google.com/
      </Cell>
      <Cell>
        April 5, 2023
      </Cell>
    </MyRow>
    <MyRow
      href="https://nytimes.com/"
      target="_blank"
    >
      <Cell>
        New York Times
      </Cell>
      <Cell>
        https://nytimes.com/
      </Cell>
      <Cell>
        July 12, 2023
      </Cell>
    </MyRow>
  </TableBody>
</Table>

Client side routing#

The <Row> component works with frameworks and client side routers like Next.js and React Router. As with other React Aria components that support links, this works via the RouterProvider component at the root of your app. See the client side routing guide to learn how to set this up.

Disabled rows#

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

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

By default, only row selection is disabled. When disabledBehavior is set to all, all interactions such as focus, dragging, and actions are also disabled.

<PokemonTable
  selectionMode="multiple"
  disabledKeys={[3]}
  disabledBehavior="all"
/>

<PokemonTable
  selectionMode="multiple"
  disabledKeys={[3]}
  disabledBehavior="all"
/>

<PokemonTable
  selectionMode="multiple"
  disabledKeys={[3]}
  disabledBehavior="all"
/>

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 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 {useAsyncList} from '@react-stately/data';

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

function AsyncSortTable() {
  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 = (parseInt(first) || first) < (parseInt(second) || second)
            ? -1
            : 1;
          if (sortDescriptor.direction === 'descending') {
            cmp *= -1;
          }
          return cmp;
        })
      };
    }
  });

  return (
    <Table
      aria-label="Example table with client side sorting"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}    >
      <TableHeader>
        <MyColumn id="name" isRowHeader allowsSorting>Name</MyColumn>
        <MyColumn id="height" allowsSorting>Height</MyColumn>
        <MyColumn id="mass" allowsSorting>Mass</MyColumn>
        <MyColumn id="birth_year" allowsSorting>Birth Year</MyColumn>
      </TableHeader>
      <TableBody items={list.items}>
        {(item) => (
          <Row id={item.name}>
            <Cell>{item.name}</Cell>
            <Cell>{item.height}</Cell>
            <Cell>{item.mass}</Cell>
            <Cell>{item.birth_year}</Cell>
          </Row>
        )}
      </TableBody>
    </Table>
  );
}

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

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

function AsyncSortTable() {
  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 =
            (parseInt(first) || first) <
                (parseInt(second) || second)
              ? -1
              : 1;
          if (sortDescriptor.direction === 'descending') {
            cmp *= -1;
          }
          return cmp;
        })
      };
    }
  });

  return (
    <Table
      aria-label="Example table with client side sorting"
      sortDescriptor={list.sortDescriptor}
      onSortChange={list.sort}    >
      <TableHeader>
        <MyColumn id="name" isRowHeader allowsSorting>
          Name
        </MyColumn>
        <MyColumn id="height" allowsSorting>
          Height
        </MyColumn>
        <MyColumn id="mass" allowsSorting>Mass</MyColumn>
        <MyColumn id="birth_year" allowsSorting>
          Birth Year
        </MyColumn>
      </TableHeader>
      <TableBody items={list.items}>
        {(item) => (
          <Row id={item.name}>
            <Cell>{item.name}</Cell>
            <Cell>{item.height}</Cell>
            <Cell>{item.mass}</Cell>
            <Cell>{item.birth_year}</Cell>
          </Row>
        )}
      </TableBody>
    </Table>
  );
}