Fill handle options
Look up the options of useDataGridFill, the ProcessFillContext that processFill receives, and the SeriesDescriptor that a custom detectSeries returns.
useDataGridFill adds the fill handle and the fill down and fill right commands. It takes one options object and returns UseDataGridFillResult, { plugin }. Pass plugin in the plugins prop of the grid. Fill handle explains the behavior.
This sample sets all three options:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import {
useDataGridFill,
type ProcessFillContext,
type SeriesDescriptor,
} from "@/components/data-grid-fill/data-grid-fill";
type Row = { id: string; name: string };
const data: Row[] = Array.from({ length: 200 }, (_, i) => ({
id: String(i),
name: String(i),
}));
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
const everySecond = (values: readonly string[]): SeriesDescriptor | null =>
values.length < 2 ? null : { extrapolate: (index) => `${index * 2}` };
export function FillGrid() {
const { plugin } = useDataGridFill({
disabled: false,
processFill: ({ target, cells }: ProcessFillContext) =>
target.height > 100 ? false : cells,
detectSeries: everySecond,
});
return <DataGrid defaultData={data} columns={columns} plugins={[plugin]} />;
}The gate cancels a fill over more than 100 rows. When a source column has two or more cells, a fill down gives each new cell twice its distance from the first source cell. A two-cell source gives 4 and 6.
UseDataGridFillOptions
Every option is optional.
Prop
Type
ProcessFillContext
processFill receives one ProcessFillContext object before the grid writes. It returns a text grid, or false to cancel the fill. A promise holds the fill as the processFill gate until it resolves, and signal aborts when a newer fill supersedes it. A text grid is a string[][] with one row of texts per row of target.
processFill runs on:
- the release of a drag
- the fill down command (Mod+D)
- the fill right command (Mod+R)
It does not run on a cancelled drag. It does not run on a keyboard command over one row (fill down) or one column (fill right), because that fills nothing.
Prop
Type
source and target are rectangles in view index. target covers the new cells only. For Mod+D, source is the top row of the selection and target is the rest of it. For Mod+R, source is the left column.
cells holds one text per cell of target, before parsing and validation. A returned grid replaces it. A cell that the returned grid does not cover is not written. cells also holds texts for the cells that the grid skips: read-only cells and, in scroll mode, rows that are not loaded yet.
SeriesDescriptor
A detectSeries function returns a SeriesDescriptor, or null to copy the source cells.
Prop
Type
detectSeries receives the source cell texts along the fill axis, in source order. A vertical fill calls it once per source column. A horizontal fill calls it once per source row. If you hold Alt (Option on Mac) at the release of a drag, the fill copies and calls no detector. The index that extrapolate receives is 0 for the first source cell. A fill up or left passes negative indexes. The add-on exports the built-in detector as detectSeries, so a custom detector can fall back to it.
Related
- Fill handle: the drag, the series rules, and the keyboard commands.
- Undo and redo options: the history that records a fill.