Documentation

Pivot Tables

Turn flat rows into a matrix — row fields on the left, column fields as dynamic headers, values aggregated in each cell.

  1. Define the field catalog

    Pass source fields in columns — labels, types, and formatters for the fact data. While pivot is active, the grid shows generated headers instead of this catalog as columns.
    TypeScript
    const headers: ReactColumnDef[] = [
      { accessor: "region", label: "Region", type: "string" },
      { accessor: "quarter", label: "Quarter", type: "string" },
      { accessor: "sales", label: "Sales", type: "number" },
    ];

  2. Provide flat rows

    Use a flat fact table — one object per measure row, not a pre-nested tree.
    TypeScript
    const flatRows = [
      { region: "North", quarter: "Q1", sales: 120000 },
      { region: "North", quarter: "Q2", sales: 145000 },
      { region: "South", quarter: "Q1", sales: 98000 },
    ];

  3. Set pivot

    Configure pivot with row dims, column dims, and at least one value. Consumer rowGrouping is ignored while pivot is on.
    React TSX
    <SimpleTable
      columns={headers}
      rows={flatRows}
      pivot={{
        rows: ["region"],
        columns: ["quarter"],
        values: [{ accessor: "sales", aggregation: { type: "sum" } }],
      }}
    />

Patterns

Multiple row dimensions

Multiple pivot.rows fields produce one flat row per combination (e.g. region × product), not an expand/collapse tree.

TypeScript
{
  rows: ["region", "product"],
  columns: ["quarter"],
  values: [{ accessor: "sales", aggregation: { type: "sum" } }],
}

Pivot Panel (column editor)

Set enablePivotPanel (with enableColumnEditor) to compose Available / Rows / Columns / Values in the side panel. The panel drives setPivot — pivot is active when Values has at least one measure.

TypeScript
enableColumnEditor: true,
enablePivotPanel: true,

Multiple measures

Add more entries to values. Optional label overrides the header. Aggregation types match aggregate functions.

TypeScript
{
  rows: ["channel"],
  columns: ["quarter"],
  values: [
    { accessor: "sales", aggregation: { type: "sum" }, label: "Sales" },
    { accessor: "units", aggregation: { type: "sum" }, label: "Units" },
  ],
}

Values only (no column dims)

Set columns: [] to group and aggregate without a matrix of dynamic headers.

TypeScript
{
  rows: ["region", "category"],
  columns: [],
  values: [
    { accessor: "sales", aggregation: { type: "sum" } },
    { accessor: "cost", aggregation: { type: "sum" } },
  ],
}

Totals

showRowTotals, showColumnTotals, and showGrandTotal default to true. Turn them off as needed.

TypeScript
{
  rows: ["country"],
  columns: ["category"],
  values: [{ accessor: "sales", aggregation: { type: "average" } }],
  showColumnTotals: false,
}

Programmatic pivot

Call setPivot to enable or update, getPivot to read the active config, or pass null to return to the source grid. onPivotChange fires for API-driven updates.

React TSX
tableRef.current?.setPivot({
  rows: ["region"],
  columns: ["quarter"],
  values: [{ accessor: "sales", aggregation: { type: "sum" } }],
});
const active = tableRef.current?.getPivot();
tableRef.current?.setPivot(null); // back to source grid

Example

StackBlitz

Props

Pivot props

PropertyRequiredDescriptionExample
pivot
PivotConfig | null
Optional
Matrix pivot config. When set, flat rows are reshaped into dynamic columns (one row per row-dimension combination). Pass null to disable. Consumer rowGrouping is off while active.
onPivotChange
(pivot: PivotConfig | null) => void
Optional
Fires when pivot changes via TableAPI.setPivot (not every prop sync from your app).
enablePivotPanel
boolean
Optional
Adds a Pivot Panel to the column editor for placing fields into Rows / Columns / Values. Requires enableColumnEditor. Pivot activates when Values has ≥ 1 measure.

PivotConfig

PropertyRequiredDescriptionExample
PivotConfig.rows
Accessor[]
Required
Row dimension accessors. Multiple fields → one flat row per combination.
PivotConfig.columns
Accessor[]
Required
Column dimension accessors. Distinct values become headers. Empty = values only.
PivotConfig.values
PivotValueConfig[]
Required
Measures to aggregate (at least one). Optional label overrides the header.
PivotConfig.showRowTotals
boolean
Optional
Total column across column dims. Default true. Only when columns is non-empty.
PivotConfig.showColumnTotals
boolean
Optional
Total row across row dims. Default true.
PivotConfig.showGrandTotal
boolean
Optional
Grand-total cells at the totals intersection. Default true.

Pivot TableAPI methods

PropertyRequiredDescriptionExample
setPivot(config)
(config: PivotConfig | null) => void
Optional
Enable, update, or clear pivot. Pass null for the source grid.
getPivot()
() => PivotConfig | null
Optional
Active pivot config, or null when off.
getPivotHeaders()
() => ColumnDef[]
Optional
Generated headers while pivot is active.
getPivotedRows()
() => Row[]
Optional
Post-pivot rows while pivot is active (flat combination rows plus optional totals).