Skip to content
flyingsalmon

Table

A table lays out rows of comparable data under column labels, with horizontal rules and nothing else.

StopNightsLodging
Kyoto3Ryokan Aoi
Kanazawa2Hotel Higashi
Tokyo4Shibuya Loft
Total93 stays

Installation

npx shadcn@latest add @flyingsalmon/table

Usage

import {
  Table,
  TableBody,
  TableCell,
  TableHeadCell,
  TableHeader,
  TableRow,
} from '@/components/ui/table'

const stops = [
  { id: 'kyoto', name: 'Kyoto', nights: 3 },
  { id: 'tokyo', name: 'Tokyo', nights: 4 },
]

export function TripStops() {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHeadCell>Stop</TableHeadCell>
          <TableHeadCell>Nights</TableHeadCell>
        </TableRow>
      </TableHeader>
      <TableBody>
        {stops.map((stop) => (
          <TableRow key={stop.id}>
            <TableCell>{stop.name}</TableCell>
            <TableCell>{stop.nights}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}

Examples

Numeric columns

Right-align a column of numbers so digits line up by place value, which is the only way to compare two amounts by reading down. Column labels stay left, because a label is a word, not a quantity.

StopNightsCost
Kyoto3¥48,000
Kanazawa2¥26,500
Total5¥74,500

Row headers

Give the cell that names a row scope row. A screen reader then announces each cell together with the row it belongs to.

StopArriveDepart
Kyoto12 Apr15 Apr
Kanazawa15 Apr17 Apr

Rows that lead somewhere

Mark a row interactive and one cell rowLink. That cell’s link stretches over the whole row, so a click anywhere follows it. Tab to a row and the rules above and below it turn orange. The Share button in each row still clicks and focuses on its own.

StopLodging
KyotoRyokan Aoi
KanazawaHotel Higashi

Empty table

There is no empty-state part. Write one row with a cell that spans every column, because only you know the column count.

TravellerRoleJoined
Nobody has joined this trip yet. Invite someone to start planning together.

With pagination

Put a pagination control under a long table, aligned right where the eye lands after the last row. The table renders the rows you hand it; slicing the data is yours.

PlaceNeighbourhoodDay
Fushimi InariFushimiDay 1
Kiyomizu-deraHigashiyamaDay 1
Nishiki MarketNakagyoDay 1

Guidelines

When to use

  • To compare the same fields across many items: stops on a trip, travellers and their roles, bookings and their costs.
  • When a reader scans down a column more than across a row.

When not to use

  • Use Card to show one item with several fields, because a card gives each item its own edge and room.
  • Use Timeline to show events in order with content beside each, because a timeline joins them with a connector.
  • Use Form to hold form fields in a grid, because a table announces a data relationship that fields do not have.

Do and don’t

  • Do
    Right-align numeric columns and leave labels left.Aligned digits are what let a reader compare two amounts by place value.
  • Do
    Close a column of amounts with a Total row in the footer.The sum lands under the last amount, where the eye arrives after reading down, and the footer’s heavier weight sets it apart from the rows it adds up.
  • Do
    In a before-and-after table, set the column that holds the outcome in medium weight.The reader compares what is with what will be, and the column that will be true is the one to read.
  • Don’t
    Label a column that holds only controls.The button already names the action. A label above it repeats the words and sits far from them, because the controls are right-aligned.
  • Don’t
    Let a row react to the pointer when nothing happens on click.The hover step tells a reader the row leads somewhere. A background change that leads nowhere reads as an affordance that is not there.

Accessibility

KeyDescription
TabMoves through the links and buttons in the rows. An interactive row has one stop for its row link; a second link or button in the same row is its own stop with its own focus ring.
EnterFollows the focused link, including the row link of an interactive row.
SpacePresses a focused button in a row.
ArrowLeftArrowRightOn a table wider than its container, scrolls it once the scroll region has focus.

The table is a native table, so screen readers announce its rows, columns, and cell positions with no ARIA. TableHeadCell defaults to scope="col" and is exposed as a column header; with scope={TableHeadCellScope.Row} in a body row it is exposed as a row header, so each cell is read with the row it belongs to. There is no caption part: label the table with aria-label or aria-labelledby on Table when the surrounding heading is not enough.

A table wider than its container sits in a focusable region with a focus ring, so a keyboard user can Tab to it and scroll it. The region is named by scrollRegionLabel, then by the table’s aria-label, then “Scrollable table”. A table that fits its container adds no tab stop.

An interactive row is not a link and holds no key handler of its own. Its row link is an anchor you write, so a router link works the same as an <a>, and Enter activates it natively. Focus on a row link paints the row’s hover background and turns the rules above and below it orange, in the same weight as the header rule: the louder state is for keyboard users, who have no pointer to say where they are.

API

Table

Also takes every <table> attribute, typed as TableProps. It wraps the table in a full-width scrolling container and sends className to the table itself. It sorts nothing, selects nothing, and paginates nothing: those belong to a data table built on top of it.

PropTypeDefaultDescription
scrollRegionLabelstring–Names the scroll region a table wider than its container sits in. Falls back to the table’s aria-label, then to "Scrollable table".

TableRow

Also takes every <tr> attribute.

PropTypeDefaultDescription
interactivebooleanfalseSteps the background to the accent colour on hover and on focus of the row link, and stretches the row link over the row. Only for a row that leads somewhere.

TableCell

Also takes every <td> attribute.

PropTypeDefaultDescription
rowLinkbooleanfalseMarks the cell whose link stretches over its interactive row. Any cell can hold it, not only the first, and only one cell per row: two stretched links cover the same area and fight over it.

TableHeadCell

Also takes every <th> attribute except scope.

PropTypeDefaultDescription
scopeTableHeadCellScopeTableHeadCellScope.ColumnColumn for a column label; Row for a cell in a body row that names that row.

TableHeader, TableBody, and TableFooter take only their element’s props.

  • Pagination

    The control that pages a long table.
  • Badge

    The marker for a status column.
  • Card

    Boxes a table, or shows one item instead of many.
  • Timeline

    Shows a sequence with content beside each marker.
  • Spacing

    The 4px scale behind the cell padding.