PivotHead React

High-Performance Pivot Tables for React Applications

Features • Installation • Quick Start • Documentation • Examples • Support

Screenshots

🚀 Try it live: Interactive Demo | Example Projects

Features

React-First Design

• Native React hooks support
• TypeScript definitions included
• Full SSR compatibility
• Optimized re-rendering

WebAssembly Powered

• Process CSV files up to 1GB
• 10x faster than pure JavaScript
• Automatic performance optimization
• Zero configuration required

Flexible Rendering

• Default Mode: Full UI included
• Minimal Mode: Slot-based customization
• Headless Mode: Complete control
• Custom themes support

Rich Features

• Drag-and-drop field management
• Dynamic aggregations
• Advanced filtering
• Multi-level grouping

Developer-Friendly

• Simple API
• Comprehensive docs
• Full TypeScript support
• Extensive examples

Framework Agnostic Core

• Works with React 17+
• Compatible with Next.js
• Remix support
• Vite optimized

Installation

# npm
npm install @mindfiredigital/pivothead-react

# yarn
yarn add @mindfiredigital/pivothead-react

# pnpm
pnpm add @mindfiredigital/pivothead-react

Requirements

• React: 17.0.0 or higher
• TypeScript (optional): 4.5.0 or higher
• Node.js: 12.0.0 or higher

Quick Start

Basic Example

import { PivotHead } from '@mindfiredigital/pivothead-react';

// Your data
const salesData = [
  { product: 'Laptop', region: 'North', sales: 5000, quarter: 'Q1' },
  { product: 'Phone', region: 'South', sales: 3000, quarter: 'Q1' },
  { product: 'Tablet', region: 'East', sales: 2000, quarter: 'Q2' },
  // ... more data
];

// Configuration
const pivotOptions = {
  rows: ['product'],
  columns: ['region'],
  values: ['sales'],
};

export default function Dashboard() {
  return (
    <div>
      <h1>Sales Dashboard</h1>
      <PivotHead mode="default" data={salesData} options={pivotOptions} />
    </div>
  );
}

Load Large CSV Files (WebAssembly)

import { PivotHead } from '@mindfiredigital/pivothead-react';
import { useState } from 'react';

export default function CsvUploader() {
  const [fileData, setFileData] = useState<File | null>(null);

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (file) {
      setFileData(file);
      // The component automatically uses WebAssembly for optimal performance
      // - Files < 8MB: Processed in-memory with WASM
      // - Files > 8MB: Streaming + WASM hybrid mode
    }
  };

  return (
    <div>
      <input type="file" accept=".csv" onChange={handleFileChange} />

      {fileData && (
        <PivotHead
          mode="default"
          data={fileData}
          onStateChange={e => {
            console.log('Performance mode:', e.detail.performanceMode);
            // Possible values: 'standard', 'workers', 'wasm', 'streaming-wasm'
          }}
        />
      )}
    </div>
  );
}

Rendering Modes

1️ Default Mode (Full UI)

Complete pivot table with built-in interface, drag-and-drop, filters, and controls.

<PivotHead mode="default" data={data} options={options} />

Best for: Quick implementation, prototyping, admin panels

2️ Minimal Mode (Customizable)

Component provides structure; you control the styling and layout.

<PivotHead mode="minimal" data={data} options={options}>
  <div slot="header">{/* Your custom toolbar */}</div>
  <div slot="body">{/* Your custom table rendering */}</div>
</PivotHead>

Best for: Custom branding, unique designs, themed applications

3️ Headless Mode (Complete Control)

No UI rendered - full programmatic control via API and events.

import { PivotHead } from '@mindfiredigital/pivothead-react';
import { useRef, useEffect, useState } from 'react';

export default function CustomPivot() {
  const pivotRef = useRef<HTMLElement>(null);
  const [state, setState] = useState(null);

  useEffect(() => {
    const handleStateChange = (e: CustomEvent) => {
      setState(e.detail);
    };

    pivotRef.current?.addEventListener('stateChange', handleStateChange);

    return () => {
      pivotRef.current?.removeEventListener('stateChange', handleStateChange);
    };
  }, []);

  return (
    <div>
      <PivotHead ref={pivotRef} mode="none" data={data} options={options} />

      {/* Build your own UI using the state */}
      {state && <YourCustomTable data={state.processedData} />}
    </div>
  );
}

Best for: Maximum flexibility, custom visualizations, advanced integrations

Advanced Usage

With TypeScript

import { PivotHead } from '@mindfiredigital/pivothead-react';
import type {
  PivotTableState,
  PivotTableOptions,
} from '@mindfiredigital/pivothead';

interface SalesRecord {
  product: string;
  region: string;
  sales: number;
  date: string;
}

const options: PivotTableOptions = {
  rows: ['product'],
  columns: ['region'],
  values: ['sales'],
};

