Data Grid

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add data-grid

Usage#

Pass columns and rows, and take the next rows back in onRowsChange. DataGridViewport is the scrolling grid and needs a height; DataGridStatusBar is optional. For a table people read rather than edit, use Data Table.

Anatomy#

import { DataGrid, DataGridViewport, DataGridStatusBar } from "@/components/ui/data-grid"

<DataGrid columns={columns} rows={rows} onRowsChange={setRows}>
  <DataGridViewport />
  <DataGridStatusBar />
</DataGrid>

Column types#

The type picks the editor and how a value reads, sorts, copies and pastes. Select a cell and press Enter to edit it.

• text: an input in the cell.
• number and currency: right-aligned in tabular figures; pasted text like €1,240.50 reads as 1240.5.
• select: a badge; Enter opens the options, typing filters them.
• date: Enter opens the calendar; typing a date also works. Stored as YYYY-MM-DD.
• checkbox: Space or a click toggles it in place.
• A column with value is computed and read-only, like Value here.

Keyboard#

Spreadsheet keys, with Ctrl on Windows and Cmd on a Mac.

Row numbers and gridlines#

rowNumbers adds a frozen number column; click a number to select the row. gridlines="all" keeps the column rules on at rest, for finance sheets.

Validation#

Return a message from validate to reject a value: the editor stays open, shakes once and shows the message under the cell. A value already in the data that fails shows a corner mark. Try a letter or a negative number in Stock.

Saving changes#

onRowsChange fires once per action with patches, so a paste of 200 cells is one call and one undo step. Send the patches to your server instead of diffing the rows.

Adding rows and columns#

onAddRow shows a New row row at the end and moves to it; onAddColumn shows a + at the end of the header. The grid never invents data: you append it.

Large data#

Only the rows in view are mounted, so ten thousand rows scroll and select like twelve. Ctrl+End jumps to the last cell; Ctrl+Shift+End selects to it and the status bar sums the lot.

Read-only#

readOnly keeps selection, copy and the status bar, and writes nothing. Pair it with gridlines="rows" and the comfortable density for a report.

API reference#

FAQ#