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.
| Type | Holds |
|---|---|
LookupOptions | The column options of the cell type. |
LookupFetchRequest | The argument of fetchOptions. |
LookupLabels | The text of the editor. |
LookupOption, LookupValue | One 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
| Prop | Type | Default | Description |
|---|---|---|---|
fetchOptions | (request: LookupFetchRequest<TData>) => Promise<readonly LookupOption[]> | required | Resolves the options that match query. |
debounceMs | number | the grid's inputDebounceMs | The wait after the last keystroke before a request starts. |
minQueryLength | number | 0 | The fewest typed characters that start a request. With 0, an opened editor loads the default list. |
maxResults | number | 50 | The 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. |
labels | Partial<LookupLabels> | English | The 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
valueis a non-empty text or a finite number andlabelis a text, the editor keeps the entry. A numbervaluebecomes text. - An empty
labelshows thevalue. - The editor drops a repeated
value, cutsvalueandlabelat 256 characters, and keeps the firstmaxResultsentries.
LookupFetchRequest
| Prop | Type | Description |
|---|---|---|
query | string | The text that the user typed. "" asks for the default list. The search box holds at most 256 characters. |
signal | AbortSignal | If the user types again, closes the editor, or the cell unmounts, the signal aborts. Pass it to fetch. |
row | TData | The 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. |
rowId | string | The id of that row. |
columnId | string | The 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
| Prop | Type | English text |
|---|---|---|
searching | string | "Searching…" |
noResults | string | "No results" |
error | string | "Could not load options" |
retry | string | "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}
/>
);
}Related
- Lookup cell: the editor keys, the stored value, and the clipboard rules.
- Cell type contract: the shape that
lookupCellTypeimplements. - Labels and i18n: the label groups of the grid.