Skip to content

Table

An accessible data table with row selection and automatic checkbox column, sortable columns, row actions and links, dynamic columns, drag-to-reorder, empty states, and three densities with optional striping, grid lines and frame.

React AriaSource

Installation

pnpm dlx shadcn@latest add @desyne/table

The CLI installs dependencies and any other components this one uses.

Usage

tsx
import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader,
} from "@/components/ui/table";
tsx
<Table aria-label="Users">
  <TableHeader>
    <Column isRowHeader>Name</Column>
    <Column>Role</Column>
  </TableHeader>
  <TableBody items={users}>
    {(user) => (
      <Row>
        <Cell>{user.name}</Cell>
        <Cell>{user.role}</Cell>
      </Row>
    )}
  </TableBody>
</Table>

Mark a row header

Set isRowHeader on the column that identifies each row (usually a name or id). Screen readers read it when moving between rows, so users know which row they're in. Every item in items also needs a unique id.

When to use

  • Table — comparing records across several attributes, with sorting, selection or bulk actions.
  • Grid List — a single column of rich rows, cards, or mobile-first lists.
  • List Box — picking values, not browsing data.
  • For simple, non-interactive tabular content in prose, a plain HTML <table> is fine.

Anatomy

tsx
<Table>                     {/* scroll container + role="grid" */}
  <TableHeader>             {/* adds a select-all column when selecting */}
    <Column isRowHeader />
    <Column allowsSorting />
  </TableHeader>
  <TableBody>
    <Row>                   {/* adds a checkbox cell when selecting */}
      <Cell />
      <Cell />
    </Row>
  </TableBody>
</Table>
PartRendersNotes
Table<div> › <table role="grid">The div scrolls horizontally and draws the card frame (framed). Provides density, striped and bordered to every cell.
TableHeader<thead>Muted background. Adds a checkbox column (select all in multiple mode) when selectionBehavior is toggle.
Column<th role="columnheader">Small, muted, non-wrapping. Shows a sort arrow when allowsSorting.
TableBody<tbody>Rows, or renderEmptyState when there are none.
Row<tr role="row">Hover and selected backgrounds. Adds a checkbox cell when selection uses checkboxes.
Cell<td role="gridcell">Non-wrapping, padded by density.

Examples

Density, striped and bordered

density sets cell padding (compact, default, comfortable). striped shades every other row, and bordered adds vertical grid lines.

Without a frame

framed={false} drops the table's own border and shadow so it can sit inside a card or panel.

Single selection

selectionMode="single" adds a checkbox column without a select-all box. Combine with disallowEmptySelection for a required choice.

Multiple selection and sorting

selectionMode="multiple" adds a select-all checkbox to the header. Sorting is controlled: give sortable columns an id and allowsSorting, then sort your data in onSortChange.

Sorting

Clicking a sortable header (or pressing Enter on it) toggles ascending and descending. The table only reports the new SortDescriptor; compare numbers numerically and strings with localeCompare (or Intl.Collator) yourself.

Selection behavior

selectionBehavior="replace" removes the checkbox column. A click selects one row, ⌘/Ctrl and Shift add more, and arrow keys move the selection like a desktop mail client.

Disabled rows

disabledKeys prevents selecting (and by default focusing) rows. Style them with data-disabled: on Row. disabledBehavior="selection" keeps them focusable.

Row actions

onRowAction makes rows actionable: clicking a row or pressing Enter calls it with the row's key. With checkbox selection as well, clicking a row performs the action while nothing is selected, and toggles selection once rows are selected; use selectionBehavior="replace" to select on click and act on double click or Enter.

Give a Row an href and the whole row navigates. Works with client-side routers through React Aria's RouterProvider.

Dynamic columns

Pass columns to TableHeader and each Row, and render both with functions. Here a multi-select Menu toggles column visibility; dependencies on TableBody re-renders rows when the columns change.

Rich cells

Cells take any content: avatars, badges, progress bars. Right-align numbers with text-right tabular-nums on both the column and its cells.

Empty state

renderEmptyState on TableBody fills the body when there are no rows.

Drag to reorder

Pass dragAndDropHooks from useDragAndDrop, add a column for the handle, and render a React Aria Button with slot="drag" in its cell. Rows can then be reordered by mouse, touch or keyboard.

Without grid lines

divided={false} removes the lines between rows. Pair it with striped (or nothing at all) for light, list-like tables such as plan comparisons.

Bleed

bleed drops the frame and lets the table run into its parent's horizontal padding (-mx-4, sm:-mx-6), so row hovers and dividers reach the card's edges while the first and last columns stay aligned with the text around them. Use it inside cards and sheets that use px-4 sm:px-6.

