# Pivot Grid
URL: /docs/web/components/pivot-grid

A standalone pivot grid with 3-level row and column hierarchies, subtotals, grand totals, drilldown, pinning, resizing, and export.

**Demo:**

```tsx
'use client';
// @custom-demo

import {
  useCallback,
  useEffect,
  useMemo,
  useState
} from 'react';

import {
  PivotGridToolbar,
  PivotGridView, usePivotGrid
} from '@docyrus/ui/components/pivot-grid';
import { useMounted } from '@docyrus/ui/primitives/hooks/use-mounted';
import {
  AwesomeDialog,
  AwesomeDialogBody,
  AwesomeDialogHeader
} from '@docyrus/ui/components/awesome-dialog';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import {
  ChevronDownIcon,
  Maximize2Icon,
  Settings2Icon
} from 'lucide-react';

import {
  createPivotGridDemoRows,
  pivotGridDemoColorRules,
  pivotGridDemoColumnDimensions,
  pivotGridDemoMeasures,
  pivotGridDemoRowDimensions,
  type PivotGridDemoRow
} from '@ui/components/pivot-grid/pivot-grid-demo-data';

interface PivotGridDemoSurfaceProps {
  enableColorRules: boolean;
  pinGrandTotals: boolean;
  showConfigure: boolean;
  onEnableColorRulesChange: (value: boolean) => void;
  onPinGrandTotalsChange: (value: boolean) => void;
  onShowConfigureChange: (value: boolean) => void;
  height: number | 'auto';
  showFullscreenButton?: boolean;
  onOpenFullscreen?: () => void;
}

function PivotGridDemoSurface({
  enableColorRules,
  pinGrandTotals,
  showConfigure,
  onEnableColorRulesChange,
  onPinGrandTotalsChange,
  onShowConfigureChange,
  height,
  showFullscreenButton = false,
  onOpenFullscreen
}: PivotGridDemoSurfaceProps) {
  const data = useMemo(() => createPivotGridDemoRows({
    regions: 2,
    countriesPerRegion: 2,
    citiesPerCountry: 2,
    years: 2,
    quarters: 2,
    channels: 2
  }), []);
  const measures = useMemo(() => pivotGridDemoMeasures.slice(0, 2), []);
  const getRowId = useCallback((row: PivotGridDemoRow) => row.id, []);

  const controller = usePivotGrid({
    data,
    rowDimensions: pivotGridDemoRowDimensions,
    columnDimensions: pivotGridDemoColumnDimensions,
    measures,
    getRowId,
    cellColorRules: enableColorRules ? pivotGridDemoColorRules : undefined,
    height,
    className: height === 'auto' ? 'min-h-0 flex-1' : undefined
  });
  const {
    pinColumns,
    table,
    unpinColumns,
    visibleLeafColumns
  } = controller;

  useEffect(() => {
    const grandTotalColumnIds = visibleLeafColumns
      .filter(column => column.kind === 'grand-total')
      .map(column => column.id);

    if (grandTotalColumnIds.length === 0) {
      return;
    }

    const hasPinnedGrandTotals = grandTotalColumnIds.every(
      columnId => table.getColumn(columnId)?.getIsPinned() === 'right'
    );

    if (pinGrandTotals) {
      if (!hasPinnedGrandTotals) {
        pinColumns(grandTotalColumnIds, 'right');
      }

      return;
    }

    if (hasPinnedGrandTotals) {
      unpinColumns(grandTotalColumnIds);
    }
  }, [
    pinColumns,
    table,
    unpinColumns,
    visibleLeafColumns,
    pinGrandTotals
  ]);

  return (
    <div className={cn('w-full space-y-3', height === 'auto' && 'flex min-h-0 flex-1 flex-col')}>
      
            ) : null}
            
          </>
        )} />

      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          showConfigure ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="grid gap-4 rounded-lg border bg-muted/30 p-4 sm:grid-cols-2">
            <label className="flex items-center justify-between gap-3 rounded-md border bg-background px-3 py-2 text-sm">
              <span>Enable JSONata color rules</span>
              
      
    </>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-pivot-grid
```

**Dependencies:**
- [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)
- [@tanstack/react-virtual](https://www.npmjs.com/package/@tanstack/react-virtual)
- [jsonata](https://www.npmjs.com/package/jsonata)
- [exceljs](https://www.npmjs.com/package/exceljs)
- [html2canvas-pro](https://www.npmjs.com/package/html2canvas-pro)
- [pdf-lib](https://www.npmjs.com/package/pdf-lib)

## Usage

```tsx
import {
  PivotGridToolbar,
  PivotGridView,
  usePivotGrid,
  type PivotGridCellColorRule,
  type PivotGridDimension,
  type PivotGridMeasure
} from '@docyrus/ui/components/pivot-grid';

const rowDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'region', label: 'Region', getValue: row => row.region },
  { id: 'country', label: 'Country', getValue: row => row.country },
  { id: 'city', label: 'City', getValue: row => row.city }
];

const columnDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'year', label: 'Year', getValue: row => row.year },
  { id: 'quarter', label: 'Quarter', getValue: row => row.quarter },
  { id: 'channel', label: 'Channel', getValue: row => row.channel }
];

const measures: PivotGridMeasure<SalesRow>[] = [
  {
    id: 'revenue',
    label: 'Revenue',
    aggregate: 'sum',
    getValue: row => row.revenue,
    formatValue: value => new Intl.NumberFormat(undefined, {
      style: 'currency',
      currency: 'USD',
      maximumFractionDigits: 0
    }).format(value)
  },
  {
    id: 'orders',
    label: 'Orders',
    aggregate: 'sum',
    getValue: row => row.orders
  }
];

const cellColorRules: PivotGridCellColorRule[] = [
  {
    scope: 'leaf',
    formula: 'measureId = "revenue" and value > 10000',
    color: 'emerald-100'
  },
  {
    scope: 'grand-total',
    formula: 'value > 0',
    color: 'slate-200'
  }
];

function SalesPivot() {
  const pivot = usePivotGrid({
    data,
    rowDimensions,
    columnDimensions,
    measures,
    getRowId: row => row.id,
    cellColorRules
  });

  return (
    <div className="space-y-3">
      
      
    </div>
  );
}
```

## Notes

- Row groups and column groups can be collapsed independently at each visible branch.
- Subtotals are emitted after every visible branch. Grand totals remain available even when groups are collapsed.
- Drilldown opens a read-only `DataGrid` dialog with the raw rows that contributed to the selected aggregate cell.
- CSV flattens the current visible header paths. Excel and PDF preserve the current visible hierarchy more faithfully.