Pivot Table Plugin

The Pivot plugin transforms flat data into a pivot table view.

Installation

import '@toolbox-web/grid/features/pivot';

Basic Usage

TypeScript

import '@toolbox-web/grid';
import '@toolbox-web/grid/features/pivot';
import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'region', header: 'Region' },
    { field: 'product', header: 'Product' },
    { field: 'quarter', header: 'Quarter' },
    { field: 'sales', header: 'Sales', type: 'number' },
  ],
  features: {
    pivot: {
      rowGroupFields: ['region', 'product'],
      columnGroupFields: ['quarter'],
      valueFields: [{ field: 'sales', aggFunc: 'sum', header: 'Total' }],
    },
  },
};
grid.rows = salesData;

React

import '@toolbox-web/grid-react/features/pivot';
import { DataGrid } from '@toolbox-web/grid-react';

function SalesPivot({ data }) {
  return (
    <DataGrid
      rows={data}
      columns={[
        { field: 'region', header: 'Region' },
        { field: 'product', header: 'Product' },
        { field: 'quarter', header: 'Quarter' },
        { field: 'sales', header: 'Sales', type: 'number' },
      ]}
      pivot={{
        rowGroupFields: ['region', 'product'],
        columnGroupFields: ['quarter'],
        valueFields: [{ field: 'sales', aggFunc: 'sum', header: 'Total' }],
      }}
      style={{ height: '400px' }}
    />
  );
}

Vue

<script setup>
import '@toolbox-web/grid-vue/features/pivot';
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';

const data = [
  { region: 'North', product: 'Widget', quarter: 'Q1', sales: 1000 },
  { region: 'North', product: 'Gadget', quarter: 'Q1', sales: 1500 },
  { region: 'South', product: 'Widget', quarter: 'Q2', sales: 1200 },
];

const pivotConfig = {
  rowGroupFields: ['region', 'product'],
  columnGroupFields: ['quarter'],
  valueFields: [{ field: 'sales', aggFunc: 'sum', header: 'Total' }],
};
</script>

<template>
  <TbwGrid :rows="data" :pivot="pivotConfig" style="height: 400px">
    <TbwGridColumn field="region" header="Region" />
    <TbwGridColumn field="product" header="Product" />
    <TbwGridColumn field="quarter" header="Quarter" />
    <TbwGridColumn field="sales" header="Sales" type="number" />
  </TbwGrid>
</template>

Angular

// Feature import - enables the [pivot] input
import { GridPivotDirective } from '@toolbox-web/grid-angular/features/pivot';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-sales-pivot',
  imports: [Grid, GridPivotDirective],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [pivot]="pivotConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class SalesPivotComponent {
  rows = [...]; // Your sales data

  columns: ColumnConfig[] = [
    { field: 'region', header: 'Region' },
    { field: 'product', header: 'Product' },
    { field: 'quarter', header: 'Quarter' },
    { field: 'sales', header: 'Sales', type: 'number' },
  ];

  pivotConfig = {
    rowGroupFields: ['region', 'product'],
    columnGroupFields: ['quarter'],
    valueFields: [{ field: 'sales', aggFunc: 'sum', header: 'Total' }],
  };
}

Demo

PIVOT

Active Whether pivot is active

Aggregation Aggregation function

sumavgcountminmax

Show total column Show the per-row Total column on the right

Show grand total Show grand total row at the bottom

Show tool panel Show drag-and-drop tool panel

Default expanded Groups expanded by default

Indent width Indent per depth level (px)

20

Animation Expand/collapse animation

slidefadefalse

Show source

Use the controls to explore the full pivot configuration — toggle active state, totals, grand total, tool panel, default expansion, indent width, aggregation function, and animation style. For sorting, see the Sorting section below.

Events & Programmatic API

Expand All Collapse All Get Expanded Groups

Event Log

Show source

Click groups to expand/collapse and watch the event log. Use the buttons to call the programmatic API. Open the tool panel and drag fields between zones to see pivot-config-change events.

Configuration Options

See PivotConfig for the full list of options and defaults.

Key options:

• showTotals — Shows/hides the per-row Total column on the right (the sum across all pivot columns for each row). This does not affect the aggregated values shown in group rows.
• showGrandTotal — Shows/hides the grand total row at the bottom.
• grandTotalInRowModel — When true, the grand total renders as a regular row instead of a sticky footer (useful for data export and copy/paste).

Aggregation Functions

Built-in: sum, avg, count, min, max, first, last

Custom Aggregators

You can provide a custom aggregation function instead of a built-in name:

features: {
  pivot: {
    rowGroupFields: ['region'],
    valueFields: [{
      field: 'sales',
      aggFunc: (values) => values.reduce((a, b) => a + b * 2, 0),
    }],
  },
}

Custom aggregators appear as “CUSTOM” in the tool panel and cannot be changed via the UI.

Value Formatting

Format aggregated values with a format function on the value field:

valueFields: [{
  field: 'revenue',
  aggFunc: 'sum',
  format: (value) => `$${value.toLocaleString()}`,
}]

If no format is provided, the plugin falls back to the original column’s format function.

Programmatic-Only Usage

To use pivot transformation without exposing the tool panel UI to users:

features: {
  pivot: {
    showToolPanel: false,
    rowGroupFields: ['region'],
    columnGroupFields: ['quarter'],
    valueFields: [{ field: 'sales', aggFunc: 'sum' }],
  },
},

The pivot API methods remain available for programmatic control.

Tool Panel

When showToolPanel: true (default), the pivot panel lets users configure the pivot interactively:

