Data Table

Installation

Copy the source into your project, or keep it behind a package.

npx shadcn@latest add Tinkerers-Labs/mischief-ui/data-table

import { DataTable } from "mischief-ui/data-table"

1"use client"2 3import * as React from "react"4import { ArrowDown, ArrowUp, ChevronsUpDown } from "lucide-react"5import { cn } from "@/lib/utils"6 7export type SortDirection = "asc" | "desc"8 9export type DataTableSort = { column: string; direction: SortDirection }10 11export type SortValue = string | number | boolean | Date | null | undefined12 13export type Column<TRow> = {14  /** Identifies the column, and names the field read when there is no value. */

Usage

const columns: Column<Person>[] = [
  { key: "name", header: "Name", sort: true },
  { key: "email", header: "Email", cell: (p) => <a href={`mailto:${p.email}`}>{p.email}</a> },
  { key: "seats", header: "Seats", width: "6rem", align: "end", sort: true },
]

export function People({ people }) {
  return (
    <DataTable
      rows={people}
      columns={columns}
      getKey={(person) => person.id}
      label="People"
    />
  )
}

Three levels of effort

A column with no sort property is not sortable, and its heading is plain text rather than a button that looks pressable and does nothing.

sort: true uses the built-in comparator against the column's value, which is the field named by key unless you gave it one. Numbers compare as numbers, dates as dates, and everything else by the reader's locale, so ten does not sort before nine and Ä does not sort after Z.

{ key: "seats", header: "Seats", sort: true }
{ key: "plan", header: "Plan", sort: (a, b) => RANK[a.plan] - RANK[b.plan] }

Pressing a heading a third time clears the sort and returns the rows to the order they arrived in, which is often the order that meant something before anyone touched it.

Empty cells sit at the bottom whichever way the column is pointing. A column of blanks at the top is never what was being asked for.

Widths, and dragging them

The table is laid out with fixed columns and a colgroup, so a width is any CSS length you like. Columns without one share whatever is left over in equal parts, which is the behaviour you would reach for a fraction unit to get.

{ key: "plan", header: "Plan", width: "8rem" }
{ key: "name", header: "Name" }  // takes a share of the rest

With resizable on, every boundary between two columns can be dragged. The last column has no handle, because there is nothing to its right to trade width with. The first drag pins every column to the width it already had, so pulling one boundary does not make the others jump about, and a drag writes straight to the colgroup rather than into state, so moving a boundary renders nothing.

Each handle is a separator that can be focused and moved with the arrow keys, because a table whose columns can only be adjusted by dragging cannot be adjusted by everybody. Double-clicking a handle returns that column to the width you declared, and no column can be dragged below its minimum and lost.

Selection is kept in keys

Passing any of selected, defaultSelected, or onSelectionChange turns selection on. What is stored is whatever getKey returns, never a row position, so sorting the table does not silently change what is selected.

Shift-clicking a checkbox extends from the last one touched, which is what people try first. The heading checkbox selects everything and shows the third, in-between state when only some rows are chosen -- a state that has to be set as a property rather than an attribute, which is why it is easy to leave out.

Clicking a row never selects it. Only the checkbox does. That keeps onRowClick free to mean open this without the two gestures fighting, and keeps a link inside a cell working.

Holding a column while the rest scrolls

A wide table scrolls sideways, and the column saying which row you are looking at is the first thing to go. Pinning holds it against the left edge. The checkbox column is held with it whenever anything is pinned, because a column of checkboxes that has scrolled away from its rows is worse than no checkboxes at all.

{ key: "name", header: "Name", pinned: "start", width: "11rem" }

Each held column's distance from the edge is written as a custom property rather than as a class, which is what lets the offsets follow a drag. Widen a held column and the ones after it move with it on the same frame, without anything re-rendering. Resizing and pinning are a pair: it is resizing that makes a table wide enough to need it.

Waiting, and not flashing while you do

loading fills the body with placeholders shaped like the rows they stand in for: one per column, at the same density, so nothing shifts under the reader when the data lands.

They are held back for a tenth of a second first. Most answers arrive faster than that, and a skeleton that appears and vanishes inside two frames reads as a flicker rather than as progress. The table marks itself busy while it waits, and the placeholders carry no text, so there is nothing for a screen reader to read out of them.

Totals

A column with a footer gets one, and the table grows a foot only when at least one column has asked for it. The function is handed the rows in the order they are shown, so a total is the sum of what is in front of you.

{
  key: "seats",
  header: "Seats",
  align: "end",
  sortFirst: "desc",
  footer: (rows) => rows.reduce((total, row) => total + row.seats, 0),
}

What it deliberately does not do

There is no pagination, no filtering, and no toolbar in here. Mischief already has pagination, and an empty row for when a filter matches nothing, and they compose better as themselves than they would absorbed into this.

<DataTable rows={page} columns={columns} getKey={byId} label="Invoices" />
<Pagination page={page} pageCount={pages} onPageChange={setPage} />

There is no virtualisation either. It would change how every row is rendered, and a few hundred rows do not need it. Reach for a windowing library when you genuinely have thousands.

Nor is there a menu for hiding columns, because there does not need to be. Columns are an array you own, so hiding one is filtering that array before you hand it over, and the widths, the sorting and the pinning all follow from that with nothing else to keep in step.

const shown = columns.filter((column) => visible[column.key])

<DataTable rows={rows} columns={shown} getKey={byId} label="Invoices" />

API

Accessibility

A real table with a caption, column headers scoped to their columns, and aria-sort on any column that can be sorted, so the current order is announced when a heading is reached. Sort controls are buttons with a touch-sized target. Resize handles are separators in the tab order, driven by the arrow keys. Every checkbox is named with the row it selects rather than being a column of boxes called Select, and the number chosen is kept in a polite live region. onRowClick is pointer only and is documented as never being the only route to what it does. While loading it marks itself busy, and the placeholders carry no text for anything to read out.