PivotGrid

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-pivot-grid

pnpm add jsonata @shopify/flash-list expo-file-system (optional) expo-sharing (optional) expo-print (optional)

The export modules are optional peers and are loaded lazily. CSV and Excel exports need expo-file-system (SDK 54+ File API) and expo-sharing. PDF export needs expo-print and expo-sharing. When a module is missing, the export does nothing.

For a server-backed pivot, see useDocyrusPivotGrid.

Usage

import { Badge } from '@/components/docyrus-native/badge';
import {
  PivotGrid,
  PivotGridView,
  PivotGridToolbar,
  PivotGridDrilldownModal,
  usePivotGrid,
  type PivotGridDimension,
  type PivotGridMeasure,
} from '@/components/docyrus-native/pivot-grid';

interface SalesRow {
  region: string;
  product: string;
  revenue: number;
}

const data: SalesRow[] = [
  { region: 'North', product: 'Widget A', revenue: 1200 },
  { region: 'North', product: 'Widget B', revenue: 850 },
  { region: 'South', product: 'Widget A', revenue: 960 },
  { region: 'South', product: 'Widget B', revenue: 1100 },
];

const rowDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'region', label: 'Region', getValue: (row) => row.region },
];

const columnDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'product', label: 'Product', getValue: (row) => row.product },
];

const measures: PivotGridMeasure<SalesRow>[] = [
  {
    id: 'revenue',
    label: 'Revenue',
    getValue: (row) => row.revenue,
    aggregate: 'sum',
    formatValue: (v) => `$${v.toLocaleString()}`,
  },
];

function SalesPivot() {
  const controller = usePivotGrid({
    data,
    rowDimensions,
    columnDimensions,
    measures,
    height: 400,
    initialState: { columnPinning: { right: [] } },
    exportFileName: 'sales-report'
  });

  return (
    <>
      <PivotGridToolbar
        controller={controller}
        startContent={<Badge>{data.length} rows</Badge>} />
      <PivotGridView controller={controller} />
      <PivotGridDrilldownModal controller={controller} />
    </>
  );
}

// Or self-contained (creates its own controller):
<PivotGrid data={data} rowDimensions={rowDimensions} columnDimensions={columnDimensions} measures={measures} height={400} />

Features

• Multi-dimension pivoting — 1-3 row/column dimensions with nested grouping
• Aggregation — sum, count, avg, min, max
• Expand/collapse — toggle individual rows/columns or expand/collapse all
• Conditional coloring — JSONata-based cell color rules with Tailwind color support
• Drilldown — tap a leaf cell to see contributing source rows in an action sheet
• Toolbar — expand / collapse buttons, the export menu, and startContent / endContent slots
• Export — CSV, a real .xlsx workbook (merged multi-level headers, frozen panes, styled subtotal and total rows, written by a zero-dependency OOXML writer) and PDF (expo-print). Each export opens the native share sheet.
• Pinned value columns — pinColumns(ids, 'left' | 'right') keeps columns sticky while you scroll horizontally. Row headers are always pinned.
• Virtualized scrolling — FlashList windowing for large datasets
• Synchronized scroll — row headers and column headers stay in sync with the data grid

API Reference

PivotGrid / usePivotGrid props

PivotGrid takes the same props as usePivotGrid (PivotGridProps = UsePivotGridProps) and creates its own controller.

PivotGridView

Renders a controller from usePivotGrid. Use it to share one controller with the toolbar and the drilldown modal.

PivotGridToolbar

A horizontally scrolling toolbar with expand rows, collapse rows, expand columns, collapse columns and the export menu.

PivotGridExportMenu

An export button that opens an action sheet with Export CSV, Export Excel and Export PDF. It replaces the web dropdown.

PivotGridDrilldownModal

An action sheet that lists the source rows behind a tapped leaf cell.

PivotGridController

Returned by usePivotGrid.

PivotGridState

PivotGridDimension

PivotGridMeasure

PivotGridCellColorRule

PivotGridDrilldown / NativeDrilldownColumn

Translations

Hooks

usePivotGrid

const controller = usePivotGrid<TData>(props: UsePivotGridProps<TData>);

Returns a PivotGridController with the full view model and every action callback. Use it when PivotGridView, PivotGridToolbar and PivotGridDrilldownModal need to share one controller.

Components

Type Exports