React Data GridFill Handle

Enterprise

When working with cell selection, a Fill Handle allows you to run operations on cells as you adjust the size of the range.

Enabling the Fill Handle Copy Link

To enable the Fill Handle, set cellSelection.handle to { mode: 'fill' } in the gridOptions as shown below:

const cellSelection = useMemo(() => { 
	return {
        handle: {
            mode: 'fill',
        }
    };
}, []);

<AgGridReact cellSelection={cellSelection} />

The example below demonstrates the default behaviour with the minimal configuration above:

Default Fill Handle Copy Link

The default Fill Handle behaviour will be as close as possible to other spreadsheet applications. Note the following:

Single Cell Copy Link

  • When a single cell is selected and the range is increased, the value of that cell will be copied to the cells added to the range.
  • When a single cell containing a number value is selected and the range is increased while pressing the ⌥ Alt key, that value will be incremented (or decremented if dragging to the left or up) by the value of one until all new cells have been filled.

Multi Cell Copy Link

  • When a range of numbers is selected and that range is extended, the Grid will detect the linear progression of the selected items and fill the extra cells with calculated values.
  • When a range of strings or a mix of strings and numbers are selected and that range is extended, the range items will be copied in order until all new cells have been properly filled.
  • When a range of numbers is selected and the range is increased while pressing the ⌥ Alt key, the behaviour will be the same as when a range of strings or mixed values is selected.

Range Reduction Copy Link

  • When reducing the size of the range, cells that are no longer part of the range will be cleared (set to null). If your column uses a valueParser, it will receive an empty string ('') as the new value.

Preventing Range Reduction Copy Link

Reducing a range selection with the Fill Handle will clear cell contents by default, as can be observed in the cell reduction example above.

If this behaviour for decreasing selection needs to be prevented, the flag cellSelection.handle.suppressClearOnFillReduction should be set to true.

Fill Handle Axis Copy Link

By default, the Fill Handle can be dragged horizontally or vertically. If you wish to restrict the permitted direction of dragging to either horizontal or vertical, set cellSelection.handle.direction to either x for horizontal or y for vertical.

const cellSelection = useMemo(() => { 
	return {
        handle: {
            mode: 'fill',
            direction: 'x', // Fill Handle can only be dragged horizontally
        }
    };
}, []);

<AgGridReact cellSelection={cellSelection} />

Fill Handle Events Copy Link

When using the fill handle the grid will fire the fillStart event before it starts filling cells and the fillEnd event when all cells have been filled. See the Custom User Function example below for an example of using these events.

fillStartCopy Link
FillStartEvent
Fill operation has started.
fillEndCopy Link
FillEndEvent
Fill operation has ended.

Custom User Function Copy Link

Often there is a need to use a custom method to fill values instead of simply copying values or increasing number values using linear progression. In these scenarios, the cellSelection.handle.setFillValue callback should be used.

const [columnDefs, setColumnDefs] = useState([
    { field: 'country' },
    { field: 'year' },
    { field: 'sport' },
    { field: 'total' }
]);
const cellSelection = useMemo(() => { 
	return {
        handle: {
            mode: 'fill',
            setFillValue: (params) => 'Custom Fill Value',
        }
    };
}, []);

<AgGridReact
    columnDefs={columnDefs}
    cellSelection={cellSelection}
/>

FillOperationParams Copy Link

Properties available on the FillOperationParams<TData = any, TContext = any> interface.

The mouse event for the fill operation.
valuesCopy Link
any[]
The values that have been processed by the fill operation.
The RowNode of the current cell being changed.
The Column of the current cell being changed.
initialValuesCopy Link
any[]
The values that were present before processing started.
initialNonAggregatedValuesCopy Link
any[]
The values that were present before processing, without the aggregation function.
initialFormattedValuesCopy Link
any[]
The values that were present before processing, after being formatted by their value formatter
currentIndexCopy Link
number
The index of the current processed value.
currentCellValueCopy Link
any
The value of the cell being currently processed by the Fill Operation.
directionCopy Link
'up' | 'down' | 'left' | 'right'
The direction of the Fill Operation.
The grid api.
contextCopy Link
TContext
Application context as set on gridOptions.context.

If a setFillValue callback is provided, the fill handle will always run it. If the current values are not relevant to the setFillValue function that was provided, false should be returned to allow the grid to process the values as it normally would.

The example below will use the custom setFillValue for the Day of the week column, but it will use the default operation for any other column.

Skipping Columns in the Fill Operation Copy Link

The example below will use the custom setFillValue to prevent values in the Country column from being altered by the Fill Handle.

When the setFillValue function returns params.currentCellValue that value is not added to the params.values list. This allows users to skip any cells in the Fill Handle operation.

Non editable cells will not be changed by the Fill Handle, so there is no need to add custom logic to skip columns that aren't editable.

Read Only Edit Copy Link

When the grid is in Read Only Edit mode the Fill Handle will not update the data inside the grid. Instead the grid fires cellEditRequest events allowing the application to process the update request.

cellEditRequestCopy Link
CellEditRequestEvent
Value has changed after editing. Only fires when readOnlyEdit=true.

The example below will show how to update cell value combining the Fill Handle with readOnlyEdit=true.

Suppressing the Fill Handle Copy Link

The Fill Handle can be disabled on a per column basis by setting the column definition property suppressFillHandle to true.

In the example below, please note that the Fill Handle is disabled in the Country and Date columns.

API Reference Copy Link

Here you can find a full list of configuration options available when the handle options are in 'fill' mode.

'fill'
'fill'
suppressClearOnFillReductionCopy Link
boolean
default: false
Set this to true to prevent cell values from being cleared when the Range Selection is reduced by the Fill Handle.
directionCopy Link
'x' | 'y' | 'xy'
default: 'xy'
Set to 'x' to force the fill handle direction to horizontal, or set to 'y' to force the fill handle direction to vertical.
setFillValueCopy Link
Function
Callback to fill values instead of simply copying values or increasing number values using linear progression.

Next up Copy Link

Continue to the next section to see the API Reference for cell selection.