Features Guide

A comprehensive reference for every PivotBlitz capability — from layouts and aggregators to charts, conditional formatting, persistence, and beyond.

Layouts

PivotBlitz supports three layout modes that control how row and column headers are rendered. Compact (default) nests row headers hierarchically for a dense view. Tabular renders a flat grid with each row field in its own column. Flat produces one row per unique combination of row values.

Svelte

<!-- Compact (default) -->
<PivotTable {store} />

<!-- Tabular layout -->
<PivotTable {store} layout="tabular" />

<!-- Flat layout -->
<PivotTable {store} layout="flat" />

Aggregators

16 built-in aggregators cover most analytical needs: Count, Count Unique, List Unique, Sum, Integer Sum, Average, Median, Min, Max, Sample Variance, Sample Std Dev, Weighted Average, and Percentile 25/50/75/90. You can also supply custom aggregators.

JavaScript

import { createPivotStore } from '@pivotblitz/svelte';

const store = createPivotStore({
  data,
  rows: ['region'],
  cols: ['year'],
  vals: ['revenue'],
  aggregatorName: 'Average',

  // Custom aggregator
  customAggregators: {
    'Geometric Mean': makeAggregator({
      init: () => ({ product: 1, count: 0 }),
      push: (state, val) => {
        state.product *= val;
        state.count++;
      },
      value: (state) =>
        Math.pow(state.product, 1 / state.count),
    }),
  },
});

Calculated Fields

Define virtual columns using formula expressions that reference field names. Supports Math functions (ABS, ROUND, SQRT, ...), Text (UPPER, CONCAT, ...), Date (YEAR, DATEDIFF, ...), Logic (IF, AND, OR, ...), and Aggregation (SUM, AVG, MEDIAN, ...).

JavaScript

import { applyCalculatedFields } from '@pivotblitz/core';

const fields = [
  {
    name: 'margin_pct',
    formula: '(revenue - cost) / revenue * 100',
  },
  {
    name: 'label',
    formula: 'CONCAT(UPPER(region), " - ", ROUND(revenue, 2))',
  },
  {
    name: 'fiscal_year',
    formula: 'IF(MONTH(date) > 6, YEAR(date) + 1, YEAR(date))',
  },
];

const enrichedData = applyCalculatedFields(data, fields);

Conditional Formatting

Apply visual rules to cells based on their values. Four rule types are available: ConditionalRule (20+ operators: gt, lt, between, top, bottom, aboveAverage, ...), HeatmapRule (color gradient), DataBarRule (in-cell bars), and IconSetRule (emoji/icons). Preset factory functions make common patterns easy.

JavaScript

import { presetRules } from '@pivotblitz/core';

const store = createPivotStore({
  data,
  rows: ['product'],
  vals: ['revenue'],
  conditionalFormats: [
    // Green-Yellow-Red heatmap
    presetRules.heatmapGYR(),

    // Traffic light icons
    presetRules.trafficLight(1000, 5000),

    // Blue data bars
    presetRules.dataBarsBlue(),

    // Arrow direction icons
    presetRules.arrowIcons(),

    // Star rating (1-5)
    presetRules.starRating(),

    // Highlight top 10
    presetRules.highlightTopN(10),

    // Green for positive, red for negative
    presetRules.positiveNegative(),

    // Bold values above/below average
    presetRules.aboveBelowAverage(),
  ],
});

Charts

The PivotChart component visualizes pivot data as interactive charts. Supported types: bar, line, pie, doughnut, area, and stacked.

Svelte

<script>
  import { PivotChart } from '@pivotblitz/svelte';
</script>

<PivotChart
  {store}
  type="bar"
  title="Revenue by Region"
  showLegend={true}
  height={400}
  colorScheme="vibrant"
/>

Sparklines

Render inline SVG trend charts within pivot rows. Sparklines provide at-a-glance visual summaries without leaving the table. Configure the type (line, bar, area), height, color, and whether to highlight min/max points.

JavaScript

const store = createPivotStore({
  data,
  rows: ['product'],
  cols: ['month'],
  vals: ['sales'],
  sparkline: {
    type: 'line',       // 'line' | 'bar' | 'area'
    height: 24,
    color: '#2563eb',
    showMinMax: true,
  },
});

Display Modes

Transform how cell values are presented with 10 display modes via ValConfig.displayMode: normal, pctOfGrandTotal, pctOfRowTotal, pctOfColTotal, pctOfParentRow, pctOfParentCol, runningTotal, difference, pctDifference, and rank.

JavaScript

const store = createPivotStore({
  data,
  rows: ['region'],
  cols: ['quarter'],
  vals: [
    {
      field: 'revenue',
      aggregator: 'Sum',
      displayMode: 'pctOfGrandTotal',
    },
    {
      field: 'revenue',
      aggregator: 'Sum',
      displayMode: 'runningTotal',
    },
    {
      field: 'revenue',
      aggregator: 'Sum',
      displayMode: 'rank',
    },
  ],
});

Top N Filtering

Limit visible rows to the top or bottom N items by aggregated value. Enable showOthers to roll up remaining items into an "Others" row. Filtering is hierarchical, applying independently within each group.

JavaScript

const store = createPivotStore({
  data,
  rows: ['category', 'product'],
  vals: ['revenue'],
  topN: {
    type: 'top',         // 'top' | 'bottom' | 'none'
    count: 5,
    showOthers: true,    // Roll up remaining into "Others"
  },
});

Range Selection

