| Actions | ||||||||
|---|---|---|---|---|---|---|---|---|
| Ada Okafor | Pending | Android | 2 | 17 Nov, 15:42 | £204.00 | |||
| Lukas Berg | Pending | Web | 1 | 17 Nov, 12:55 | £68.95 | |||
| Tomás Herrera | Pending | iOS | 1 | 17 Nov, 09:07 | £118.00 | |||
| Leila Haddad | Paid | Android | 3 | 17 Nov, 06:21 | £155.00 | |||
| Mei Lin | Paid | Web | 3 | 17 Nov, 03:13 | £220.00 | |||
| Hana Novak | Paid | Android | 3 | 17 Nov, 00:34 | £242.00 | |||
| Hana Novak | Paid | iOS | 2 | 16 Nov, 21:01 | £86.00 | |||
| Ada Okafor | Paid | Android | 2 | 16 Nov, 19:18 | £182.95 | |||
| Ada Okafor | Paid | iOS | 3 | 16 Nov, 16:02 | £220.95 | |||
| Felix Wagner | Paid | In store | 3 | 16 Nov, 12:15 | £116.95 |
densitystateexpandableselectabledisabledimport { DataTable, DataTableAction, createColumnHelper } from "@/components/ui/data-table"
const col = createColumnHelper<Order>()
const columns = [
col.accessor("id", { header: "Order", size: 84, enableHiding: false, meta: { pin: "left", phone: "meta" } }),
col.accessor("customer", { header: "Customer", meta: { phone: "title" } }),
col.accessor("status", { header: "Status", size: 100, meta: { phone: "meta", phoneOrder: 2 } }),
col.accessor("channel", { header: "Channel", size: 84 }),
col.accessor("items", { header: "Items", size: 72, meta: { numeric: true } }),
col.accessor("placed", { header: "Placed", size: 116, meta: { phone: "meta", phoneOrder: 1, sortLabels: ["Oldest", "Newest"] } }),
col.accessor("amount", { header: "Amount", size: 96, meta: { numeric: true, phone: "value", sortLabels: ["Lowest", "Highest"] } }),
]
export function Orders({ orders }: { orders: Order[] }) {
return (
<DataTable
data={orders}
columns={columns}
noun={{ singular: "order", plural: "orders" }}
facet={{ column: "status" }}
defaultSorting={[{ id: "placed", desc: true }]}
getRowLabel={(o) => `Order #${o.id}`}
rowActions={(order) => (
<>
<DataTableAction>Copy order ID</DataTableAction>
<DataTableAction destructive>Refund</DataTableAction>
</>
)}
/>
)
}Usage
import { DataTable, createColumnHelper } from "@/components/ui/data-table"
type Order = { id: number; customer: string; status: string; amount: number }
const col = createColumnHelper<Order>()
const columns = [
col.accessor("id", { header: "Order", size: 84, meta: { pin: "left", phone: "meta" } }),
col.accessor("customer", { header: "Customer", meta: { phone: "title" } }),
col.accessor("status", { header: "Status", size: 100, meta: { phone: "meta" } }),
col.accessor("amount", { header: "Amount", size: 96, meta: { numeric: true, phone: "value" } }),
]
export function Orders({ orders }: { orders: Order[] }) {
return (
<DataTable
data={orders}
columns={columns}
noun={{ singular: "order", plural: "orders" }}
facet={{ column: "status" }}
/>
)
}Examples
248 orders
| Actions | ||||||||
|---|---|---|---|---|---|---|---|---|
| Ada Okafor | Pending | Android | 2 | 17 Nov, 15:42 | £204.00 | |||
| Lukas Berg | Pending | Web | 1 | 17 Nov, 12:55 | £68.95 | |||
| Tomás Herrera | Pending | iOS | 1 | 17 Nov, 09:07 | £118.00 | |||
| Leila Haddad | Paid | Android | 3 | 17 Nov, 06:21 | £155.00 | |||
| Mei Lin | Paid | Web | 3 | 17 Nov, 03:13 | £220.00 | |||
| Hana Novak | Paid | Android | 3 | 17 Nov, 00:34 | £242.00 | |||
| Hana Novak | Paid | iOS | 2 | 16 Nov, 21:01 | £86.00 | |||
| Ada Okafor | Paid | Android | 2 | 16 Nov, 19:18 | £182.95 | |||
| Ada Okafor | Paid | iOS | 3 | 16 Nov, 16:02 | £220.95 | |||
| Felix Wagner | Paid | In store | 3 | 16 Nov, 12:15 | £116.95 |
import { DataTable, DataTableAction, DataTableRowTrigger, createColumnHelper } from '@/components/ui/data-table';
type Order = { id: number; customer: string; status: string; placed: Date; amount: number };
const col = createColumnHelper<Order>();
const columns = [
col.accessor('id', {
header: 'Order',
size: 84,
enableHiding: false,
meta: { pin: 'left', phone: 'meta' },
cell: (c) => <DataTableRowTrigger>#{c.getValue()}</DataTableRowTrigger>,
}),
col.accessor('customer', { header: 'Customer', meta: { phone: 'title' } }),
col.accessor('status', { header: 'Status', size: 100, meta: { phone: 'meta', phoneOrder: 2 } }),
col.accessor('placed', {
header: 'Placed',
sortingFn: 'datetime',
// The phone line has room for the day, not the time.
meta: { phone: 'meta', phoneOrder: 1, phoneCell: (c) => c.getValue().toLocaleDateString() },
cell: (c) => c.getValue().toLocaleString(),
}),
col.accessor('amount', { header: 'Amount', size: 96, meta: { numeric: true, phone: 'value' } }),
];
export function Example({ orders }: { orders: Order[] }) {
return (
<DataTable
data={orders}
columns={columns}
getRowLabel={(o) => `Order #${o.id}`}
noun={{ singular: 'order', plural: 'orders' }}
facet={{ column: 'status' }}
rowActions={() => (
<>
<DataTableAction>Copy order ID</DataTableAction>
<DataTableAction destructive>Refund</DataTableAction>
</>
)}
/>
);
}0 orders
| Actions | ||||||||
|---|---|---|---|---|---|---|---|---|
import { useEffect, useState } from 'react';
import { DataTable, type DataTableState } from '@/components/ui/data-table';
export function Example() {
const [state, setState] = useState<Partial<DataTableState>>({
sorting: [{ id: 'placed', desc: true }],
columnFilters: [],
globalFilter: '',
pagination: { pageIndex: 0, pageSize: 10 },
});
const [page, setPage] = useState<{ rows: Order[]; total: number } | null>(null);
useEffect(() => {
fetchOrders(state).then(setPage);
}, [state]);
// Selection and column changes need no new page, so keep the query unless it changed.
const onStateChange = (next: DataTableState) => {
const asked = { sorting: next.sorting, columnFilters: next.columnFilters, globalFilter: next.globalFilter, pagination: next.pagination };
setState((prev) => (JSON.stringify(prev) === JSON.stringify(asked) ? prev : asked));
};
return (
<DataTable
data={page?.rows ?? []}
rowCount={page?.total ?? 0}
loading={!page}
columns={columns}
noun={{ singular: 'order', plural: 'orders' }}
facet={{ column: 'status', options: [{ value: 'Paid', count: 201 }, { value: 'Pending', count: 31 }] }}
sorting={state.sorting}
columnFilters={state.columnFilters}
globalFilter={state.globalFilter}
pagination={state.pagination}
onStateChange={onStateChange}
/>
);
}5,000 orders
| Actions |
|---|
import { DataTable } from '@/components/ui/data-table';
export function Example({ orders }: { orders: Order[] }) {
return (
<DataTable
data={orders}
columns={columns}
noun={{ singular: 'order', plural: 'orders' }}
virtualize
maxHeight={452}
/>
);
}Notes
Server mode
Set rowCount and the table stops sorting, filtering and paging on its own. Control the state, fetch on each change and pass the page back as data. onStateChange hands you every slice at once:
<DataTable
data={page.rows}
rowCount={page.total}
loading={pending}
sorting={state.sorting}
pagination={state.pagination}
globalFilter={state.globalFilter}
columnFilters={state.columnFilters}
onStateChange={setState}
/>The state holds selection and column visibility too, so refetch only when sorting, filters, search or paging changed; the Server-side example compares them.
With a page at a time, the header checkbox selects the page and the bar offers Select all 248. That selects every row on the server: each page arrives selected, and selectionActions gets selection.all, so act on the query rather than the ids. A new search or filter, Clear, or unticking a row ends it.
Selection and filters
Selected rows stay selected when a filter hides them. The bar counts the ones in view and says how many are hidden, and selectionActions gets only the ones in view, so a bulk action never reaches a row nobody can see. Clear drops both.
Phone
Below 768px the table becomes a list with no sideways scroll. Each row is two lines from the phone meta: the title and value columns, then the meta ones, ordered by phoneOrder. phoneCell renders a column there more briefly, such as a date without its time. Filters scroll as a chip row, one control by the title sorts, and tapping a row opens it in a sheet listing every visible column, with the row actions in its header.
Select, by the title, turns the rows into checkboxes and the search into the selection bar; a long press does the same and selects that row. Done clears the selection.
Changes and details
Every handler gets (value, details). details.cancel() refuses the change, and isAgentChange(details) tells you an agent made it. A sort, filter or search also sends the page back to 1, as a second change with its own details.
Pinned columns
The checkbox, the expander and any pin: "left" column stay put as the rest scrolls, with a shadow only while something is under them. Give pinned columns a size.
API
TanStack column definitions. Build them with createColumnHelper. Extras go on meta, below.null hides it.options with a count each in server mode.true reads Couldn't load orders. A node replaces the message.clear().rows are the selected rows the filters show; selection has their ids, the hidden ones, the count, and all once every row on the server is chosen.DataTableActions.getSubRows there.cell. The sheet still uses cell.["Oldest", "Newest"].<button>.Agent
Inside an AgentProvider, it appears in agent.snapshot() as select.
Reads
Sort ordersA multiple select. Its value is the sort in order, such as Amount descending; its items, each column both ways.
Select ordersA checkbox-group of the rows on the page, by their getRowLabel. Its value is every selected row. On phone too.
Search ordersThe search input.
Filter orders by StatusThe facet's toggle-group.
Pages of ordersThe page, a number.
Rows per pageThe page size, a select.
Actions
select("Amount descending")Sorts by a column. A bare column name takes its natural first direction; sortLabels such as Newest work too.
setValue(["Status ascending", "Amount descending"])Sorts by several columns.
clear()Back to the default sort, on Sort; no rows selected, on Select.
select("Order #4821")Selects rows by label or id, on Select. "all" selects everything that matches.
An agent's change runs through the same handlers as a person's, with isAgentChange(details) true; details.cancel() refuses it. A column that cannot sort, or a row that is not there, is refused with what is.
await agent.act({
steps: [
{ ref: "Filter orders by Status", action: "select", args: ["Paid"] },
{ ref: "Sort orders", action: "select", args: ["Amount descending"] },
{ ref: "Select orders", action: "select", args: ["Order #4821"] },
],
})Accessibility
- An ARIA
gridnamed by its title, witharia-rowcountfor every row, not just the page, andaria-rowindexon each. - Sorted headers carry
aria-sort, and a polite live region reads the new sort and count. It stays quiet while there is an error, which is analert. - Paging keeps focus on the page button while the next page loads, and Try again keeps it in the grid.
- Checkboxes are named Select page, or Select all when virtualized, and Select Order #4821; selected rows have
aria-selected. - Resize handles are
separators named Resize Amount, with their width asaria-valuenow. Headers are named by their label alone. - Column order changes from the Columns menu as well as by drag.
- Phone rows are buttons, at least 44px tall, and paging uses 44px targets. In Select mode each row is a
checkbox. - Long press is a shortcut only; the Select button reaches the same mode by tap, keyboard or screen reader.