Pivot Mode - AG Grid

Enterprise Feature: Pivoting requires ag-grid-enterprise and a valid license key.

Pivot Mode transforms your grid into a pivot table, creating dynamic columns based on row values and aggregating data across multiple dimensions.

Installation

Install Package

npm install ag-grid-enterprise

Import Module

import { ModuleRegistry } from 'ag-grid-community';
import { PivotModule } from 'ag-grid-enterprise';

ModuleRegistry.registerModules([PivotModule]);

Set License Key

import { LicenseManager } from 'ag-grid-enterprise';

LicenseManager.setLicenseKey('YOUR_LICENSE_KEY');

Pivot Module requires Row Grouping Module. Source: /packages/ag-grid-enterprise/src/pivot/pivotModule.ts:55-61

Basic Pivot Table

Create a pivot table by enabling pivot mode and configuring pivot columns:

import { ColDef, GridOptions } from 'ag-grid-community';

const columnDefs: ColDef[] = [
  { 
    field: 'country',
    rowGroup: true,      // Group rows by country
    hide: true
  },
  { 
    field: 'year',
    pivot: true,         // Create columns for each year
    hide: true
  },
  { 
    field: 'sport',
    pivot: true          // Secondary pivot dimension
  },
  { 
    field: 'gold',
    aggFunc: 'sum'       // Aggregate gold medals
  },
  { 
    field: 'silver',
    aggFunc: 'sum'
  }
];

const gridOptions: GridOptions = {
  columnDefs,
  rowData: olympicData,
  pivotMode: true,               // Enable pivot mode
  autoGroupColumnDef: {
    minWidth: 200
  }
};

Understanding Pivot Tables

A pivot table has three key components:

Row Groups

Columns with rowGroup: true form the row hierarchy (e.g., Country)

Pivot Columns

Columns with pivot: true create dynamic column headers (e.g., Year)

Value Columns

Columns with aggFunc are aggregated in pivot cells (e.g., Sum of Gold)

Column Configuration

Enable Pivot

Configure columns to support pivoting:

const columnDefs: ColDef[] = [
  {
    field: 'year',
    enablePivot: true,    // Allow user to drag to pivot panel
    pivot: false          // Not pivoted by default
  },
  {
    field: 'quarter',
    pivot: true,          // Pivoted by default
    pivotIndex: 0         // First pivot dimension
  },
  {
    field: 'month',
    pivot: true,
    pivotIndex: 1         // Second pivot dimension (nested)
  }
];

Pivot Comparator

Control the order of pivot columns:

const columnDefs: ColDef[] = [
  {
    field: 'month',
    pivot: true,
    pivotComparator: (a, b) => {
      const monthOrder = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                          'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
      return monthOrder.indexOf(a) - monthOrder.indexOf(b);
    }
  }
];

Programmatic API

Control pivot mode and columns programmatically:

Check Pivot Mode

import { GridApi } from 'ag-grid-community';

const api: GridApi = gridRef.current.api;

// Check if pivot mode is enabled
const isPivot = api.isPivotMode();
console.log('Pivot mode:', isPivot);

Source: /packages/ag-grid-enterprise/src/pivot/pivotApi.ts:3-5

Set Pivot Columns

// Set columns to pivot by
api.setPivotColumns(['year', 'quarter']);

// Add a column to pivoting
api.addPivotColumns(['month']);

// Remove a column from pivoting
api.removePivotColumns(['quarter']);

// Get current pivot columns
const pivotCols = api.getPivotColumns();
console.log(pivotCols.map(col => col.getColId()));

Source: /packages/ag-grid-enterprise/src/pivot/pivotApi.ts:31-44

Set Value Columns

// Set which columns to aggregate in pivot cells
api.setValueColumns(['gold', 'silver', 'bronze']);

// Add value column
api.addValueColumns(['total']);

// Remove value column
api.removeValueColumns(['bronze']);

// Get current value columns
const valueCols = api.getValueColumns();
console.log(valueCols.map(col => col.getColId()));

Source: /packages/ag-grid-enterprise/src/pivot/pivotApi.ts:15-29

Access Pivot Result Columns

// Get generated pivot result columns
const resultCols = api.getPivotResultColumns();

// Get specific pivot result column
const col = api.getPivotResultColumn(
  ['2020', 'Q1'],  // Pivot keys
  'gold'           // Value column key
);