Enable spreadsheet-style cell range selection. Users can click to select a cell, shift-click to extend the range, ctrl/cmd-click for multi-select, and drag to select a rectangular area. The status bar automatically shows sum, average, count, min, and max for the selected range.

Svelte

<PivotTable
  {store}
  enableRangeSelection={true}
/>

<!-- Status bar shows sum, avg, count, min, max -->
<StatusBar {store} />

Row Drag & Drop

Allow users to reorder rows by dragging. Enable with the enableRowDragDrop prop and handle the new order via the onRowReorder callback.

Svelte

<PivotTable
  {store}
  enableRowDragDrop={true}
  onRowReorder={(event) => {
    console.log('Moved:', event.fromIndex, '->', event.toIndex);
  }}
/>

Master/Detail

Expand any row to reveal the underlying detail records. Click the arrow icon to toggle the detail panel. Configure the renderer and panel height via MasterDetailConfig.

JavaScript

const store = createPivotStore({
  data,
  rows: ['region'],
  vals: ['revenue'],
  masterDetail: {
    enabled: true,
    renderer: 'records',  // Show raw records
    height: 200,           // Detail panel height in px
  },
});

Undo/Redo

Track configuration changes and let users step backwards and forwards through history. Enable with the enableHistory option on createPivotStore, then call store.undo() and store.redo().

JavaScript

const store = createPivotStore({
  data,
  rows: ['region'],
  vals: ['revenue'],
  enableHistory: true,
});

// After user changes configuration...
store.undo();   // Step back
store.redo();   // Step forward

// Check availability
console.log(store.canUndo); // true | false
console.log(store.canRedo); // true | false

Export

Export pivot table data to multiple formats. The core package includes exportToCSV, exportToJSON, and exportToHTML. The Pro package adds exportToExcel and exportToPDF with advanced formatting options.

JavaScript

import { exportToCSV, exportToJSON, exportToHTML } from '@pivotblitz/core';
import { exportToExcel, exportToPDF } from '@pivotblitz/pro';

// Core exports
const csv  = exportToCSV(store);
const json = exportToJSON(store);
const html = exportToHTML(store);

// Pro exports
const xlsx = await exportToExcel(store, { sheetName: 'Report' });
const pdf  = await exportToPDF(store, { title: 'Q4 Report' });

i18n

PivotBlitz ships with 10 locales: en, it, de, fr, es, pt, ja, zh, ar. Set the locale prop on PivotTable. Arabic includes full RTL layout support.

Svelte

<!-- German locale -->
<PivotTable {store} locale="de" />

<!-- Arabic with RTL -->
<PivotTable {store} locale="ar" />

<!-- Japanese -->
<PivotTable {store} locale="ja" />

Theming

Wrap your application with ThemeProvider to enable light, dark, or system-detected color modes. Pass a customTheme object to override individual tokens.

Svelte

<script>
  import { ThemeProvider, PivotTable } from '@pivotblitz/svelte';
</script>

<ThemeProvider mode="dark">
  <PivotTable {store} />
</ThemeProvider>

<!-- Custom theme overrides -->
<ThemeProvider
  mode="light"
  customTheme={{
    primaryColor: '#7c3aed',
    headerBg: '#faf5ff',
    borderColor: '#e9d5ff',
  }}
>
  <PivotTable {store} />
</ThemeProvider>

Pinning

Pin rows or columns to the edges of the table so they remain visible during scrolling. Supports top, bottom, left, and right pinning.

Svelte

<PivotTable
  {store}
  pinnedTopRows={['Total']}
  pinnedBottomRows={['Average']}
  pinnedLeftColumns={['product']}
  pinnedRightColumns={['total']}
/>

Virtual Scrolling

Virtual scrolling is automatically enabled when the total cell count exceeds the virtualThreshold (default: 5000 cells). Only visible rows are rendered in the DOM, keeping performance smooth even with massive datasets. Use the forceVirtual prop to enable it regardless of size.

Svelte

<!-- Auto-enabled above 5000 cells -->
<PivotTable {store} />

<!-- Custom threshold -->
<PivotTable {store} virtualThreshold={2000} />

<!-- Force virtual scrolling on -->
<PivotTable {store} forceVirtual={true} />

Persistence

Save and restore pivot configurations using store.exportConfig() and store.importConfig(). Built-in storage adapters include LocalStorage, SessionStorage, Memory, and REST API.

JavaScript

// Save current configuration
const saved = store.exportConfig('My Report Layout');

// Restore later
store.importConfig(saved);

// Use a storage adapter
import { LocalStorageAdapter } from '@pivotblitz/core';

const adapter = new LocalStorageAdapter('pivotblitz-configs');
await adapter.save('report-v1', saved);
const restored = await adapter.load('report-v1');

Cell Flashing

Highlight cells momentarily when their values change — ideal for real-time dashboards. Configure the flash duration and colors for upward and downward changes via the cellFlash option.

JavaScript

const store = createPivotStore({
  data,
  rows: ['ticker'],
  vals: ['price'],
  cellFlash: {
    enabled: true,
    duration: 500,           // ms
    upColor: '#bbf7d0',      // green flash on increase
    downColor: '#fecaca',    // red flash on decrease
  },
});

Print Mode

Render a print-friendly version of the pivot table. Enable with the enablePrint prop and customize via PrintConfig for title, page size, orientation, and timestamp.

Svelte

<PivotTable
  {store}
  enablePrint={true}
  printConfig={{
    title: 'Quarterly Revenue Report',
    pageSize: 'A4',
    orientation: 'landscape',
    showTimestamp: true,
  }}
/>