DataGrid

When to useLink to "When to use"

• Query results and table data: many rows, many columns, which people scan, sort, resize, select and copy.

Use something else when:

• the data is a few dozen rows people read rather than work through: Table, a semantic table with row checkboxes
• rows have no columns: VirtualList
• cells are edited: not yet (inline editing, column reorder and a filter row come later)

UsageLink to "Usage"

import { DataGrid, type DataGridColumn } from "@arshad-shah/cynosure";

const columns: DataGridColumn<Row>[] = fields.map((field) => ({
  key: field.name,
  header: field.name,
  sortable: true,
  resizable: true,
  minWidth: 80,
  align: field.numeric ? "end" : "start",
  cell: (row) => format(row[field.name]),
  cellKind: (row) => (row[field.name] === null ? "null" : field.numeric ? "number" : undefined),
}));

<DataGrid label="Results" columns={columns} rows={rows} getRowId={(row) => row.id} size="sm" />

Columns are width CSS pixels wide (default 160). cell formats a value for display (default: the value as text, objects as JSON); value is the raw value that sorting compares and copying writes (default row[key]). Set the grid's height with style={{ blockSize: … }} or the height token.

SortingLink to "Sorting"

A sortable column's header is a button (a SortButton filling the header cell): ascending, descending, then unsorted. The sort is a TableSort ({ key, direction }), the same as Table's. Numbers compare as numbers, text in the locale's order, and empty values go last either way. Control it with sort and onSortChange; with manualSort you sort the rows (on a server) and the grid only shows and reports the sort.

Selection and copyingLink to "Selection and copying"

selectionMode is "none" (default), "row", "cell" or "range". Rows are selected (ids, as Table's); cells are selectedRange, two corners ({ anchor, focus }, each { rowId, key }), so a selection survives sorting and loading more rows. Ctrl/Cmd+C copies the selection as tab-separated text: rows on lines, raw values, and a value holding a tab, a line break or a quote is quoted.

Text inside cells stays selectable: dragging selects text, and a copy with text selected copies that text, the browser's way. Cells are selected by clicking, Shift+click and the keyboard instead, so both work without a mode switch.

Full values, nulls and numbersLink to "Full values, nulls and numbers"

tooltip returns the full value of a cell (shown in a Tooltip on hover and keyboard focus only while the cell's text is cut short with an ellipsis, and not read to screen readers, since the cell's text already holds it), or nothing. cellKind says what a cell holds: "null" is muted and italic, "number" takes the number colour token. cellTone colours a cell with a tone (accent, neutral, danger, success, warning, info), over the kind's colour. size="sm" is dense: 28px rows under a 32px header.

Load more, or pagesLink to "Load more, or pages"

onEndReached is called once the last rows come into view, once per row count: append the next rows. For pages, put a Pagination under the grid and give the grid one page of rows; paging is not built in.

const [page, setPage] = useState(1);
<DataGrid label="Results" columns={columns} rows={rows.slice((page - 1) * 50, page * 50)} getRowId={(r) => r.id} />
<Pagination count={pageCount(rows.length, 50)} page={page} onChange={setPage} />

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

An APG grid (role="grid" with rows, column headers and cells) with one tab stop. aria-rowcount, aria-colcount and each row's and cell's index count every row and column, rendered or not. The focused cell is scrolled into view below the sticky header, and stays rendered while it is scrolled away.

Clicking a cell selects it (or its row); Ctrl/Cmd+click toggles a row; Shift+click extends. onRowClick reports every click or tap on a row. A resizable column's edge is dragged with a mouse, pen or finger; Escape cancels the drag. In right-to-left text the first column is on the right and the edge on a column's left.

TouchLink to "Touch"

A finger scrolls the grid in both directions and a tap acts as a click. Rows and the header are at least 44px tall on a coarse pointer, and a column's edge has a 44px hit area.

ThemingLink to "Theming"

RelatedLink to "Related"

• Table: a short, semantic table
• VirtualList: a long list without columns
• Pagination: pages under the grid
• Tooltip: the full value of a cut-short cell