Data table

InstallationCopy Anchor Link

npx shadcn@latest add @quireui-pro/data-table

UsageCopy Anchor Link

Describe the columns once with typed helpers, then hand the table your rows. Search, sorting, paging, counts and totals come from the column definitions.

const columns = defineColumns<Invoice>((column) => [
  column.person("customer", { sub: (row) => row.id, searchable: true, sortable: true }),
  column.badge("status", { labels, tones, icons, sortable: true }),
  column.text("owner", { searchable: true }),
  column.money("amount", { sortable: true, summary: "sum" }),
  column.date("due", { relative: true, sortable: true }),
]);

<DataTable
  title="Invoices"
  noun="invoices"
  rows={invoices}
  rowKey="id"
  columns={columns}
  filters={[filter.multi("status"), filter.range("amount"), filter.date("due")]}
/>

The helpers are typed to your rows, so a misspelled field is a type error. Everything sits in one row above the table and the table never moves while you work it: filters change in place, selecting turns that row into the selection bar, and the pager only appears when there is more than one page.

ColumnsCopy Anchor Link

Every helper also takes sortable, searchable, hideable, hidden, sticky and width. Money and numbers take summary (sum, average, count or range), shown in the footer over every matching row, not only the page. Money and dates are formatted in en-US unless you pass locale, so the server and the browser always agree.

Filters and viewsCopy Anchor Link

Each filter is a pill in the toolbar. Unset, it is a dashed "+ Status"; set, it turns solid and shows its value, "Status Overdue, Open", with a cross to clear it. A click opens its editor right under it:

• filter.multi: the column's values with how many rows each would give.
• filter.range: at least and at most, applied as you type.
• filter.date: the Date range picker's panel. Type "last 30 days", pick a preset or two days. Presets roll, so "Last 7 days" in a saved view still means the last 7 days tomorrow; in server mode the table sends the days they cover today.
• filter.boolean: yes or no.

Past four filters the rest wait under "More". Views are saved ways of looking at the rows, picked from the menu by the title with a live count each; a view can bring its own filters and order:

views={[
  { label: "All" },
  { label: "Overdue", filter: { status: ["overdue"] }, sort: { column: "amount", direction: "descending" } },
]}

Search waits behind an icon until it is wanted or / is pressed. The order, rows per page and which columns show sit behind one display button; clicking a header sorts too. storageKey remembers the hidden columns and the page size.

Selection and actionsCopy Anchor Link

bulkActions turns on selection: checkboxes that appear on hover, Shift-click ranges, and neighbouring selected rows joining into one block. While rows are selected the toolbar row becomes the selection bar, with the count, the total of the money column, "Select all" across pages and the actions.

rowActions adds actions to every row: those marked inline show as icon buttons on hover, and all of them are in the row's menu. when hides an action where it does not apply.

An action's run can return a function that reverses it. The table then shows a toast with Undo, which is kinder than asking first for anything that can be put back. For what cannot, confirm asks with a second click.

const remove: DataTableAction<Invoice> = {
  label: "Delete",
  icon: <TrashIcon />,
  danger: true,
  done: (n) => `Deleted ${n} invoices`,
  run: (rows) => {
    const before = list;
    setList(withoutRows(rows));
    return () => setList(before);
  },
};

PeekCopy Anchor Link

peek renders a quick look at a row in a panel over the table's edge, opened with Space or a click. It is not modal: J and K keep moving the cursor and the panel follows, so you can read through rows one after another. Esc closes it.

Narrow tablesCopy Anchor Link

Below 40rem of the table's own width, not the screen's, so a table in a sidebar compacts too, statuses keep only their icon and person columns drop the avatar. The word stays for screen readers and shows on hover. Turn it off per column with compact: false.

Loading and emptyCopy Anchor Link

While loading with no rows, skeleton rows in the shape of each column hold the space. A refetch with rows already there dims them, so nobody acts on stale data. With no rows at all the table says so (empty for your own message); when a search or filter finds nothing, it offers to clear them.

Server modeCopy Anchor Link

Pass total and the table stops narrowing the rows itself. It shows the rows you pass as the current page and reports what to fetch through onQueryChange: the search, filters, order, page and view. Search waits for a pause in typing, so every key is not a request. Give multi filters their options, and views their counts with viewCounts, since the table no longer sees every row.

<DataTable
  rows={page.rows}
  total={page.total}
  loading={loading}
  onQueryChange={async (query) => {
    setLoading(true);
    setPage(await fetchInvoices(query));
    setLoading(false);
  }}
  …
/>

AccessibilityCopy Anchor Link

The table is a grid with a row cursor, so Tab reaches it once and the keys do the rest; the cursor shows only while you use the keyboard. Sortable headers announce their order, selected rows are marked as selected, and every checkbox and icon button has a name. Press ? for the keys a table answers to; it only lists what that table supports.

MotionCopy Anchor Link

The peek slides in from the edge in 160ms and leaves faster; with the keyboard it switches instantly, like everything that answers a key. Checkboxes and row actions fade in on hover. Selecting, filtering and paging never move the table.

Data table or something else?Copy Anchor Link

• A few rows you render yourself, with no filtering or selection: the free Table.
• A list with one line per item and no columns: a plain list.

API referenceCopy Anchor Link