if (col) {
  console.log('Column ID:', col.getColId());
  console.log('Column definition:', col.getColDef());
}

Source: /packages/ag-grid-enterprise/src/pivot/pivotApi.ts:7-13 and 47-54

Grid Options

Pivot Mode Configuration

const gridOptions: GridOptions = {
  // Enable pivot mode
  pivotMode: true,
  
  // Suppress auto-generated pivot columns
  suppressExpandablePivotGroups: false,
  
  // Show pivot panel for drag-and-drop
  pivotPanelShow: 'always',  // 'always', 'onlyWhenPivoting', 'never'
  
  // Pivot column group totals
  pivotColumnGroupTotals: 'before',  // 'before', 'after', undefined
  
  // Pivot row totals
  pivotRowTotals: 'before',  // 'before', 'after', undefined
  
  // Suppress aggregation at higher levels
  suppressAggFuncInHeader: false,
  
  // Remove pivot columns that have no values
  removePivotHeaderRowWhenSingleValueColumn: false
};

Pivot Default Expanded

const gridOptions: GridOptions = {
  pivotMode: true,
  
  // Control default expansion of pivot groups
  groupDefaultExpanded: 0,    // Collapse all
  // groupDefaultExpanded: 1, // Expand first level
  // groupDefaultExpanded: -1 // Expand all
};

Value Columns with Multiple Aggregations

Allow different aggregation functions per value column:

const columnDefs: ColDef[] = [
  { field: 'country', rowGroup: true },
  { field: 'year', pivot: true },
  {
    field: 'gold',
    enableValue: true,
    allowedAggFuncs: ['sum', 'avg', 'min', 'max'],
    aggFunc: 'sum'
  },
  {
    headerName: 'Total Medals',
    valueGetter: params => {
      return (params.data.gold || 0) + 
             (params.data.silver || 0) + 
             (params.data.bronze || 0);
    },
    aggFunc: 'sum'
  }
];

Advanced Pivot Features

Secondary Columns

Customize the generated pivot result columns:

const gridOptions: GridOptions = {
  pivotMode: true,
  
  // Process secondary columns as they're created
  processSecondaryColDef: (colDef) => {
    // Customize generated pivot columns
    colDef.minWidth = 100;
    colDef.maxWidth = 300;
    colDef.headerClass = 'pivot-header';
    return colDef;
  },
  
  // Process secondary column groups
  processSecondaryColGroupDef: (colGroupDef) => {
    // Customize generated column groups
    colGroupDef.headerClass = 'pivot-group-header';
    return colGroupDef;
  }
};

Pivot Chart Integration

Create charts directly from pivot data:

import { IntegratedChartsModule } from 'ag-grid-enterprise';
import { AgChartsEnterpriseModule } from 'ag-charts-enterprise';

ModuleRegistry.registerModules([
  IntegratedChartsModule.with(AgChartsEnterpriseModule)
]);

const gridOptions: GridOptions = {
  pivotMode: true,
  enableCharts: true,
  
  // Create pivot chart
  onGridReady: (params) => {
    params.api.createPivotChart({
      chartType: 'groupedColumn',
      chartContainer: document.querySelector('#chartContainer')
    });
  }
};

Total Columns

Add total columns before or after pivot groups:

const gridOptions: GridOptions = {
  pivotMode: true,
  
  // Show totals for column groups
  pivotColumnGroupTotals: 'before',  // Total column before group
  
  // Show totals for rows
  pivotRowTotals: 'after',          // Total row after group
  
  // Grand total configuration
  groupIncludeTotalFooter: true
};

Pivot Panel

Enable the Pivot Panel for drag-and-drop configuration:

const gridOptions: GridOptions = {
  // Show pivot panel
  pivotPanelShow: 'always',
  
  // Enable drag and drop
  rowGroupPanelShow: 'always',
  
  // Column configuration
  columnDefs: [
    { field: 'country', enableRowGroup: true },
    { field: 'year', enablePivot: true },
    { field: 'sport', enablePivot: true },
    { field: 'gold', enableValue: true, aggFunc: 'sum' }
  ],
  
  // Keep columns visible when dragged to panel
  suppressDragLeaveHidesColumns: true
};

Custom Pivot Aggregations

Implement custom aggregation logic for pivot cells:

import { IAggFunc, IAggFuncParams } from 'ag-grid-community';

