Data Grid

Installation

npx shadcn@latest add @blank-pro/data-grid

Usage

import {
  createDataGridColumnHelper,
  DataGrid,
  DataGridColumnHeader,
  DataGridPagination,
  DataGridSearch,
  DataGridSelectAll,
  DataGridSelectRow,
  DataGridTable,
  DataGridToolbar,
  DataGridViewOptions,
  useDataGrid,
} from "@/components/ui/data-grid"

const column = createDataGridColumnHelper<Deployment>()

const columns = column.columns([
  column.display({
    id: "select",
    header: ({ table }) => <DataGridSelectAll table={table} />,
    cell: ({ row }) => <DataGridSelectRow row={row} />,
    enableSorting: false,
    enableHiding: false,
  }),
  column.accessor("commit", {
    header: ({ column }) => <DataGridColumnHeader column={column} title="Commit" />,
  }),
  column.accessor("duration", {
    header: ({ column }) => <DataGridColumnHeader column={column} title="Duration" />,
    meta: { align: "end" },
  }),
])

export function Deployments({ data }: { data: Deployment[] }) {
  const table = useDataGrid({ data, columns, getRowId: (row) => row.id })

  return (
    <DataGrid table={table}>
      <DataGridToolbar>
        <DataGridSearch />
        <DataGridViewOptions className="ml-auto" />
      </DataGridToolbar>
      <DataGridTable />
      <DataGridPagination />
    </DataGrid>
  )
}

useDataGrid is TanStack Table v9's useTable with the features a grid needs already registered: sorting, a global filter, column visibility, row selection and pagination. Everything else — initialState, controlled state with its on…Change callback, manualPagination for server data — is passed straight through. Define columns at module scope or memoise them, along with data; new arrays every render re-run every row model.

DataGrid puts the table in context, so each part is a single element and you arrange them as you like. The markup is Blank's Table.

Column headers are menus: sort ascending or descending, clear the sort, or hide the column, with aria-sort on the header cell. The search waits 150ms after typing before filtering, and Escape clears it; a search with no matches says so and offers to clear it. Shift-click on a row checkbox selects the range from the last row you clicked.

Column meta takes align ("start", "center" or "end"), a label for the column menu when the header is not a string, and headerClassName and cellClassName.

Examples

Loading and empty

loading swaps the rows for skeletons and disables paging. empty on DataGridTable replaces the message shown when there are no rows at all.

API Reference

useDataGrid

Takes TanStack useTable options except features; returns the table. globalFilterFn defaults to "includesString" and the page size to 10.

createDataGridColumnHelper

createDataGridColumnHelper<TData>() returns a column helper typed for the grid's features, including its column meta.

DataGrid

div props, plus:

DataGridToolbar

div props, with role="toolbar".

DataGridSearch

InputGroupInput props, plus:

DataGridViewOptions

Button props. Lists every column that can be hidden.

DataGridDensityToggle

ToggleGroup props, without its value props — density lives on DataGrid.

DataGridColumnHeader

DataGridSelectAll, DataGridSelectRow

Checkboxes for a select column. DataGridSelectAll takes the header's table; DataGridSelectRow takes the cell's row.

DataGridTable

Table props, plus:

DataGridPagination

div props, plus: