---
title: "Table"
description: "A bordered data table with sortable headings, selectable rows and a caption."
---

Use it for records that share the same fields and that a reader compares down a column: an audit log, a member list with roles and join dates, command usage. For a handful of label and value pairs, a list reads better.

It styles a native `<table>` and adds nothing between you and the markup. Sorting is yours: a heading reports that it was pressed and shows the order you tell it, and the rows are whatever you render.

_Live example of Table — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add table
```

Files written — React: components/ui/table.tsx. Vue: components/ui/table/Table.vue, components/ui/table/TableHeader.vue, components/ui/table/TableBody.vue, components/ui/table/TableRow.vue, components/ui/table/TableHead.vue, components/ui/table/TableCell.vue, components/ui/table/TableCaption.vue, components/ui/table/index.ts.

## Usage

React:

```tsx
import { Table } from "@/components/ui/table"
```

Vue:

```ts
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell, TableCaption } from "@/components/ui/table"
```

## API reference

**`Table`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `wrapperClassName / wrapperClass` | `string` | — | Classes for the scrolling wrapper, which is where a width or a max-height belongs. |

**`TableHead`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sort` | `"ascending" \| "descending" \| "none"` | — | Makes the heading a button and sets `aria-sort`. `none` is a sortable column the table is not currently sorted by. |
| `onSort / @sort` | `() => void` | — | Called when the sortable heading is activated. |
| `align` | `"start" \| "end"` | `"start"` | `end` aligns the heading with a column of numbers. |
| `scope` | `"col" \| "row"` | `"col"` | Which cells the heading labels. |

**`TableCell`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "end"` | `"start"` | `end` right-aligns the cell in left-to-right text and sets tabular figures. |

**`TableRow`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `selected` | `boolean` | — | Marks the row as chosen and sets `aria-selected`. |

`TableHeader`, `TableBody` and `TableCaption` render `<thead>`, `<tbody>` and `<caption>`. Put a plain `<tr>` inside the header; `TableRow` is for body rows.

## Accessibility

Because it is a real table, a screen reader announces the column heading with each cell and lets the reader move by row and column. Every `TableHead` has a `scope`. Give the table a `TableCaption`, which names it, or an `aria-label`. A sortable heading is a button inside the `<th>`, and the `<th>` carries `aria-sort`, so the current order is announced and not only shown by the arrow. On a narrow screen the wrapper scrolls sideways and the cells do not wrap.

## Tokens

Table reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