// Weighted average aggregation
const weightedAverage: IAggFunc = (params: IAggFuncParams) => {
  let totalWeight = 0;
  let totalValue = 0;
  
  params.values.forEach((value, index) => {
    if (value != null && typeof value === 'number') {
      const weight = params.rowNode.data?.weight || 1;
      totalValue += value * weight;
      totalWeight += weight;
    }
  });
  
  return totalWeight > 0 ? totalValue / totalWeight : null;
};

const columnDefs: ColDef[] = [
  { field: 'country', rowGroup: true },
  { field: 'year', pivot: true },
  {
    field: 'score',
    aggFunc: weightedAverage,
    headerName: 'Weighted Avg Score'
  }
];

Performance Optimization

Limit Pivot Dimensions

Use fewer pivot columns to reduce the number of generated columns

Suppress Expansion

Set groupDefaultExpanded: 0 to collapse all groups initially

Filter Data

Apply filters before pivoting to reduce data volume

Debounce Updates

Use debounceMs on filters to reduce recalculation frequency

Common Patterns

Year-Over-Year Comparison

const columnDefs: ColDef[] = [
  { field: 'product', rowGroup: true },
  { field: 'year', pivot: true },
  { field: 'revenue', aggFunc: 'sum' },
  { field: 'units', aggFunc: 'sum' }
];

const gridOptions: GridOptions = {
  pivotMode: true,
  autoGroupColumnDef: {
    headerName: 'Product'
  }
};

Cross-Tabulation Report

const columnDefs: ColDef[] = [
  { field: 'region', rowGroup: true, rowGroupIndex: 0 },
  { field: 'department', rowGroup: true, rowGroupIndex: 1 },
  { field: 'quarter', pivot: true },
  { field: 'sales', aggFunc: 'sum' },
  { field: 'profit', aggFunc: 'sum' }
];

const gridOptions: GridOptions = {
  pivotMode: true,
  groupDefaultExpanded: 1,
  pivotColumnGroupTotals: 'after'
};

Troubleshooting

Pivot Columns Not Appearing

Enable Pivot Mode

Ensure pivotMode: true is set in grid options

Configure Pivot Columns

At least one column must have pivot: true

Set Value Columns

At least one column must have aggFunc defined

Check Module Registration

Verify PivotModule is registered

No Data in Pivot Cells

Ensure value columns have valid aggregation functions:

const columnDefs: ColDef[] = [
  { field: 'gold', aggFunc: 'sum' }  // Must have aggFunc
];

Next Steps

Row Grouping

Learn about row grouping fundamentals

Integrated Charts

Create charts from pivot data

Excel Export

Export pivot tables to Excel

Aggregation

Advanced aggregation techniques

Get Started

Framework Integration

Core Concepts

Features

Enterprise Features

Customization

Themes

​Installation

​Basic Pivot Table

​Understanding Pivot Tables

Row Groups

Pivot Columns

Value Columns

​Column Configuration

​Enable Pivot

​Pivot Comparator

​Programmatic API

​Check Pivot Mode

​Set Pivot Columns

​Set Value Columns

​Access Pivot Result Columns

​Grid Options

​Pivot Mode Configuration

​Pivot Default Expanded

​Value Columns with Multiple Aggregations

​Advanced Pivot Features

​Secondary Columns

​Pivot Chart Integration

​Total Columns

​Pivot Panel

​Custom Pivot Aggregations

​Performance Optimization

Limit Pivot Dimensions

Suppress Expansion

Filter Data

Debounce Updates

​Common Patterns

​Year-Over-Year Comparison

​Cross-Tabulation Report

​Troubleshooting

​Pivot Columns Not Appearing

​No Data in Pivot Cells

​Next Steps

Row Grouping

Integrated Charts

Excel Export

Aggregation

Build docs developers (and LLMs) love

Installation

Basic Pivot Table

Understanding Pivot Tables

Column Configuration

Enable Pivot

Pivot Comparator

Programmatic API

Check Pivot Mode

Set Pivot Columns

Set Value Columns

Access Pivot Result Columns

Grid Options

Pivot Mode Configuration

Pivot Default Expanded

Value Columns with Multiple Aggregations

Advanced Pivot Features

Secondary Columns

Pivot Chart Integration

Total Columns

Pivot Panel

Custom Pivot Aggregations

Performance Optimization

Common Patterns

Year-Over-Year Comparison

Cross-Tabulation Report

Troubleshooting

Pivot Columns Not Appearing

No Data in Pivot Cells

Next Steps