Built-in cell types
Pick a built-in cell type for each column and set its options, such as number format, date picker, select choices, links, and long text.
A cell type decides how a column shows a value and which editor it opens. It also turns copied text back into a value. gridcn ships seven: text, number, checkbox, select, date, url, and longText. Set type on the column and pass the type's settings in options. A column without type shows and edits its values as text. No built-in type holds a time of day or a list of values. For those, store text and check it with validate, or write a cell type.
The demo opens the two date editors. Press Enter on a date cell. The cell types example shows every type:
Press Enter on a date cell. The "Calendar at edit start" column opens the calendar at once. The "Calendar button" column shows a typed input with a calendar button, and the calendar opens when you press the button.
Types and options
| Name | Value | Options |
|---|---|---|
text | string | None |
number | number | null | min, max, step, decimals, format, locale |
checkbox | boolean | None |
select | string | null | choices |
date | ISO yyyy-mm-dd string or null | min, max, displayFormat, locale, calendarTrigger |
url | string | null | label |
longText | string | maxLength, placeholder |
Every type follows the same text pipeline, which Cell type model describes.
Align a column changes the alignment of every type except checkbox. number and date cells align to the end, checkbox cells center, and the other types align to the start.
This grid uses five of the types:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Person = {
id: string;
name: string;
age: number | null;
active: boolean;
role: string | null;
joined: string | null;
};
const columns = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name", type: "text" },
{
id: "age",
header: "Age",
accessorKey: "age",
type: "number",
options: { min: 0, max: 120 },
},
{ id: "active", header: "Active", accessorKey: "active", type: "checkbox" },
{
id: "role",
header: "Role",
accessorKey: "role",
type: "select",
options: {
choices: [
{ value: "admin", label: "Admin" },
{ value: "user", label: "User" },
],
},
},
{ id: "joined", header: "Joined", accessorKey: "joined", type: "date" },
]);
export function People({ people }: { people: Person[] }) {
return <DataGrid defaultData={people} columns={columns} />;
}A date cell turns text that names no real day into an empty value. A number cell rejects text that is not a number: see Number formatting. A column validate can refuse the empty value. See Validation.
Number formatting
The type rounds to decimals and clamps to min and max, in the editor and on paste. In the editor, ArrowUp and ArrowDown step the draft by step (default 1) within min and max. With decimals set, the step is never smaller than the last decimal place.
Paste and parse follow these rules:
- The clamp runs before a column
validate, so a typed, pasted, or filled value outsideminandmaxnever reaches it. - A value that code writes with
updateCellsis not clamped. - A value that
processCellFromClipboard(paste) orprocessCellFromText(import) returns skips the clamp, unless the hook returns the result of thefromTextit receives. 1,234.50,1,234,567, and1.234,50read as grouped numbers.- A single comma that is not followed by three digits is the decimal point, so
1,5stores1.5. 1,234can mean1234or1.234, so the type rejects it. The type also rejects text that is not a number.- A rejected paste or fill leaves the cell unchanged. A rejected typed value keeps the editor open.
To read other formats, set processCellFromClipboard for paste, or processCellFromText for import.
format takes Intl.NumberFormatOptions. locale sets the language of format. Alone, it groups the digits in that language. It defaults to the grid locale, or "en-US" without one. format and locale change only the display.
The editor, copy, paste, sort, and export keep the plain number, so a stored 0.25 under style: "percent" shows 25% and edits as 0.25. When the format sets no fraction digits, decimals sets both the minimum and the maximum. A format that Intl rejects, such as style: "currency" without a currency, shows the plain number and logs one development warning per locale and format.
This column shows a price as US dollars:
import { defineColumns } from "@/components/data-grid/data-grid";
type Product = { id: string; price: number | null };
const columns = defineColumns<Product>()([
{
id: "price",
header: "Price",
accessorKey: "price",
type: "number",
options: { format: { style: "currency", currency: "USD" } },
},
]);Date
The stored value and the clipboard text are always ISO yyyy-mm-dd. displayFormat takes Intl.DateTimeFormatOptions. locale sets the language of displayFormat and defaults to the locale of the grid. A column with no displayFormat and no locale shows the ISO text. Alone, locale shows the medium date style. displayFormat and locale change only the display. A locale or timeZone that Intl rejects, such as "de_DE", shows the ISO text and logs one development warning per locale and format.
The editor is a popover with a typed input and a calendar. The input accepts ISO text or any text that Date parses. A text that names no real calendar day or falls outside min and max becomes an empty value. Enter commits the typed text and moves down. Picking a day commits and stays in place.
calendarTrigger shows the editor as a typed input with a calendar button. The calendar stays closed until the button opens it, and the button toggles it. The button label comes from labels.grid.dateCalendarAriaLabel. A column without calendarTrigger opens the calendar at the start of the edit.
This column formats the display and uses the calendar button:
import { defineColumns } from "@/components/data-grid/data-grid";
type Task = { id: string; due: string | null };
const columns = defineColumns<Task>()([
{
id: "due",
header: "Due",
accessorKey: "due",
type: "date",
options: {
displayFormat: { year: "numeric", month: "short", day: "numeric" },
locale: "en-US",
calendarTrigger: true,
},
},
]);Select and checkbox
A select cell stores the choice value and shows its label. A string choice is its own value and label. Display, search, sort, and copy use the label. A filter matches the stored choice value. A stored value without a choice shows as it is.
Paste accepts a choice value, or a label in any letter case. Other text leaves the cell unchanged, and the grid reports it to onValidationError. Blank text empties the cell. Picking a choice commits at once.
The grid caches lookups for each choices array. Pass a new array to change the choices, and never change the array in place.
A checkbox cell toggles in place and has no editor. A locked cell does not toggle. A toggle asks onBeforeEditStart. If validate rejects the new value, onValidationError reports it with source: "edit". Copy writes true or false. Paste reads true, 1, yes, x, and on in any letter case as true, and any other text as false.
URL links
A url cell stores the URL as text and shows it as a link. The link opens in a new tab without a referrer and is not a tab stop. A click on the link selects the cell. Ctrl+click (Cmd+click on macOS) opens the link, and a middle-click opens it through the browser. Alt+Enter (the openLink action) opens the link of the active cell, also in a read-only grid.
options.label maps the stored URL to the link text. Copy and export keep the URL.
Only http, https, and mailto render as links
No setting widens the allow-list. A javascript: or data: value, a relative value, and a URL longer
than 2,048 characters render as plain text, and openLink does not open them.
Long text
A longText cell stores multi-line text as it is. The cell shows one line: the first 500 characters, with line breaks as spaces. The editor is a popover with a textarea that opens over the cell.
The built-in cell types do not wrap text. A cell shows one line that ends with an ellipsis when the text is too long. To show more, set rowHeight to a larger value and return an element with whitespace-normal and line-clamp-2 from renderCell. See Density and small screens and Display override.
Enter commits and moves down. Shift+Enter and Alt+Enter insert a line break. Escape cancels, and a click outside commits the draft.
maxLength defaults to 100,000. The textarea enforces it while typing. Paste, fill, and import reject text over maxLength with a message. A column validate runs after this check.
Server mode
In server mode, filters and sorts send the stored value: the choice value, the plain number, and the ISO date. format and displayFormat stay in the browser.
Related
- Editable columns: the keys each editor reads.
- Validation: reject values by column.
- Cell type model: the value pipeline behind every type.
- Write a cell type: add a type of your own.
- Cell type contract: the members each type implements.