Plan a cell type
Step 2 of 3
Decide the stored value, the text form, the empty value, and the editor of a custom cell type, then write the type as one typed object.
Before you start, pick a code route and choose a custom cell type. One cell type object serves the display, the editor, the clipboard, the sort, the search, and the filter. A wrong choice reaches every feature, so decide before you write.
Decide five things
- The stored value. Store a serializable primitive, such as a number or an ISO date string. Do not store a class instance.
- The text form.
toTextturns the value into plain text.fromTextparses typed, pasted, and imported text back into a value. For every value,fromText(toText(value))returns the same value. IffromTextcannot parse the text, callrejectText(): the cell keeps its value. ReturnclearValue()only to empty the cell on purpose. - The empty value.
isEmptysays which values count as empty. In the rating type below,0is a real rating, soisEmptyreturnstruefornullonly. - The display.
Celldraws the value. If print, column autosize, and the header filter need formatted text, addtoDisplayText. - The editor. Build a text editor on
useCellEditor. It owns the draft, the focus, and the commit on Enter and on blur.
A cell type needs six members: Cell, Editor, toText, fromText, clearValue, and isEmpty. Every other member is optional. If the default sort does not fit your value, add compare.
Write the plan as a type
This type stores a rating from 0 to the max option, or null:
"use client";
import {
defineCellType,
rejectText,
useCellEditor,
type CellEditorProps,
type CellRenderProps,
} from "@/components/data-grid/data-grid";
import { Input } from "@/components/ui/input";
declare module "@/components/data-grid/types" {
interface GridCellTypes {
rating: { value: number | null; options: { max: number } };
}
}
type Value = number | null;
type Options = { max: number };
function parseRating(text: string, options?: Options): Value {
const rating = Math.round(Number(text));
const max = options?.max ?? 5;
const invalid = text.trim() === "" || Number.isNaN(rating);
return invalid || rating < 0 || rating > max ? null : rating;
}
function Cell({ value, options }: CellRenderProps<unknown, Value, Options>) {
if (value === null) return null;
return <span>{`${value} / ${options?.max ?? 5}`}</span>;
}
function Editor(props: CellEditorProps<unknown, Value, Options>) {
const { ref, ...bindings } = useCellEditor(props, {
toDraft: (value) => (value === null ? "" : String(value)),
toValue: (draft) => ratingCellType.fromText(draft, props.options),
});
return <Input ref={ref} {...bindings} className="h-full text-end" />;
}
export const ratingCellType = defineCellType("rating", {
Cell,
Editor,
toText: (value) => (value === null ? "" : String(value)),
fromText: (text, options) =>
text.trim() === "" ? null : (parseRating(text, options) ?? rejectText()),
clearValue: () => null,
isEmpty: (value) => value === null,
align: "end",
});Register the type under the name that a column uses in type, with cellTypes={{ rating: ratingCellType }}. A column then sets type: "rating" and options: { max: 10 }.
Result
You hold a typed plan with every required member filled. With max: 10, a paste of 7 stores 7, a paste of abc leaves the cell unchanged, and a copy gives the plain number.
Next: Plan a plugin, or write the type in Write a cell type.