gridcn2.0.0
Clipboard and undo

Fill handle

Drag the corner of a selection to copy it or continue a number or text series, or fill down and right from the keyboard.

Typing the same value into many cells is slow. The fill handle is the small square at the bottom-right corner of a selection. Drag it up, down, left, or right to extend the selection. The grid fills the new cells from the source cells. useDataGridFill adds the handle and the keyboard fill commands.

Select a cell or range in a filled column and drag the small handle at its corner down: Count (1, 2, 3), Code (001, 002) and Item (Item 1, Item 2) extrapolate their series, Label (plain text) just tiles. Hold Alt/Option while dragging to force a plain copy, or select a filled range and press Ctrl/Cmd+D (fill down) / Ctrl/Cmd+R (fill right) instead of dragging.

Count
Code
Item
Label
1
001
Item 1
West
2
002
Item 2
West
3
003
Item 3
West
pnpm dlx shadcn@latest add @gridcn/data-grid-fill

Fill setup

The hook returns one plugin. Pass it to the grid through plugins:

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { useDataGridFill } from "@/components/data-grid-fill/data-grid-fill";

type Row = { id: string; name: string };

const data: Row[] = [{ id: "1", name: "Item 1" }];
const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

function MyGrid() {
  const { plugin } = useDataGridFill();

  return <DataGrid defaultData={data} columns={columns} plugins={[plugin]} />;
}

Copy and series

The drag snaps to the axis that you move further on. Press Escape during a drag to cancel it. If the window loses focus or the browser cancels the pointer, the drag ends and fills nothing. By default, the fill repeats the source cells over the target. A single cell repeats, and a two-row source repeats every two rows.

If the source cells form a series, the fill continues the series instead:

  • Arithmetic runs. 1, 2, 3 continues as 4, 5, 6. 10, 20, 30 continues as 40, 50, 60. Decimal steps work too: 0.5, 1 continues as 1.5, 2.0.
  • Zero-padded numbers. 001, 002 continues as 003, 004 and keeps the width.
  • Text with a trailing number. Item 1, Item 2 continues as Item 3, Item 4.

A series needs two source cells, because one value has no step. An integer with more than 15 digits is an identifier, so the fill copies it. Dates have no series of their own: the fill copies ISO dates such as 2026-01-30, 2026-01-31. A custom detector below continues real dates.

A vertical fill checks the series per column. A horizontal fill checks it per row. The series applies to a column or row only when the fromText of each target cell reads every generated value. A select column reads a value that names a choice. A date column reads a valid date inside min and max, so it rejects a date after max. If fromText rejects one generated value, the fill repeats the source in that column or row instead. A value that validate rejects is reported and not copied:

  • A vertical fill repeats the stored source values of the column. With the choices Tier 1 to Tier 3, the source Tier 1, Tier 2 fills three cells with Tier 1, Tier 2, Tier 1, because Tier 4 is no choice.
  • A horizontal fill reads the text of each source cell with the fromText of the target column. A row that fails repeats the source text. A target column that lacks the label keeps the cell value and reports it to onValidationError with source "fill", as a paste does.

After a fill commits, the written cells play a short fade pulse. The pulse plays only for cells in the viewport.

Forcing a plain copy

To force a plain copy, even over a series, hold Alt (Option on Mac) at the release of the drag.

Keyboard fill

The handle is pointer-only and hidden from screen readers. These keys fill from the keyboard:

  • Ctrl/Cmd+D fills down. It copies the top row of the selection into every row below it.
  • Ctrl/Cmd+R fills right. It copies the left column into every column to its right.

Both keys use the same copy and series logic as a drag. The source of each key is one row or one column, so the built-in detector always copies. The add-on binds both keys. In a writable grid, outside an edit, Ctrl+R fills right and the page does not reload. The fillDown and fillRight flags of the global shortcuts extend them to the whole window. Without this add-on, the grid leaves both keys to the browser. See Add-on actions.

Touch

After a touch selection, the handle is hidden because the selection handle uses the same corner. With the context menu add-on, the cell menu shows Fill down and Fill right instead. They run the same commands.

Skipped cells

A fill writes only to cells that accept a write:

  • A read-only grid never fills. The handle is hidden and both commands do nothing.
  • In a writable grid, a fill skips the read-only cells and fills the others. A column or a row function can mark a cell read-only. It shows no error, like a paste over a read-only cell.
  • A fill commits as one change. When a column validator rejects a value, the grid reports the rejected cells through onValidationError with source "fill" and writes the rest.