• Drag fields between Row Groups, Column Groups, and Values zones
• Reorder fields within a zone by dragging
• Search fields using the filter input at the top of the Available Fields list
• Change aggregation via the dropdown on each value field (built-in functions only — custom aggregators show “CUSTOM” and cannot be changed via the UI)

The panel fires pivot-config-change events when users modify the configuration.

Animation

The plugin supports animated expand/collapse transitions. Animation respects the grid-level animation.mode setting and can be customized per-plugin:

features: {
  pivot: {
    rowGroupFields: ['region'],
    valueFields: [{ field: 'sales', aggFunc: 'sum' }],
    animation: 'slide', // 'slide' | 'fade' | false
  },
},

Animation is automatically disabled when animation.mode is 'off' or when the user prefers reduced motion ('reduced-motion' mode with system preference).

Programmatic API

const plugin = grid.getPluginByName('pivot');

plugin.expand('North__Widget A');  // expand a specific group by key
plugin.collapse('North');           // collapse a group
plugin.expandAll();
plugin.collapseAll();
plugin.getExpandedGroups();         // returns string[] of expanded keys

Sorting

Pivot columns support interactive sorting — click any column header to cycle through ascending, descending, and unsorted.

Multi-Column Sort

When the Multi-Sort plugin is loaded alongside Pivot, shift-click adds secondary sort columns with numbered priority badges. Pivot translates the multi-sort model into hierarchical sorting that respects the group structure.

Click any column header to sort. Shift-click to sort by multiple columns. Click again to reverse. Click a third time to clear.

Programmatic Sort

You can also configure sorting programmatically:

features: {
  pivot: {
    rowGroupFields: ['region'],
    valueFields: [{ field: 'sales', aggFunc: 'sum' }],
    sortRows: { by: 'label', direction: 'asc' },    // sort row groups alphabetically
    sortColumns: 'desc',                              // sort column keys descending
  },
}

sortRows accepts { by: 'label' | 'value', direction: 'asc' | 'desc', valueField?: string }. When by is 'value', rows are sorted by their total (or by a specific valueField).

Default Expanded

Control which groups start expanded:

features: {
  pivot: {
    defaultExpanded: true,           // all groups (default)
    defaultExpanded: false,          // all collapsed
    defaultExpanded: 'North',        // expand only the 'North' group
    defaultExpanded: ['North', 'South'], // expand specific groups
    defaultExpanded: 0,              // expand group at index 0
  },
}

Grand Total in Row Model

By default, the grand total renders as a sticky footer. To include it in the row model (useful for exports and copy/paste):

features: {
  pivot: {
    showGrandTotal: true,
    grandTotalInRowModel: true,
  },
}

Events

Event	Detail	Description
pivot-toggle	{ key, expanded, label, depth }	Fired when a group is expanded or collapsed
pivot-state-change	{ active: boolean }	Fired when pivot mode is enabled or disabled
pivot-config-change	{ property, field?, zone? }	Fired when pivot configuration changes (fields, agg func, etc.)

grid.addEventListener('pivot-toggle', (e) => {
  console.log(`${e.detail.label} ${e.detail.expanded ? 'expanded' : 'collapsed'}`);
});

grid.addEventListener('pivot-state-change', (e) => {
  console.log(`Pivot is now ${e.detail.active ? 'active' : 'inactive'}`);
});

Styling

The pivot plugin supports CSS custom properties for theming. Override these on tbw-grid or a parent container:

CSS Custom Properties

Property	Default	Description
--tbw-pivot-group-bg	var(--tbw-color-row-alt)	Group row background
--tbw-pivot-group-hover	var(--tbw-color-row-hover)	Group row hover
--tbw-pivot-leaf-bg	var(--tbw-color-bg)	Leaf row background
--tbw-pivot-grand-total-bg	var(--tbw-color-header-bg)	Grand total row
--tbw-pivot-toggle-hover-bg	var(--tbw-color-row-hover)	Toggle button hover
--tbw-pivot-section-bg	var(--tbw-color-panel-bg)	Panel section background
--tbw-toggle-size	1.25em	Toggle button size
--tbw-animation-duration	200ms	Expand/collapse animation

Example

tbw-grid {
  /* Custom pivot styling */
  --tbw-pivot-group-bg: #fff3e0;
  --tbw-pivot-grand-total-bg: #ffcc80;
  --tbw-pivot-toggle-hover-bg: #ffe0b2;
}

CSS Classes

The pivot plugin uses these class names:

Class	Element
.pivot-group-row	Grouped summary row
.pivot-leaf-row	Detail/leaf row
.pivot-grand-total-row	Grand total row
.pivot-grand-total-footer	Sticky footer container
.pivot-toggle	Expand/collapse button
.pivot-label	Group name display
.tbw-pivot-slide-in	Row slide animation
.tbw-pivot-fade-in	Row fade animation

Plugin Compatibility

Incompatible Plugins

The Pivot plugin cannot be used with the following plugins:

• Row Grouping — Pivot creates its own aggregated row and column structure. Row grouping cannot be applied on top of pivot-generated rows.
• Tree — Pivot replaces the entire row and column structure with aggregated data. Tree hierarchy cannot coexist with pivot aggregation.
• Server-Side — Pivot requires the full dataset to compute aggregations. Server-side lazy loading provides rows in blocks, so pivot aggregation cannot be performed client-side.

A development-mode warning is shown if incompatible plugins are loaded together.

See Also

• Row Grouping — Group flat data by field values
• Server-Side Plugin — Lazy loading and remote data