Skip to main content

useFillHandle

Drag the small square at the bottom-right of a selection and the source block is tiled over the cells you drag across, down or sideways (one axis at a time, like Excel). The hook tracks the drag target, exposes the extended fillRange for highlighting, and on commit calls core's applyFillValues to turn the fill into ICellValueChangedEvent objects. You apply them to your data. Column editable, type, and valueParser are honored, so a text value will not land in a numeric column.

Live demo​

Select cells, then drag the green square at the range's bottom-right corner down or across
Live

Quick example​

import { useHeadlessGrid, useRangeSelection, useFillHandle } from '@alaarab/ogrid-react';

const grid = useHeadlessGrid({ columns, data, getRowId });
const range = useRangeSelection({ rowCount: grid.rows.length, colCount: grid.columns.length });
const fill = useFillHandle({
rangeSelection: range,
rows: grid.rows,
columns: grid.columns,
onFillCells: (events) => setData((prev) => events.reduce(applyOneEvent, prev)),
});

// Commit even when the mouse is released outside the table.
useEffect(() => {
if (!fill.isFilling) return;
window.addEventListener('mouseup', fill.commitFill);
return () => window.removeEventListener('mouseup', fill.commitFill);
}, [fill.isFilling, fill.commitFill]);

// Inside the cell loop:
const r = range.range;
<td
onMouseEnter={(e) => (fill.isFilling ? fill.updateFill(rowIdx, colIdx) : e.buttons === 1 && range.extendRange(rowIdx, colIdx))}
data-fill={fill.isFilling && fill.isInFillRange(rowIdx, colIdx)}
>
{value}
{r && rowIdx === r.endRow && colIdx === r.endCol && (
<span className="fill-handle" onMouseDown={(e) => { e.stopPropagation(); fill.startFill(); }} />
)}
</td>

Parameters​

UseFillHandleParams<T>

ParamTypeDescription
rangeSelectionUseRangeSelectionResultThe source range. Fill always extends from rangeSelection.range.
rowsT[]The rows you render (grid.rows). Event rowIndex values index into this array.
columnsIColumnDef<T>[]Visible columns, in render order.
onFillCells(events: ICellValueChangedEvent<T>[]) => voidCalled once on commit with every accepted cell. Not called when nothing changed.
fillSeriesbooleanContinue detected series instead of copying (default true).

Returns​

UseFillHandleResult

FieldTypeDescription
fillTargetCellCoord | nullCell the handle is being dragged toward.
isFillingbooleanfillTarget !== null.
fillRangeISelectionRange | nullSource range extended toward the target along one axis (see behavior notes); equals the source range when idle or when the target is inside it.
startFill() => voidBegin a drag from the range's bottom-right cell. No-op without a range.
updateFill(row, col) => voidMove the target. No-op when not filling.
commitFill(event?: { ctrlKey?, metaKey? }) => voidCompute events, call onFillCells, select the filled range, end the drag. Pass the mouse event: Ctrl/Cmd held flips copy and series.
autoFillDown(event?: { ctrlKey?, metaKey? }) => voidExcel's double-click on the fill handle: fill the range down to the end of the adjacent data column (left, else right).
cancelFill() => voidEnd the drag without changes.
isInFillRange(row, col) => booleanHit test against fillRange (includes the source cells).

Behavior notes​

  • Series are continued like Excel (1, 2 -> 3; Mon -> Tue; Item 1 -> Item 2; dates by day, or by month/year for two same-day dates); a single number and anything that is not a series is copied. Ctrl/Cmd at commit flips that, and fillSeries: false always copies. See Fill handle.

  • Tiling, not series. The source block repeats across the fill range at the same offset modulo the block size (Excel's behavior for a plain drag). Source cells are never overwritten. There is no 1, 2, 3 series detection.

  • One axis at a time, like Excel. The fill range is the source range extended toward the target along a single axis: whichever one the target is farther outside the source on, counted in cells (rows vs columns; an exact tie fills rows). Dragging diagonally therefore fills down or across, never both, and the highlight switches axis as the pointer moves. Dragging up or to the left fills in that direction too. A target inside the source range (including dragging back into it) leaves fillRange equal to the source, so commitFill is a no-op.

  • Releasing without moving is a no-op: when fillRange equals the source range, commitFill ends the drag and onFillCells is not called.

  • The filled range becomes the selection, as in Excel and <OGrid>: after a fill that extends the source, commitFill calls rangeSelection.setRange(fillRange). A no-op fill leaves the selection alone.

  • Validation per cell. Read-only cells are skipped, and each value runs through the target column's valueParser / built-in type parser; rejected cells are dropped from the event list.

  • Stop propagation on the handle. The handle sits inside a cell whose onMouseDown starts a new range; e.stopPropagation() keeps the source range intact.

  • Formula-aware fill (relative reference adjustment) is only available through <OGrid> with formulas enabled; the headless hook passes no formula options to applyFillValues.

See also​