aggregation

This skill builds on core and table-features. Aggregation is independent from grouping: use it alone for totals, or combine it with the grouping skill for synthetic grouped rows.

Setup

import {
  rowAggregationFeature,
  aggregationFn_mean,
  aggregationFn_sum,
  tableFeatures,
} from '@tanstack/table-core'

export const features = tableFeatures({
  rowAggregationFeature,
  aggregationFns: {
    mean: aggregationFn_mean,
    sum: aggregationFn_sum,
  },
})

Core Patterns

Grand total and selected row scopes

const grandTotal = salaryColumn.getAggregationValue()
const filteredTotal = salaryColumn.getAggregationValue({
  rows: table.getFilteredRowModel().rows,
})
const childTotal = salaryColumn.getAggregationValue({
  rows: table.getCoreRowModel().rows,
  maxDepth: 1,
})

The default uses the pre-grouped row model. Explicit rows can come from any row model or caller-selected subset. maxAggregationDepth defaults to 0, which selects the supplied roots; 1 selects direct sub-rows, and Infinity selects terminal rows. Branches that end early contribute their deepest available row. Default calls are cached; explicit-row calls intentionally are not because array identity and contents are caller-owned. table.getMaxSubRowDepth() returns the deepest structural depth in the core row model.

Multiple aggregations

columnHelper.accessor('salary', {
  aggregationFn: ['mean', { id: 'range', aggregationFn: 'extent' }],
})

const value = salaryColumn.getAggregationValue<{
  mean: number
  range: [number, number]
}>()

A scalar option returns a scalar. An array returns a keyed object. Named functions use their registry name; descriptors provide a stable id, which is required for inline definitions in an array.

Custom definitions

const weightedMean = constructAggregationFn({
  aggregate: ({ rows, getValue }) => {
    const total = rows.reduce((sum, row) => sum + Number(getValue(row)), 0)
    return rows.length ? total / rows.length : undefined
  },
})

The context provides depth-selected rows, maxDepth, getValue, column, columnId, table, and optional grouped-only groupingRow and subRows. Every aggregation configured on a column receives the same row frontier. Add merge({ subRowResults, subRows, ...context }) when nested groups can more efficiently combine already-computed sub-row results; otherwise the engine calls aggregate with both row sets. subRowResults[i] corresponds to subRows[i].

Manual or remote values

Set a column definition's getAggregationValue(context) to return { value } for requests handled by a server or another execution environment. Returning undefined falls back to the local definition. manualAggregation: true disables that local fallback.

Common Mistakes

HIGH Adding grouping for a grand total

Wrong: registering columnGroupingFeature solely to total a column.

Correct: register rowAggregationFeature and call column.getAggregationValue(). Grouping is only required for grouped rows.

HIGH Passing a scope label and rows

There is no scope option. Call getAggregationValue() for the cached default, or pass a single options object containing rows from the desired row model and maxDepth when the desired frontier is below those rows.

HIGH Reusing the legacy callable signature

Wrong: (columnId, leafRows, childRows) => result.

Correct: constructAggregationFn({ aggregate: ({ rows, subRows, getValue }) => result }).

MEDIUM Assuming arbitrary totals run in the worker

The experimental worker computes grouped row-model aggregates. Public getAggregationValue(options?) totals execute on the main thread, and custom grouped results sent by the worker must be structured-cloneable.

API Discovery

Inspect node_modules/@tanstack/table-core/dist/features/row-aggregation/ and the Aggregation Guide. Use Column_RowAggregation, AggregationFnDef, AggregationContext, and AggregationResult for the typed public surface.