gridcn2.0.0
Custom code path

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

  1. The stored value. Store a serializable primitive, such as a number or an ISO date string. Do not store a class instance.
  2. The text form. toText turns the value into plain text. fromText parses typed, pasted, and imported text back into a value. For every value, fromText(toText(value)) returns the same value. If fromText cannot parse the text, call rejectText(): the cell keeps its value. Return clearValue() only to empty the cell on purpose.
  3. The empty value. isEmpty says which values count as empty. In the rating type below, 0 is a real rating, so isEmpty returns true for null only.
  4. The display. Cell draws the value. If print, column autosize, and the header filter need formatted text, add toDisplayText.
  5. 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.

On this page