Server mode

A fill works on the rows that the grid holds in memory. It never asks the server for rows. Fill follows the displayed order, so a sorted grid fills in the order that you see.

A fill is one change. The grid applies it, then calls onDataChange and onSave with the same change. change.source is "fill". change.ops holds one update operation per written row, and each operation lists the changed cells. Your onSave sends these updates to the server.

A refused fill reverts through onDataChange with source "rollback". Handle refused saves owns the onSave contract.

In scroll mode, a fill target can cover rows that are not loaded. The grid fills the loaded rows, skips the others, and still expands the selection over the whole target. A development warning gives the number of skipped rows. When the fill must reach them, load the rows first. See Load rows while scrolling.

Data modes owns the detail for every mode.

Options

Pass these options to useDataGridFill. Every option is optional:

PropTypeDefault
disabledbooleanfalse
processFill(ctx: ProcessFillContext) => string[][] | falsenone
detectSeries(values: readonly string[]) => SeriesDescriptor | nullbuilt-in detector

disabled

disabled hides the handle and leaves Ctrl/Cmd+D and Ctrl/Cmd+R to the browser.

processFill

processFill runs on drag release and on both keyboard commands, before the grid applies the fill. It returns the text grid to write, or false to cancel the fill. The grid parses the returned text with the fromText of each column and validates it, like a paste. After false, the grid writes nothing and the selection does not expand.

A promise holds the fill as the processFill gate. When it resolves, the selection expands and the cells write. A newer fill, readOnly, or a changed row set drops the answer. useDataGridGatePending and gateTimeoutMs cover the gate.

This option cancels large fills:

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import {
  useDataGridFill,
  type ProcessFillContext,
} from "@/components/data-grid-fill/data-grid-fill";

type Row = { id: string; name: string };

const rows: Row[] = [{ id: "1", name: "Item 1" }];
const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

function processFill({ target, cells }: ProcessFillContext) {
  return target.height > 100 ? false : cells;
}

function MyGrid() {
  const { plugin } = useDataGridFill({ processFill });
  return <DataGrid defaultData={rows} columns={columns} plugins={[plugin]} />;
}

ProcessFillContext also carries source, the rectangle of the source cells. cells is the text grid for the target before parsing. signal aborts when a newer fill supersedes this one. For Ctrl/Cmd+D, source is the top row. For Ctrl/Cmd+R, it is the left column. target covers the new cells only. onDataChange with the "fill" source reports each fill that the grid writes.

detectSeries

detectSeries replaces the built-in detector. It receives the source cell texts along the fill axis, in source order. It returns a SeriesDescriptor with an extrapolate(index) function, or null to copy. index counts from the first source cell: 0 is the first source cell, and an up or left fill passes negative indexes. This detector adds date series:

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import {
  useDataGridFill,
  type SeriesDescriptor,
} from "@/components/data-grid-fill/data-grid-fill";

type Row = { id: string; name: string };

const rows: Row[] = [{ id: "1", name: "2026-01-30" }];
const columns = defineColumns<Row>()([
  { id: "name", header: "Date", accessorKey: "name" },
]);

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;

const detectDates = (values: readonly string[]): SeriesDescriptor | null => {
  if (values.length < 2 || !values.every((v) => ISO_DATE.test(v))) return null;
  const times = values.map((v) => Date.parse(v));
  if (times.some(Number.isNaN)) return null;
  const step = times[1]! - times[0]!;
  for (let i = 2; i < times.length; i += 1) {
    if (times[i]! - times[i - 1]! !== step) return null;
  }
  return {
    extrapolate: (index) =>
      new Date(times[0]! + step * index).toISOString().slice(0, 10),
  };
};

function MyGrid() {
  const { plugin } = useDataGridFill({ detectSeries: detectDates });
  return <DataGrid defaultData={rows} columns={columns} plugins={[plugin]} />;
}

Result: the source cells 2026-01-30, 2026-01-31 continue as 2026-02-01, 2026-02-02.

To keep the built-in series, call the exported detectSeries for every input that your detector rejects:

import { detectSeries } from "@/components/data-grid-fill/data-grid-fill";

const detectBoth = (values: readonly string[]) =>
  detectDates(values) ?? detectSeries(values);

On this page