# Data Grid

> Editable React data grid that works like a spreadsheet: arrow keys between cells, type to edit, block selection, copy and paste with Excel or Sheets, undo.

- Kind: Component (Tables)
- Docs: https://ui.minidev.pro/docs/data-grid
- Source (registry JSON with the full file): https://ui.minidev.pro/r/data-grid.json
- License: MIT. One file, yours to edit after install.

## When to use

Use it when people change many values in place: price lists, stock counts, budgets, bulk imports. Columns are text, number, select or checkbox. Shift+arrows select a block, Cmd/Ctrl+C copies it as tab-separated text, Cmd/Ctrl+V pastes a block from a spreadsheet and turns "1,240.50" into a number, Delete clears and Cmd/Ctrl+Z undoes. The grid is controlled: it shows `rows` and hands every edit to `onRowsChange`; without that prop it is read-only. The header and first column stay put while you scroll, and columns resize by dragging the header edge. For sorting, filtering and row selection use DataTable; to edit a single value in a read-only table use InlineCellEdit; for query output use SqlResultTable.

## Installation

### shadcn CLI (copies the source into your project)

```bash
npx shadcn@latest add @minidev/data-grid
```

Writes `components/ui/data-grid.tsx` plus the MiniDev files it is built from (checkbox, select) and installs its npm dependencies. Older CLI versions: `npx shadcn@latest add https://ui.minidev.pro/r/data-grid.json`.

### npm package

```bash
npm i minidev-ui-kit
```

Add the tokens to your global stylesheet once:

```css
@import "tailwindcss";
@import "minidev-ui-kit/styles.css";
@source "../node_modules/minidev-ui-kit";
```

Next.js also needs `transpilePackages: ["minidev-ui-kit"]` in next.config.

## Import

After the shadcn install:

```tsx
import { DataGrid } from "@/components/ui/data-grid"
```

From the npm package:

```tsx
import { DataGrid } from "minidev-ui-kit/ui/data-grid"
```

## Usage

```tsx
import { DataGrid } from "@/components/ui/data-grid"

export function Example() {
  return (
    <DataGrid />
  )
}
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `columns` | `DataGridColumn<T>[]` | - | yes | Column definitions, left to right. The first column stays visible while scrolling sideways. |
| `rows` | `T[]` | - | yes | The rows to show. The grid never copies them: edits go to `onRowsChange`. |
| `onRowsChange` | `(rows: T[]) => void` | - | no | Fires with a new rows array after each edit, paste, clear or undo. Leave it out for a read-only grid. |
| `getRowId` | `(row: T, index: number) => string` | `(_, i) => String(i)` | no | Stable key for each row. Defaults to the row index. |
| `rowNumbers` | `boolean` | `true` | no | Show a numbered column on the left. Click a number to select its row. |
| `aria-label` | `string` | - | yes | Accessible name of the grid, such as "Price list". |
| `className` | `string` | - | no | Size the scroll area here, for example `max-h-[32rem]`. |

## Examples

### Price list

Text, select, number and checkbox columns, a read-only SKU column and row numbers. Type to edit, Enter to save and move down.

```tsx
const columns: DataGridColumn<Product>[] = [
  { key: "sku", header: "SKU", width: 104, readOnly: true },
  { key: "name", header: "Product", width: 200 },
  { key: "category", header: "Category", type: "select", options: [{ value: "paper", label: "Paper" }, { value: "pens", label: "Pens" }] },
  { key: "price", header: "Price (USD)", type: "number" },
  { key: "stock", header: "Stock", type: "number" },
  { key: "active", header: "Active", type: "checkbox" },
]

function PriceList() {
  const [rows, setRows] = React.useState(products)
  return <DataGrid aria-label="Price list" columns={columns} rows={rows} onRowsChange={setRows} getRowId={(r) => r.sku} className="max-h-80" />
}
```

### Budget with a computed column

onRowsChange recomputes Total after every edit or paste, and the read-only column skips edits and pastes.

```tsx
function Budget() {
  const [rows, setRows] = React.useState(lines)
  return (
    <DataGrid
      aria-label="Q1 budget"
      columns={[
        { key: "item", header: "Line item", width: 200 },
        { key: "qty", header: "Qty", type: "number" },
        { key: "unit", header: "Unit cost", type: "number" },
        { key: "total", header: "Total", type: "number", readOnly: true },
      ]}
      rows={rows}
      onRowsChange={(next) => setRows(next.map((r) => ({ ...r, total: r.qty != null && r.unit != null ? r.qty * r.unit : null })))}
      rowNumbers={false}
    />
  )
}
```

### Paste from a spreadsheet

Copy rows from Excel or Google Sheets and paste them at the active cell. "$18.00" becomes the number 18.

```tsx
const empty = Array.from({ length: 6 }, () => ({ sku: "", name: "", price: null as number | null }))

