Aggregation

The Aggregation plugin computes aggregate values for group rows by walking the group tree bottom-up. It supports built-in functions (sum, avg, count, min, max, first, last), custom aggregation functions, and automatic recomputation when grouping changes.

Installation

npm install @gridstorm/plugin-aggregation @gridstorm/plugin-grouping

The Aggregation plugin declares dependencies: ['grouping'] and requires the Grouping plugin to be installed.

Setup

import { createGrid } from '@gridstorm/core';
import { GroupingPlugin } from '@gridstorm/plugin-grouping';
import { AggregationPlugin } from '@gridstorm/plugin-aggregation';

const grid = createGrid({
  columns: [
    { colId: 'department', field: 'department', headerName: 'Department', rowGroup: true, rowGroupIndex: 0 },
    { colId: 'name', field: 'name', headerName: 'Name' },
    { colId: 'salary', field: 'salary', headerName: 'Salary', aggFunc: 'sum' },
    { colId: 'age', field: 'age', headerName: 'Age', aggFunc: 'avg' },
  ],
  rowData: [],
  plugins: [
    GroupingPlugin({ defaultExpanded: true }),
    AggregationPlugin({
      customAggFuncs: {
        median: ({ values }) => {
          const nums = values.filter((v) => v != null && !isNaN(Number(v))).map(Number).sort((a, b) => a - b);
          if (nums.length === 0) return null;
          const mid = Math.floor(nums.length / 2);
          return nums.length % 2 === 0 ? (nums[mid - 1] + nums[mid]) / 2 : nums[mid];
        },
      },
    }),
  ],
});

Live example: Aggregation Demo

See sum, avg, count, and other aggregate values computed automatically on grouped data with custom aggregation function support.

Plugin Options

Name Type Default Description
defaultAggFunc string undefined Default aggregation function name applied to columns without an explicit aggFunc.
customAggFuncs Record<string, AggFunc> {} Custom aggregation functions merged with the built-in registry. Keys become the function names you reference in aggFunc.

Built-in Aggregation Functions

Name Description
sum Sum of all numeric values.
avg Average of all numeric values.
count Count of non-null values.
min Minimum numeric value.
max Maximum numeric value.
first First value in the group.
last Last value in the group.

Usage Examples

Set Aggregation on a Column at Runtime

grid.commandBus.dispatch('agg:setColumnFunc', {
  colId: 'salary',
  aggFunc: 'avg',
});

Remove Aggregation from a Column

When all aggregation columns are removed, aggData is cleared from all group nodes.

grid.commandBus.dispatch('agg:removeColumnFunc', {
  colId: 'salary',
});

Manually Trigger Recomputation

Aggregations auto-recompute on grouping:changed events. You can also trigger it manually.

grid.commandBus.dispatch('agg:compute', {});

Custom Aggregation Functions

The AggFunc signature receives an object with values, nodes, and column:

type AggFunc = (params: {
  values: any[];
  nodes: RowNode[];
  column: ColumnState;
}) => any;

For hierarchical groups, values may contain already-aggregated child group values rather than raw leaf values, enabling cascading aggregation.

Commands

Name Payload Description
agg:setColumnFunc { colId: string; aggFunc: string } Set the aggregation function on a column. Triggers immediate recomputation.
agg:removeColumnFunc { colId: string } Remove aggregation from a column. Sets aggFunc to null. Clears aggData if no agg columns remain.
agg:compute {} Manually trigger aggregation recomputation across all group nodes.

Events

Name Payload Description
aggregation:computed { groupNodeIds: string[] } Emitted after aggregations are computed. Contains the IDs of all group nodes that were updated.
grouping:changed { groupColumns: string[] } Listened to internally to auto-recompute aggregations when grouping changes.

React Integration

import { GridStorm, useGridApi } from '@gridstorm/react';
import { GroupingPlugin } from '@gridstorm/plugin-grouping';
import { AggregationPlugin } from '@gridstorm/plugin-aggregation';

function AggregatedGrid({ rowData, columns }) {
  const apiRef = useGridApi();

  const switchToAvg = () => {
    apiRef.current?.commandBus.dispatch('agg:setColumnFunc', {
      colId: 'salary',
      aggFunc: 'avg',
    });
  };

  return (
    <>
      <button onClick={switchToAvg}>Show Average Salary</button>
      <GridStorm
        rowData={rowData}
        columns={columns}
        plugins={[
          GroupingPlugin({ defaultExpanded: true }),
          AggregationPlugin(),
        ]}
      />
    </>
  );
}

Next Steps