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 salesData = [
  { region: 'North', product: 'Widget', quarter: 'Q1', sales: 1200 },
  { region: 'North', product: 'Widget', quarter: 'Q2', sales: 1500 },
  { region: 'South', product: 'Gadget', quarter: 'Q1', sales: 900 },
  { region: 'South', product: 'Gadget', quarter: 'Q2', sales: 1100 },
];

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';
import type { GridConfig } from '@toolbox-web/grid-react';

const gridConfig: 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' }],
    },
  },
};

function SalesPivot({ data }) {
  return <DataGrid rows={data} gridConfig={gridConfig} style={{ height: '400px' }} />;
}

Alternative: feature prop

You can instead pass columns={[ … ]} and pivot={{ … }} as individual props on <DataGrid>. That form is idiomatic React, but gridConfig keeps the configuration identical across every framework.

Vue

<script setup>
import '@toolbox-web/grid-vue/features/pivot';
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { GridConfig } 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 gridConfig: 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' }],
    },
  },
};
</script>

<template>
  <TbwGrid :rows="data" :grid-config="gridConfig" style="height: 400px" />
</template>

Alternative: prop + light-dom columns

You can instead bind :pivot="{ … }" and declare columns with <TbwGridColumn> children. That form is idiomatic Vue, but gridConfig keeps the configuration identical across every framework.

Angular

Define everything inside gridConfig.features, exactly like the other frameworks. The side-effect import registers the feature so the adapter can bridge it.

import '@toolbox-web/grid-angular/features/pivot';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';

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

  gridConfig: 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' }],
      },
    },
  };
}

Alternative: per-feature directive

You can instead import GridPivotDirective and bind [pivot] directly on <tbw-grid>. That form gives a compile-time check that the feature is imported, but gridConfig.features above is the recommended, framework-consistent approach.

Demos

Full configuration

PIVOT

ActiveWhether pivot is active

AggregationAggregation function

sumavgcountminmax

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

Show grand totalShow grand total row at the bottom

Show tool panelShow drag-and-drop tool panel

Default expandedGroups expanded by default

Indent widthIndent per depth level (px)

20

AnimationExpand/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 and programmatic API

Expand AllCollapse AllGet 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.

Accessibility

The pivot panel satisfies WCAG 2.2 SC 2.5.7 Dragging Movements: every field move that can be made by dragging a chip can also be made with a single pointer that never drags.

• Click the chip you would have dragged — pressing and releasing a field chip without moving is a tap, not a drag. HTML5 drag-and-drop only fires dragstart on a real drag, so a plain click means the pointer user could not (or chose not to) drag, and the panel opens a menu of click-only actions instead.
• Chips already in a zone — the menu offers Move up, Move down, Move to Column Groups (or Move to Row Groups from the column zone), Move to Values and Remove field. Steps that would run off the end of the zone are rendered disabled rather than hidden. Every entry calls the same panel callback a drop does, so the resulting pivot-config-change event is identical.
• Chips in Available Fields — the menu offers Add to Row Groups, Add to Column Groups and Add to Values, matching the three zones a chip can be dropped on.
• No reserved chrome — the alternative reuses the chip itself, so it costs no extra panel width. SC 2.5.7 requires the alternative to exist and be pointer-operable, not to be permanently on screen.
• Chip semantics — the accessible name is “<field> — drag, or activate for move options” so the dual purpose is announced. On a chip that owns a remove button, the name and role="button" sit on the chip’s label rather than the chip, because role="button" would make the remove button presentational. The menu itself is a role="group" of plain buttons; focus moves to the first enabled entry on open, Escape closes it, and moving focus outside dismisses it.

See Pointer Alternatives to Dragging for how this fits the grid-wide a11y.dragAlternatives setting.

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