function PasteImport() {
  const [rows, setRows] = React.useState(empty)
  return (
    <DataGrid
      aria-label="Import products"
      columns={[
        { key: "sku", header: "SKU" },
        { key: "name", header: "Product", width: 200 },
        { key: "price", header: "Price", type: "number" },
      ]}
      rows={rows}
      onRowsChange={setRows}
    />
  )
}
```

## Keyboard interactions

| Key | Action |
| --- | --- |
| `ArrowUp` or `ArrowDown` or `ArrowLeft` or `ArrowRight` | Moves the active cell. |
| `Shift+ArrowUp` or `Shift+ArrowDown` or `Shift+ArrowLeft` or `Shift+ArrowRight` | Grows or shrinks the selected block. |
| `Ctrl+ArrowDown` or `Cmd+ArrowDown` | Jumps to the last row. With the other arrows, jumps to the first row, first column or last column. |
| `Home` or `End` | Moves to the first or last column. With Ctrl or Cmd, to the first or last cell of the grid. |
| `Tab` or `Shift+Tab` | Moves one cell right or left. From the last or first column, focus leaves the grid. |
| `Enter` or `F2` | Edits the active cell, keeping its text. On a checkbox cell, toggles it; on a select cell, opens the options. |
| `A-Z` or `0-9` | Starts editing and replaces the cell's text with the typed character. |
| `Space` | Toggles a checkbox cell. On a text or number cell, starts editing like any other character. |
| `Enter` or `Shift+Enter` | While editing, saves and moves down or up. |
| `Tab` or `Shift+Tab` | While editing, saves and moves right or left. |
| `Escape` | While editing, cancels and keeps the old value. Otherwise, shrinks the selection to the active cell. |
| `Delete` or `Backspace` | Clears every editable cell in the selection. Select cells keep their value. |
| `Ctrl+C` or `Cmd+C` | Copies the selection as tab-separated text. Checkboxes copy as TRUE or FALSE, selects as their label. |
| `Ctrl+V` or `Cmd+V` | Pastes tab-separated text at the top-left cell of the selection. |
| `Ctrl+Z` or `Cmd+Z` | Undoes the last edit, paste or clear. |
| `Ctrl+A` or `Cmd+A` | Selects every cell. |

## Accessibility

- The `<table>` has `role="grid"`, the required `aria-label`, `aria-rowcount`, `aria-colcount` and `aria-multiselectable`. Rows carry `aria-rowindex` (the header row is 1), cells carry `aria-colindex`, and row numbers are `<th scope="row">` row headers.
- Only the active cell has `tabIndex=0`, and focus moves from cell to cell, so the grid is one tab stop. Cells in the selection have `aria-selected="true"`, read-only columns have `aria-readonly`, and the whole grid is `aria-readonly` without `onRowsChange`.
- Editors are labelled with the column and row, such as "Price, row 3". Number cells edit in an `<input>` with `inputMode="decimal"`, and select cells open a Base UI Select. A checkbox cell's box is `inert` and the cell holds hidden "checked" or "not checked" text, so the cell stays the only focus stop.
- Column resizing is pointer only: the handle on each header edge is `aria-hidden` and has no keyboard control.

## FAQ

### How do I paste data from Excel or Google Sheets?

Click the cell where the top-left value should land and press Cmd+V or Ctrl+V. DataGrid reads the tab-separated text both apps copy, including quoted cells with line breaks, fills right and down, and fills a whole selected block when you paste one value. Read-only columns, values that do not fit the column type and anything past the last row or column are skipped: paste never adds rows.

### How are pasted or typed numbers parsed?

Number columns drop currency symbols, spaces and thousands commas, so "$1,240.50" becomes `1240.5` and "(1,200)" becomes `-1200`; a comma that is not a thousands separator, as in "1,5" or "1.240,50", is rejected and the cell keeps its value. Clearing a number cell writes `null`, so type those fields `number | null`. Checkbox cells take TRUE, yes, 1 or x, and select cells match an option's value or label.

### How do I add a computed column or reject an edit?

Every change arrives in `onRowsChange` as a whole new array, so recompute there: `onRowsChange={(next) => setRows(next.map((r) => ({ ...r, total: r.qty * r.unit })))}`, and mark the column `readOnly`. The grid only shows `rows`, so an edit you do not store simply disappears. Cmd/Ctrl+Z restores the array from before the last change, up to 50 steps.

### Is DataGrid virtualized? How many rows can it handle?

No. It renders every cell, which stays smooth to roughly 2,000 rows. Past that, page the data or build on [`VirtualList`](https://ui.minidev.pro/docs/virtual-list). For sorting, filtering and row selection without cell editing, use [`DataTable`](https://ui.minidev.pro/docs/data-table).

## Rules for generating code

- Use semantic tokens only (bg, surface, sunken, border, fg, fg-muted, fg-subtle, ink, accent, success, warning, danger). Never raw hex or palette steps like blue-500.
- Shadows only from the set: shadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlay.
- Numbers use tabular-nums. Dark mode is the `dark` class on <html>; components never branch on theme.

## Dependencies

- Built from: [checkbox](https://ui.minidev.pro/docs/checkbox/md), [select](https://ui.minidev.pro/docs/select/md)

## Related

- [Data Table](https://ui.minidev.pro/docs/data-table/md): React data table with sortable columns, row selection, a floating bulk actions bar, hover row actions, sticky header, three densities and skeleton loading.
- [Inline Cell Edit](https://ui.minidev.pro/docs/inline-cell-edit/md): Click to edit table cell text: the value turns into an input on click, saves on Enter or blur and cancels on Escape. Built for editable React data grids.
- [Sql Result Table](https://ui.minidev.pro/docs/sql-result-table/md): SQL query result table with uppercase column headers, monospace cells and horizontal scroll for wide results. Built for database consoles and admin tools.
- [Audit Filter Bar](https://ui.minidev.pro/docs/audit-filter-bar/md): Filter toolbar for audit logs combining a search field, actor filter chips for all, admins or system, and a date range picker in one wrapping row.
- [Audit Log Entry](https://ui.minidev.pro/docs/audit-log-entry/md): Single audit log line: actor avatar, actor name, muted action text and the affected target, with a relative timestamp underneath. Stacks into a trail.
- [Audit Trail](https://ui.minidev.pro/docs/audit-trail/md): Bordered audit trail in React that renders a list of actor, action, target and time records as stacked log entries. Useful for security and admin history pages.

---

All 557 components: https://ui.minidev.pro/llms.txt (full text: https://ui.minidev.pro/llms-full.txt).
