react-data-table

Storybook: anthony-liddle.github.io/react-data-table. Every feature is an interactive demo there.

npm install @anthony-liddle/react-data-table

A data-dense React table for admin and reporting screens. It was extracted from a production app and published as a standalone package.

Features

• Sorting: click a header to cycle ascending → descending → off, and opt in to multi-column sort with Shift+click or Shift+Enter. Sort headers are keyboard-operable buttons and report aria-sort.
• Grouped columns: parent headers spanning sub-columns, with a two-row header.
• Row selection: checkboxes, select-all, optional click-anywhere-on-the-row, and rows that can't be selected.
• Drag selection: press on a row and drag to select a range.
• Column management: show, hide, and reorder columns from a header panel, by mouse or keyboard.
• Pagination: a footer with range text and an optional "Page N of M", plus hooks for offset and cursor APIs.
• Persistence: column layout, sort, and filters written to the URL (shareable) and to localStorage (survives reloads).
• Also: row action menus with submenus, loading skeletons, expandable rows, and overridable labels.

ESM only, strict TypeScript, React 18 or 19. No Tailwind required: the package ships its own CSS.

Upgrading from an earlier version? MIGRATION.md lists every breaking change and what to do.

Setup

Import the stylesheet once, for example in your root layout:

import '@anthony-liddle/react-data-table/styles.css';

That is the whole setup. The table needs no Tailwind and no build step of its own.

Using Tailwind, or any cascade layers of your own? Import the layered copy instead, from your CSS entry, after a line that orders the layers. Between Tailwind's base and utilities, preflight leaves the table alone and a utility you pass through className wins:

@layer theme, base, react-data-table, components, utilities;
@import "tailwindcss";
@import "@anthony-liddle/react-data-table/styles.layer.css";

Import it here rather than from JavaScript, so the order line always comes first. A layer used before it is ordered goes to the bottom, under Tailwind's preflight, and the table loses its padding and borders. With the unlayered styles.css, Tailwind's utilities (which sit in a layer) can't override the table, so the layered copy is the one to use with Tailwind.

styles.layer.css is the same rules as styles.css inside @layer react-data-table. See Styling for theming and overrides.

Quick start

import { DataTable, type TableColumn } from '@anthony-liddle/react-data-table';

interface Member {
  id: string;
  name: string;
  email: string;
  team: string;
}

const columns: TableColumn<Member>[] = [
  { id: 'name', header: 'Name', sortKey: 'name', cell: ({ row }) => row.name },
  { id: 'email', header: 'Email', cell: ({ row }) => row.email },
  { id: 'team', header: 'Team', sortKey: 'team', cell: ({ row }) => row.team, hideByDefault: true },
];

export function Members({ members }: { members: Member[] }) {
  return <DataTable columns={columns} data={members} persistKey="members" />;
}

The table is controlled. You own the data, the sort, the selection, and the page, and the hooks below manage the usual cases. See the Features stories for each one wired up end to end.

DataTable props

Columns

interface TableColumn<T> {
  id: string;                // required, unique in the table, and stable across header text and translations
  header: string;            // header text
  sortKey?: string;          // makes the column sortable
  cell?: ({ row }) => ReactNode;
  loadingCell?: () => ReactNode;
  headerIcon?: ReactNode;
  headerClassName?: string;  // header cell classes
  cellClassName?: string;    // body cell classes
  subColumns?: TableColumn<T>[]; // makes this a grouped parent column
  hideByDefault?: boolean;   // starts hidden; can be shown from the panel
  alwaysVisible?: boolean;   // pinned: can't be hidden or moved, and stays out of the column panel
}

Hooks

sortBy lists the sorted columns in priority order, each { key, direction } with a lowercase 'asc' or 'desc'; unsorted is an empty list. If your API wants an uppercase enum, convert at the call. reset() returns to defaultSortBy, and setSortBy([]) clears the sort.

