gridcn2.0.0
Add-on optionsEditing cells

Lookup options

Look up the column options of the lookup cell type, the request that fetchOptions receives, the editor labels, and the stored value types.

A lookup column takes a LookupOptions object in its options field. You must pass fetchOptions. The other options have defaults. The editor, the stored value, and the clipboard rules are on Lookup cell.

TypeHolds
LookupOptionsThe column options of the cell type.
LookupFetchRequestThe argument of fetchOptions.
LookupLabelsThe text of the editor.
LookupOption, LookupValueOne option, and the value a cell stores.

This sample passes fetchOptions and no other option:

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import {
  lookupCellType,
  type LookupValue,
} from "@/components/data-grid-lookup/data-grid-lookup";

type Order = { id: string; customer: LookupValue };

const columns = defineColumns<Order>()([
  {
    id: "customer",
    header: "Customer",
    accessorKey: "customer",
    type: "lookup",
    options: {
      fetchOptions: async ({ query, signal }) => {
        const url = `/api/customers?q=${encodeURIComponent(query)}`;
        const res = await fetch(url, { signal });
        return res.json();
      },
    },
  },
]);

export function Orders({ orders }: { orders: Order[] }) {
  return (
    <DataGrid
      defaultData={orders}
      cellTypes={{ lookup: lookupCellType }}
      columns={columns}
    />
  );
}

LookupOptions

PropTypeDefaultDescription
fetchOptions(request: LookupFetchRequest<TData>) => Promise<readonly LookupOption[]>requiredResolves the options that match query.
debounceMsnumberthe grid's inputDebounceMsThe wait after the last keystroke before a request starts.
minQueryLengthnumber0The fewest typed characters that start a request. With 0, an opened editor loads the default list.
maxResultsnumber50The most options that the editor shows. The editor uses at most 200.
unresolvedPaste"reject" | "clear" | "keep""reject"A pasted or imported text that matches no known option. "reject" keeps the cell value and reports the text to onValidationError. "clear" empties the cell. "keep" stores { value: text, label: "" } with the trimmed text, which shows as unresolved.
labelsPartial<LookupLabels>EnglishThe text of the editor. Each field that you leave out stays English.

The cell type resolves a pasted label through a cache for each lookup column of a grid. An inline fetchOptions keeps the cache. The cache holds at most 5,000 labels and drops the oldest first.

The editor treats the answer of fetchOptions as untrusted input:

  • The editor reads an array only. Any other answer and a rejected promise show the error line with the Retry button.
  • If value is a non-empty text or a finite number and label is a text, the editor keeps the entry. A number value becomes text.
  • An empty label shows the value.
  • The editor drops a repeated value, cuts value and label at 256 characters, and keeps the first maxResults entries.

LookupFetchRequest

PropTypeDescription
querystringThe text that the user typed. "" asks for the default list. The search box holds at most 256 characters.
signalAbortSignalIf the user types again, closes the editor, or the cell unmounts, the signal aborts. Pass it to fetch.
rowTDataThe row that the user edits. A dependent lookup reads it, such as a city list for the country of the row. TData is the row type that you pass to LookupOptions<TData>. It defaults to unknown.
rowIdstringThe id of that row.
columnIdstringThe id of the lookup column.

The request does not repeat when a push changes the row during the edit.

The editor drops an answer that arrives after its signal aborted.

LookupLabels

PropTypeEnglish text
searchingstring"Searching…"
noResultsstring"No results"
errorstring"Could not load options"
retrystring"Retry"
typeMore(missing: number) => string"Type 2 more characters" for 2

typeMore receives the number of characters that minQueryLength still asks for.

LookupOption and LookupValue

LookupOption is { value: string; label: string }. value is the key that your server uses. label is the text that the grid shows, copies, sorts, searches, and filters.

LookupValue is the value that a cell stores: a LookupOption, a bare key string without a label, or null. A bare key, or an option with an empty label, shows in muted text with a data-unresolved attribute until the user picks an option.

Example with limits and labels

This sample asks for three characters before a search and sets every label in German:

import { DataGrid, type ColumnDef } from "@/components/data-grid/data-grid";
import {
  lookupCellType,
  type LookupOptions,
  type LookupValue,
} from "@/components/data-grid-lookup/data-grid-lookup";

const customerOptions: LookupOptions = {
  fetchOptions: async ({ query, signal }) => {
    const url = `/api/customers?q=${encodeURIComponent(query)}`;
    const res = await fetch(url, { signal });
    return res.json();
  },
  minQueryLength: 3,
  maxResults: 20,
  labels: {
    searching: "Suche…",
    noResults: "Keine Treffer",
    error: "Optionen konnten nicht geladen werden",
    retry: "Erneut versuchen",
    typeMore: (missing) => `Noch ${missing} Zeichen`,
  },
};

type Order = { id: string; customer: LookupValue };

const columns: ColumnDef<Order, unknown>[] = [
  {
    id: "customer",
    header: "Kunde",
    accessorKey: "customer",
    type: "lookup",
    options: customerOptions,
  },
];

export function Orders({ orders }: { orders: Order[] }) {
  return (
    <DataGrid
      defaultData={orders}
      cellTypes={{ lookup: lookupCellType }}
      columns={columns}
    />
  );
}

On this page