Data Table

Basic

Density

Use density to step row vertical padding. The default matches existing behaviour (12px); compact (8px) packs more rows into a narrow viewport; editorial (20px) makes each row read as a card for high-design admin patterns. Horizontal cell padding is unchanged across densities. Themes can override per-density values by targeting [data-density="…"] from their own selectors.

Row Selection

Group Rows

Use rows instead of data when the server pre-groups results — calendar-grouped events, status-grouped tasks, date-ranged admin logs. Each entry is either a data row ({ kind: "data", id, row }) or a group-head separator ({ kind: "group", id, label, count? }). When rows is provided, column sort controls and the pagination footer are suppressed — the caller owns grouping and windowing.

Pass groupRowRenderer to replace the default eyebrow-style header with custom content — a badge, an icon, or any React node.

Loading State

Empty State

Installation

npx visor add data-table

This copies two files into your project and installs @tanstack/react-table:

• components/ui/data-table/data-table.tsx — the component
• components/ui/data-table/data-table.module.css — the styles

Usage

import { DataTable, type ColumnDef } from '@/components/ui/data-table/data-table';

interface User {
  id: string;
  name: string;
  email: string;
  role: string;
}

const columns: ColumnDef<User>[] = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'role', header: 'Role' },
];

export default function UsersPage({ users }: { users: User[] }) {
  return <DataTable columns={columns} data={users} enableRowSelection />;
}

API Reference

DataTableProps

The component also accepts all standard HTML attributes for the root <div>.

Source Files

After running npx visor add data-table, you'll have:

data-table.tsx

A "use client" component that wraps useReactTable from @tanstack/react-table and composes the existing Visor Table, TableHeader, TableBody, TableRow, TableHead, and TableCell primitives. Sorting, pagination, row selection, and global filter are all supported in either controlled or uncontrolled modes. The component re-exports the useful Tanstack types (ColumnDef, SortingState, RowSelectionState, PaginationState) so consumers don't need a second import.

data-table.module.css

All values use CSS custom properties from @loworbitstudio/visor-core, so the table automatically adapts to your active theme. The root uses container-type: inline-size so the pagination footer stacks vertically inside narrow containers without relying on viewport media queries. Sort headers use native <button> elements inside the <th> so screen readers announce them correctly; the parent <th> carries aria-sort.

Customization

After copying the component, you own it completely. Common customizations:

• Swap the native <select> page-size picker for Visor's Select compound if you want Radix-consistent styling across the app.
• Add server-driven pagination by passing pagination and onPaginationChange and wiring them to your data fetch.
• Extend the selection column with a bulk-action bar by reading rowSelection from the controlled state.
• Add column-visibility toggles by layering Tanstack's getVisibilityState-style APIs.