Data grid
A spreadsheet-style grid: pinned first column, sortable and reorderable columns, inline cell editing (a bottom sheet on phones), selection and add-row.
The first column is pinned and stays in view while the others scroll under it. rows draw in the order given until a sort is chosen; with no rows the grid draws nothing, so show an @khaeli/empty state in its place. Below 768px the same props draw a list instead of a grid: a tap edits the row's first editable cell in a bottom sheet, and a long press opens a menu of every editable column.
Sortable columns
Harbor mobile app
To do
15 Jan 2027
€73,000
Atlas redesign
In progress
4 Dec 2026
€48,000
Orchard API
In progress
18 Dec 2026
€64,000
Billing migration
In review
24 Nov 2026
€122,500
Lumen help centre
Done
30 Oct 2026
€18,500
5 projects
€326,000
5 projects
"use client"
import { useState } from "react"
import { DataGrid, type DataGridColumn } from "@/components/ui/data-grid"
import type { DataGridSort } from "@/components/ui/data-grid-sort"
type Project = { id: string; name: string; status: string; due: string; budget: number }
const projects: Project[] = [
{ id: "harbor", name: "Harbor mobile app", status: "To do", due: "2027-01-15", budget: 73000 },
{ id: "atlas", name: "Atlas redesign", status: "In progress", due: "2026-12-04", budget: 48000 },
{ id: "orchard", name: "Orchard API", status: "In progress", due: "2026-12-18", budget: 64000 },
{ id: "billing", name: "Billing migration", status: "In review", due: "2026-11-24", budget: 122500 },
{ id: "lumen", name: "Lumen help centre", status: "Done", due: "2026-10-30", budget: 18500 },
]
const money = new Intl.NumberFormat("en-GB", { style: "currency", currency: "EUR", maximumFractionDigits: 0 })
const day = new Intl.DateTimeFormat("en-GB", { dateStyle: "medium", timeZone: "UTC" })
const name: DataGridColumn<Project> = {
id: "name",
header: "Project",
cell: (project) => project.name,
sortValue: (project) => project.name,
}
const columns: DataGridColumn<Project>[] = [
{ id: "status", header: "Status", cell: (project) => project.status, sortValue: (project) => project.status },
{
id: "due",
header: "Due",
cell: (project) => day.format(new Date(project.due)),
sortValue: (project) => project.due,
},
{
id: "budget",
header: "Budget",
align: "right",
cell: (project) => <span className="tabular-nums">{money.format(project.budget)}</span>,
sortValue: (project) => project.budget,
footer: (rows) => money.format(rows.reduce((sum, project) => sum + project.budget, 0)),
},
]
export default function DataGridSortableColumns() {
const [sort, setSort] = useState<DataGridSort | null>(null)
return (
<div className="w-full min-w-0">
<DataGrid
aria-label="Projects"
pinned={name}
columns={columns}
rows={projects}
rowKey={(project) => project.id}
sort={sort}
onSortChange={setSort}
footer={`${projects.length} projects`}
/>
</div>
)
}
Inline editing
Task
Status
Estimate (days)
Due
Reference
Write the migration guide
In review
3
24 Nov 2026
T-318
Add keyboard shortcuts to the editor
In progress
5
2 Dec 2026
T-317
Fix the export time zone
To do
2
No date
T-314
3 tasks
3 tasks
"use client"
import { useState } from "react"
import { DataGrid, type DataGridColumn } from "@/components/ui/data-grid"
type Task = { id: string; title: string; status: string; estimate: string; due: string }
const tasks: Task[] = [
{ id: "T-318", title: "Write the migration guide", status: "In review", estimate: "3", due: "2026-11-24" },
{ id: "T-317", title: "Add keyboard shortcuts to the editor", status: "In progress", estimate: "5", due: "2026-12-02" },
{ id: "T-314", title: "Fix the export time zone", status: "To do", estimate: "2", due: "" },
]
const statuses = ["To do", "In progress", "In review", "Done"].map((status) => ({ value: status, label: status }))
const day = new Intl.DateTimeFormat("en-GB", { dateStyle: "medium", timeZone: "UTC" })
export default function DataGridInlineEditing() {
const [rows, setRows] = useState(tasks)
// The grid waits for the promise: resolve once `rows` holds the new value.
const save = (field: keyof Task) => async (task: Task, next: string) =>
setRows((current) => current.map((row) => (row.id === task.id ? { ...row, [field]: next } : row)))
const title: DataGridColumn<Task> = {
id: "title",
header: "Task",
cell: (task) => task.title,
edit: { kind: "text", required: true, value: (task) => task.title, onSave: save("title") },
}
const columns: DataGridColumn<Task>[] = [
{
id: "status",
header: "Status",
width: 150,
cell: (task) => task.status,
edit: { kind: "select", options: () => statuses, value: (task) => task.status, onSave: save("status") },
},
{
id: "estimate",
header: "Estimate (days)",
width: 150,
align: "right",
cell: (task) => <span className="tabular-nums">{task.estimate}</span>,
edit: { kind: "number", min: 0, value: (task) => task.estimate, onSave: save("estimate") },
},
{
id: "due",
header: "Due",
width: 150,
// The phone list leaves out a cell marked `data-placeholder`.
cell: (task) =>
task.due ? (
day.format(new Date(task.due))
) : (
<span data-placeholder className="text-muted-foreground">
No date
</span>
),
edit: { kind: "date", value: (task) => task.due, onSave: save("due") },
},
{ id: "id", header: "Reference", width: 120, cell: (task) => task.id },
]
return (
<div className="w-full min-w-0">
<DataGrid
aria-label="Tasks"
pinned={title}
columns={columns}
rows={rows}
rowKey={(task) => task.id}
footer={`${rows.length} tasks`}
/>
</div>
)
}
Row selection
Invoice
Project
Due
Amount
INV-1042
Atlas redesign
30 Nov 2026
€4,800
INV-1041
Billing migration
24 Nov 2026
€12,250
INV-1040
Harbor mobile app
15 Nov 2026
€7,300
INV-1039
Orchard API
8 Nov 2026
€9,100
1 of 4 selected
1 of 4 selected
"use client"
import { useState } from "react"
import { DataGrid, type DataGridColumn } from "@/components/ui/data-grid"
type Invoice = { number: string; project: string; due: string; amount: string }
const invoices: Invoice[] = [
{ number: "INV-1042", project: "Atlas redesign", due: "30 Nov 2026", amount: "€4,800" },
{ number: "INV-1041", project: "Billing migration", due: "24 Nov 2026", amount: "€12,250" },
{ number: "INV-1040", project: "Harbor mobile app", due: "15 Nov 2026", amount: "€7,300" },
{ number: "INV-1039", project: "Orchard API", due: "8 Nov 2026", amount: "€9,100" },
]
const number: DataGridColumn<Invoice> = { id: "number", header: "Invoice", cell: (invoice) => invoice.number }
const columns: DataGridColumn<Invoice>[] = [
{ id: "project", header: "Project", cell: (invoice) => invoice.project },
{ id: "due", header: "Due", width: 140, cell: (invoice) => invoice.due },
{
id: "amount",
header: "Amount",
width: 120,
align: "right",
cell: (invoice) => <span className="tabular-nums">{invoice.amount}</span>,
},
]
export default function DataGridRowSelection() {
const [selected, setSelected] = useState(new Set(["INV-1041"]))
return (
<div className="w-full min-w-0">
<DataGrid
aria-label="Invoices"
pinned={number}
columns={columns}
rows={invoices}
rowKey={(invoice) => invoice.number}
selectable
selected={selected}
onSelectedChange={setSelected}
footer={`${selected.size} of ${invoices.length} selected`}
/>
</div>
)
}
Manual order
Step
Team
Freeze the release branch
Platform
Publish the release notes
Product
Run the database migration
Platform
Announce release 4.2.0
Marketing
4 steps
4 steps
"use client"
import { useState } from "react"
import { DataGrid, type DataGridColumn } from "@/components/ui/data-grid"
type Step = { id: string; name: string; team: string }
const checklist: Step[] = [
{ id: "freeze", name: "Freeze the release branch", team: "Platform" },
{ id: "notes", name: "Publish the release notes", team: "Product" },
{ id: "migrate", name: "Run the database migration", team: "Platform" },
{ id: "announce", name: "Announce release 4.2.0", team: "Marketing" },
]
const name: DataGridColumn<Step> = { id: "name", header: "Step", width: 320, cell: (step) => step.name }
const columns: DataGridColumn<Step>[] = [{ id: "team", header: "Team", cell: (step) => step.team }]
export default function DataGridManualOrder() {
const [rows, setRows] = useState(checklist)
return (
<div className="w-full min-w-0">
<DataGrid
aria-label="Launch checklist"
pinned={name}
columns={columns}
rows={rows}
rowKey={(step) => step.id}
// Pass the rows back in the order the grid reports.
onReorder={(keys) => setRows(keys.flatMap((key) => rows.filter((step) => step.id === key)))}
footer={`${rows.length} steps`}
/>
</div>
)
}
Adding a row
Release
Channel
4.2.0
Stable
4.3.0-beta.1
Beta
2 releases
2 releases
"use client"
import { useState } from "react"
import { DataGrid, type DataGridColumn } from "@/components/ui/data-grid"
type Release = { id: string; version: string; channel: string }
const releases: Release[] = [
{ id: "r1", version: "4.2.0", channel: "Stable" },
{ id: "r2", version: "4.3.0-beta.1", channel: "Beta" },
]
const channels = ["Stable", "Beta", "Nightly"].map((channel) => ({ value: channel, label: channel }))
const version: DataGridColumn<Release> = {
id: "version",
header: "Release",
cell: (release) => release.version,
edit: { kind: "text", placeholder: "Version", required: true, value: (release) => release.version },
}
const columns: DataGridColumn<Release>[] = [
{
id: "channel",
header: "Channel",
cell: (release) => release.channel,
edit: { kind: "select", options: () => channels, value: (release) => release.channel },
},
]
export default function DataGridAddingARow() {
const [rows, setRows] = useState(releases)
return (
<div className="w-full min-w-0">
<DataGrid
aria-label="Releases"
pinned={version}
columns={columns}
rows={rows}
rowKey={(release) => release.id}
create={{
label: "New release",
required: ["version"],
defaults: { channel: "Beta" },
// Resolve with the new row's key once `rows` holds it.
onCreate: async (values) => {
const id = `r${rows.length + 1}`
setRows([...rows, { id, version: values.version ?? "", channel: values.channel ?? "Beta" }])
return id
},
}}
footer={`${rows.length} releases`}
/>
</div>
)
}
Installation
npx shadcn@latest add @khaeli/data-gridbunx --bun shadcn@latest add @khaeli/data-gridInstall @khaeli/foundation first: this item's styling lives in its tokens and [data-slot] rules.
Installs with
- Registry items
- npm packages
- @dnd-kit/core ^6.3.1
- @dnd-kit/sortable ^10.0.0
- @dnd-kit/utilities ^3.2.2
- @keyline-icons/react ^2.2.0
Keyboard
Tab- Enters at the sort buttons (one tab stop for the header row), then at the active cell. Inside the body Tab and Shift+Tab move one cell at a time, wrapping from row to row, and leave the grid only from its last and first cell.
EnterSpace- On a sort button: sorts ascending, then descending, then returns to the order given. The column header takes
aria-sortand the change is read out, as in Sorted by Project, ascending. ArrowLeftArrowRightHomeEnd- On a sort button: move to the previous, next, first or last sortable column. On a cell: the arrows move one cell, Home and End go to the first and last cell of the row.
ArrowUpArrowDown- Move the active cell one row.
EnterF2- Open the editor of an editable cell. A read-only cell is marked
aria-readonlyand does not open. Any character- Opens the editor with that character in place of the old value. In a date cell it opens the editor with the date kept.
BackspaceDelete- Open the editor empty, ready to clear the cell with Enter. A
requiredcolumn ignores them. EnterTabEscape- In an editor: Enter saves and returns to the cell, Tab saves and moves to the next cell, Escape discards. An empty required cell stays open with a message such as Task is required. A select editor filters as you type, ArrowUp and ArrowDown move the highlight and Enter chooses; a date editor takes YYYY-MM-DD or a day from its calendar.
Shift+Space- With
selectable: selects the focused cell's row, or deselects it. Focus stays on the cell and no editor opens. Alt+ArrowUpAlt+ArrowDown- With
onReorderand no sort chosen: move the focused cell's row one place and keep focus on the cell. The grip is for pointers and is not a tab stop. Escape- On a cell: removes the active ring; focus stays on the cell. On a cell of the new row: discards the row and moves focus to the button that adds one.
TabEnterSpace- In the list below 768px: every row is a tab stop, and Enter or Space opens the sheet for its first editable cell with focus in the field.
Context menu key- In the list: opens the row's menu with focus on its first entry. ArrowUp and ArrowDown move through the entries and wrap, Home and End go to the first and last, and Enter opens the sheet for that column. Escape or Tab closes the menu and returns focus to the row.
Accessible name
- The grid takes its name from
aria-label, which is required. - A sort button is named Sort by and the header, then Sort by Project, currently ascending. When a header is not plain text, give the column a
sortLabel. - With
selectable, the header checkbox is named Select all rows and every row's checkbox Select row. - A row's grip is named Move and the text of its pinned cell, so keep that cell's text meaningful.
- An editor's input is named by its column's
header, as in Task or Estimate (days), on the desktop and in the phone sheet. Aplaceholderis a hint only. - On a phone the sheet is a dialog named Edit and the column's header, with buttons named Cancel and Save.
Registry JSON
The item as the shadcn CLI reads it, with every file it ships: https://ui.khaeli.com/r/data-grid.json