export default function TypedPivot() {
  const handleStateChange = (
    event: CustomEvent<PivotTableState<SalesRecord>>
  ) => {
    console.log('New state:', event.detail);
  };

  return (
    <PivotHead<SalesRecord>
      mode="default"
      data={salesData}
      options={options}
      onStateChange={handleStateChange}
    />
  );
}

Using Component Methods

import { PivotHead } from '@mindfiredigital/pivothead-react';
import { useRef } from 'react';

export default function MethodsExample() {
  const pivotRef = useRef<any>(null);

  const handleExportPDF = () => {
    pivotRef.current?.exportToPDF('sales-report');
  };

  const handleExportExcel = () => {
    pivotRef.current?.exportToExcel('sales-data');
  };

  const handleSort = (field: string) => {
    pivotRef.current?.sort(field, 'desc');
  };

  return (
    <div>
      <div className="toolbar">
        <button onClick={handleExportPDF}>Export PDF</button>
        <button onClick={handleExportExcel}>Export Excel</button>
        <button onClick={() => handleSort('sales')}>Sort by Sales</button>
      </div>

      <PivotHead ref={pivotRef} mode="default" data={data} options={options} />
    </div>
  );
}

Real-Time Data Updates

import { PivotHead } from '@mindfiredigital/pivothead-react';
import { useState, useEffect } from 'react';

export default function LiveDashboard() {
  const [data, setData] = useState([]);

  useEffect(() => {
    // Simulate real-time data updates
    const interval = setInterval(() => {
      fetch('/api/sales/latest')
        .then(res => res.json())
        .then(newData => setData(newData));
    }, 5000);

    return () => clearInterval(interval);
  }, []);

  return <PivotHead mode="default" data={data} options={options} />;
}

Documentation

Component Props

| Prop | Type | Default | Description | | --------------- | ---------------------------------- | ----------- | -------------------------------------------------- | | mode | 'default' \| 'minimal' \| 'none' | 'default' | Rendering mode | | data | Array \| File \| string | [] | Data source (JSON array, CSV File, or JSON string) | | options | PivotTableOptions \| string | {} | Pivot configuration | | filters | FilterConfig[] \| string | [] | Active filters | | pagination | PaginationConfig \| string | {} | Pagination settings | | onStateChange | (event: CustomEvent) => void | - | Fired when state changes |

Available Methods

Access methods via ref:

const pivotRef = useRef<any>(null);

// Methods
pivotRef.current?.getState(); // Get current state
pivotRef.current?.refresh(); // Refresh the pivot table
pivotRef.current?.sort(field, dir); // Sort by field
pivotRef.current?.exportToPDF(name); // Export to PDF
pivotRef.current?.exportToExcel(name); // Export to Excel
pivotRef.current?.exportToHTML(name); // Export to HTML

Events

| Event | Payload | Description | | --------------- | ----------------- | -------------------------------------------------- | | onStateChange | PivotTableState | Triggered on any state change (sort, filter, etc.) |

Examples

Full Examples Repository

Check out complete working examples in the repository:

| Example | Description | Path | | ----------------- | ------------------------------------------ | ------------------------------------------------------------------- | | Default Mode | Full UI with all features enabled | react-web-component-demo | | React Wrapper | React-specific implementation | react-demo | | CSV Upload | Large file processing with WASM | simple-js-demo | | Minimal Mode | Custom rendering with slots | pivothead-minimal-demo | | Headless Mode | Complete control for custom visualizations | pivothead-none-demo |

Running Examples Locally

# Clone the repository
git clone https://github.com/mindfiredigital/PivotHead.git
cd PivotHead

# Navigate to React demo
cd examples/react-demo

# Install dependencies
pnpm install

# Start development server
pnpm dev

Performance Benchmarks

| File Size | Processing Mode | Load Time | Memory Usage | | --------- | ---------------- | --------- | ------------- | | < 1 MB | Standard | ~50ms | Low | | 1-8 MB | Web Workers | ~200ms | Medium | | 8-100 MB | WASM (in-memory) | ~800ms | Medium | | 100MB-1GB | Streaming + WASM | ~3-5s | Low (chunked) |

All benchmarks run on Chrome 120, MacBook Pro M1, 16GB RAM

Framework Integration

Next.js

// app/dashboard/page.tsx
'use client';

import dynamic from 'next/dynamic';

const PivotHead = dynamic(
  () => import('@mindfiredigital/pivothead-react').then(mod => mod.PivotHead),
  { ssr: false }
);

export default function DashboardPage() {
  return <PivotHead mode="default" data={data} options={options} />;
}

Remix

// app/routes/dashboard.tsx
import { PivotHead } from '@mindfiredigital/pivothead-react';
import { useLoaderData } from '@remix-run/react';

export async function loader() {
  const data = await fetchSalesData();
  return { data };
}

export default function Dashboard() {
  const { data } = useLoaderData();
  return <PivotHead mode="default" data={data} options={options} />;
}

Support

If PivotHead helps your project, please consider:

• ⭐ Star the repository

License

MIT © Mindfiredigital

Built with ❤️ by the Mindfiredigital team

GitHub • NPM • Website