With multiSort: true, Shift+click on a header (or Shift+Enter or Shift+Space on a focused one) adds that column as the next sort key, then flips it, then removes it, leaving the others in place. A plain click still makes the column the only sort. Each sorted column shows a small number with its place while two or more are sorted. Turn it on only when your API can sort by several fields.

To keep the selection in your own state instead of useTableSelection, pass isRowSelected, onToggleRow and onToggleAll to the selection prop yourself. A Shift range or a drag calls onToggleRow once for each row it changes, in a single event, so update your state from its previous value (setSelected(prev => ...)). Otherwise only the last row sticks.

usePagination hands back the offset and limit for the current page. The total row count usually arrives with that page, so the table's pagination prop is built from it at render time:

const { offset, limit, getPagination, reset } = usePagination({ pageSize: 25 });
const { items, total } = useMembers({ offset, limit }); // your fetch, or rows.slice(offset, offset + limit)

<DataTable columns={columns} data={items} pagination={getPagination(total)} />;

Call reset() when the sort or filters change, so the table goes back to the first page. useTableSort's onChange runs on every sort change except restoring a persisted one, so it's the place for that: useTableSort({ onChange: () => reset() }).

TablePagination.totalCount is optional, since cursor APIs often have no total. Without it the footer reads "Showing 11-20", ending at the page's row count (DataTable supplies it; a standalone Pagination takes pageRowCount), it drops "Page N of M", and Next follows hasNextPage. A negative or non-finite total, such as an API's -1 for unknown, counts as none. usePagination works out hasNextPage from the total, so it needs the real one. With an unknown total, use useCursorPagination for a cursor API, or build the pagination prop yourself with your API's own hasNextPage. A page with no rows reads "Showing 0-0".

Labels

Every string the table renders or announces comes from labels, so a translation covers screen reader names too. Pass any subset to DataTable or Pagination; the rest keep their English defaults, which defaultLabels exports.

A standalone TableActionMenu names its trigger "Actions", or triggerLabel.

Persistence

Give the table and its hooks the same persistKey. What is worth sharing goes in the URL, and the column layout stays in the browser:

• A link is the whole view. When a page opens with params in a table's namespace that it didn't write itself, those params alone set the view: a state the link leaves out takes its default, and saved state isn't read. Otherwise each state reads its own param, then localStorage, then its default. The column layout is never part of a link, so it always comes from localStorage.
• The URL shows the current view. Once restored, and on every change, state is written back with history.replaceState, keeping your other params, the hash and history.state. The sort is always written, as {key}.sort= when unsorted, so the address bar gains the table's params on first load.
• Readable, checked one param at a time. A sort is a comma list in priority order, - marking descending, and the page is 1-based and absent on page 1. A param that doesn't parse, or a sort naming a column outside sortableColumns, takes its default while the others still apply. A page past the end is kept: the table shows its empty state and Previous still works. Storage keys carry a format version (rdt:1:), so a later format ignores old entries.
• Names. Sort keys can't contain commas or start with -, and filter param names can't contain .. Give each table on a page its own key, and use one usePersistedFilters per key.
• Pass sortableColumns with a persistKey. A link can name any sort key, and without the list it goes straight into your query; with it, an unknown key falls back to the default.
• Server rendering. The server render, and the client render that hydrates it, use the defaults, so persisted state never causes a hydration mismatch; it arrives in the render straight after. A client-only render starts from it. Each hook returns isRestored, false only during those first renders, so you can hold a fetch until the persisted state is in.

Styling

Every element the table renders has a documented class, and runtime state lives on attributes, so you restyle it with ordinary CSS. Each base rule in styles.css is a single class, and a modifier or state adds at most one more class, attribute or pseudo-class. So one class of yours, loaded after the stylesheet, overrides a base style, and the same class with the same state overrides a stateful one. Nothing uses !important, and the stylesheet resets only its own elements, never your markup inside a cell.

Theme

