Table
A table lays out rows of comparable data under column labels, with horizontal rules and nothing else.
| Stop | Nights | Lodging |
|---|---|---|
| Kyoto | 3 | Ryokan Aoi |
| Kanazawa | 2 | Hotel Higashi |
| Tokyo | 4 | Shibuya Loft |
| Total | 9 | 3 stays |
Installation
npx shadcn@latest add @flyingsalmon/tableUsage
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.
| Stop | Nights | Cost |
|---|---|---|
| Kyoto | 3 | ¥48,000 |
| Kanazawa | 2 | ¥26,500 |
| Total | 5 | ¥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.
| Stop | Arrive | Depart |
|---|---|---|
| Kyoto | 12 Apr | 15 Apr |
| Kanazawa | 15 Apr | 17 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.
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.
| Traveller | Role | Joined |
|---|---|---|
| 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.
| Place | Neighbourhood | Day |
|---|---|---|
| Fushimi Inari | Fushimi | Day 1 |
| Kiyomizu-dera | Higashiyama | Day 1 |
| Nishiki Market | Nakagyo | Day 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
- DoRight-align numeric columns and leave labels left.Aligned digits are what let a reader compare two amounts by place value.
- DoClose 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.
- DoIn 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’tLabel 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’tLet 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
| Key | Description |
|---|---|
| Tab | Moves 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. |
| Enter | Follows the focused link, including the row link of an interactive row. |
| Space | Presses a focused button in a row. |
| ArrowLeftArrowRight | On 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| scrollRegionLabel | string | – | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| interactive | boolean | false | Steps 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| rowLink | boolean | false | Marks 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| scope | TableHeadCellScope | TableHeadCellScope.Column | Column 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.