Expandable rows

Keep a set of expanded ids, put a TableExpandButton in the first cell and render the detail as an extra Row right after the parent, with one Cell that spans every column (colSpan). The button sets aria-expanded, and the detail row stays in the grid, so keyboard users reach it with the arrow keys.

Infinite scrolling

Give the table a fixed-height scroll container with containerClassName (the header stays sticky) and add TableLoadMore as the last child of TableBody. It calls onLoadMore when it scrolls into view and shows a spinner row while isLoading is true. Remove it, or stop calling your loader, when there's nothing left to fetch.

Resizable columns

Set allowsResizing on Table to let people drag column edges. Each Column gets a resize handle; give columns a defaultWidth (pixels, % or fr) and a minWidth/maxWidth to shape the starting layout, and opt one out with isResizable={false}. Keyboard users focus a header, press Enter to enter resize mode and use the arrow keys. onResizeEnd receives every column's width, which is the place to persist a user's layout. Cells truncate with an ellipsis while the table is resizable.

Recipes

Data table

Search, a status filter, sortable columns, a bulk-action bar that replaces the toolbar while rows are selected, and client-side pagination with Paginator.

Member management

An inline role Select and a per-row action Menu. Controls inside cells are reachable with the arrow keys and labelled with the member's name.

Permission matrix

A Checkbox in every cell, bordered grid lines and compact density. Each checkbox's aria-label names both the permission and the role.

Accessibility

  • The table is a role="grid": users move between cells with the arrow keys, and focus is a single tab stop.
  • Label the table with aria-label or aria-labelledby, and mark one column isRowHeader.
  • Sortable columns announce their sort direction with aria-sort.
  • The selection checkboxes are labelled automatically ("Select", "Select all") and linked to the row header.
  • Controls inside cells (buttons, selects, checkboxes) are reachable by arrowing into the cell. Give icon-only buttons an aria-label that names the row.
  • Visually hidden column labels (like "Actions") keep header cells meaningful for screen readers.
  • Drag and drop has keyboard and screen reader support built in.

Keyboard

KeyAction
TabMoves focus into and out of the table
↑ / ↓Moves focus to the row or cell above / below
← / →Moves focus between cells in a row (and into a cell's controls)
Home / EndMoves focus to the first / last cell in the row
Ctrl+Home / Ctrl+EndMoves focus to the first / last row
Page Up / Page DownMoves focus by a page
SpaceToggles selection of the focused row
EnterSorts by the focused column, or triggers the row action / link
Shift+↑ / Shift+↓Extends the selection (multiple)
⌘/Ctrl+ASelects all rows (multiple)
EscClears the selection

Styling

Data attributes

AttributeOnPresent when
data-focused / data-focus-visibleTable, Column, Row, CellFocused / keyboard focused
data-drop-targetTable, TableBody, RowA drag is over it
data-hoveredTableHeader, Column, Row, CellHovered with a mouse
data-pressedColumn, Row, CellBeing pressed
data-allows-sortingColumnallowsSorting is set
data-sort-directionColumnascending or descending when sorted by this column
data-emptyTableBodyThere are no rows
data-selectedRow, CellThe row is selected
data-disabledRow, CellThe row is disabled
data-selection-modeRowsingle or multiple
data-focus-visible-withinRowA cell or control in the row has keyboard focus
data-dragging / data-allows-draggingRowThe row is being dragged / drag and drop is enabled

Column and Row are Tailwind groups (group/column, group/row), so children can use group-data-selected/row: or group-data-hovered/column:.

Slots

data-slotElement
table-containerScroll container and frame
table<table>
table-header / table-columnHeader row and header cells
table-body / table-row / table-cellBody, rows and cells

Customizing

  • className on Table styles the <table> element (for example min-w-[640px] to force horizontal scroll). The container is always w-full overflow-auto.
  • Cells don't wrap by default. Add whitespace-normal to a Cell for long text, or max-w-* truncate to clip it.
  • Set column widths with w-* classes on Column.
  • Every part's className also accepts a function of its render props.
  • Column resizing and expandable tree rows aren't part of this component.

API Reference

Table

Prop

Type

Also accepts every prop of React Aria's Table.

TableHeader

Prop

Type

Column

Prop

Type

TableLoadMore

Prop

Type

TableExpandButton

Prop

Type

TableBody

Prop

Type

Row

Prop

Type

Cell

Prop

Type

  • Grid List — single-column interactive lists and cards.
  • Pagination — page controls for long tables.
  • Menu — row action menus and column pickers.
  • Checkbox — the selection control used in rows.