Colours come from shadcn-style tokens, read as full colour values: --background, --foreground, --card, --popover, --popover-foreground, --primary, --primary-foreground, --muted, --muted-foreground, --accent, --accent-foreground, --border and --ring. The package never declares them. It reads each one with a built-in default, so a theme you declare anywhere wins, even inside a cascade layer, and .dark on any ancestor, or on a component's own element, switches the defaults. Menus and the column panel render at the end of <body>, so when their table sits in a .dark section they copy .dark onto themselves. A current shadcn/ui theme applies as it is.

Older shadcn themes wrote bare HSL triplets (--card: 0 0% 100%) and read them as hsl(var(--card)). To use one here, change both together: write each value as a full colour (--card: hsl(0 0% 100%)), and read it as var(--card) everywhere in your own CSS, including a Tailwind @theme mapping. Changing only the values gives hsl(hsl(...)), which is invalid.

Custom properties

Set these on :root, on any ancestor of the table, or on a single row through rowClassName.

Classes and state

Inside DataTable, a sortable header is both rdt-table__header-cell and rdt-sort-header. The column panel and the row menus render in a portal at the end of <body>, so style them by their own classes, not through .rdt-table.

Example

/* Denser rows and square corners for every table on the page */
:root {
  --rdt-cell-padding-y: 0.25rem;
  --rdt-radius: 0;
}

/* Tint selected rows as well, in both themes. These keep shadcn's
   default muted text at 4.5:1. */
:root {
  --rdt-row-selected: oklch(0.985 0.012 250);
}

.dark {
  --rdt-row-selected: oklch(0.26 0.03 255);
}

/* Bold the sorted column's header */
.rdt-table__header-cell[aria-sort] {
  font-weight: 600;
}

Accessibility

On every PR, each story is rendered in headless Chromium and checked with axe (@storybook/addon-a11y).

• Clickable rows: rows don't take focus, since a focused <tr> can't announce that it does anything. For a row that opens something, put a real link (or button) in its main cell for keyboard and screen reader users, and use onRowClick as the mouse shortcut for the rest of the row. Clicks on the link don't count as row clicks, so nothing fires twice. The Clickable Rows story shows it.
• Expandable rows have a real button, named "Details for ⟨label⟩", with aria-expanded and, while open, aria-controls pointing at the panel.
• Sort headers are buttons. The primary sorted column carries aria-sort; while two or more columns are sorted, each sorted header also announces its place and direction ("sort priority 2, descending").
• Header cells use scope="col", and grouped parent headers use scope="colgroup".
• Checkboxes, pagination buttons ("Previous page" / "Next page"), the column settings trigger, and column drag handles ("Reorder ⟨column⟩") all have accessible names.
• Row checkboxes and row menus are named after their row ("Select ⟨label⟩", "Actions for ⟨label⟩") when you pass getRowLabel, for example the row's name. Without it they fall back to "row ⟨id⟩", so pass it whenever rows have a human-readable name.
• The column settings panel is a dialog: Tab reaches every checkbox and handle, Space toggles a column, and a focused handle reorders with Space, the arrow keys, and Space.
• Row menus are Radix dropdown menus with arrow-key navigation.

Known gaps:

• Drag selection and click-to-select rows are mouse-only. The checkboxes are the keyboard path, and Shift+Space on a focused checkbox sets every row from the last one toggled.

Known issues

None at the moment. Report one on GitHub.

Development

pnpm install
pnpm storybook        # http://localhost:6006
pnpm test             # unit tests (Vitest + happy-dom)
pnpm test:storybook   # every story in Chromium: play functions + axe
pnpm lint             # Biome
pnpm typecheck
pnpm build            # dist/
pnpm lint:package     # publint + are-the-types-wrong
pnpm smoke            # install the packed tarball and use it

pnpm test:storybook needs Chromium once: pnpm exec playwright install chromium.

Releases publish from CI when a GitHub Release is published, via npm trusted publishing with provenance. See CONTRIBUTING.md.

License

MIT © Anthony Liddle