# PivotHead Web Component **Universal Pivot Tables for Any JavaScript Framework** [![npm version](https://img.shields.io/npm/v/@mindfiredigital/pivothead-web-component?color=brightgreen)](https://www.npmjs.com/package/@mindfiredigital/pivothead-web-component) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript)](https://www.typescriptlang.org/) [![Web Components](https://img.shields.io/badge/Web_Components-Standard-29ABE2?logo=webcomponents.org)](https://www.webcomponents.org/) [Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [API](#-api-reference) • [Examples](#-examples) • [Support](#-support)
--- ## Screenshots > ** Try it live**: Check out the [examples directory](../../examples) for working demos across different modes and frameworks --- ## ⚡ Features
### **Framework Agnostic** - **Vanilla JavaScript** - Works anywhere - **React** - Native wrapper available - **Vue** - Full compatibility - **Angular** - Drop-in component - **Svelte** - Seamless integration - **Any framework** - Standard web component ### **WebAssembly Performance** - Process **up to 1GB CSV files** - **10x faster** than JavaScript - **Automatic optimization** - < 1MB: Standard processing - 1-8MB: Web Workers parallelization - 8MB+: WASM + streaming hybrid - **Near-native performance**
### **Three Rendering Modes** **Default Mode** - Full UI included ```html ``` **Minimal Mode** - Customizable slots ```html
Custom toolbar
Custom table
 ``` **Headless Mode** - Full API control ```html ``` 		### **Rich Data Features** - Drag & drop fields - Dynamic aggregations (sum, avg, count, min, max) - Advanced filtering - Multi-level grouping - Export to PDF, Excel, HTML - Conditional formatting - Custom calculations - Responsive design
--- ## Installation ```bash # npm npm install @mindfiredigital/pivothead-web-component # yarn yarn add @mindfiredigital/pivothead-web-component # pnpm pnpm add @mindfiredigital/pivothead-web-component # CDN (for quick prototyping) ``` ### Browser Requirements - Modern browsers with Web Components support (Chrome 54+, Firefox 63+, Safari 10.1+, Edge 79+) - For older browsers, include the [Web Components polyfill](https://www.webcomponents.org/polyfills) --- ## Quick Start ### Vanilla JavaScript ```html PivotHead Demo ``` ### React Integration ```tsx import { useEffect, useRef } from 'react'; import '@mindfiredigital/pivothead-web-component'; export default function PivotDemo() { const pivotRef = useRef(null); useEffect(() => { if (pivotRef.current) { pivotRef.current.data = salesData; pivotRef.current.options = { rows: ['product'], columns: ['region'], values: ['sales'], }; } }, []); return ; } ``` > **Prefer React?** Use our official React wrapper: [`@mindfiredigital/pivothead-react`](../react) ### Vue Integration ```vue ``` ### Angular Integration ```typescript // app.component.ts import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; import '@mindfiredigital/pivothead-web-component'; @Component({ selector: 'app-root', template: ``, schemas: [CUSTOM_ELEMENTS_SCHEMA], }) export class AppComponent { dataJson = JSON.stringify(salesData); optionsJson = JSON.stringify({ rows: ['product'], columns: ['region'], values: ['sales'], }); } ``` --- ## Rendering Modes Deep Dive ### 1️ Default Mode - Full UI Included Perfect for rapid development with zero configuration. ```html ``` **Includes:** - Pre-built responsive UI - Drag & drop interface - Filtering controls - Pagination - Export buttons - Sorting indicators **Best for**: Admin panels, dashboards, internal tools, rapid prototyping --- ### Minimal Mode - Customizable Slots You control the UI, we handle the data. ```html
``` **Best for**: Custom designs, branded applications, unique UX requirements --- ### Headless Mode - Complete Control Zero UI, maximum flexibility. Build anything on top of the pivot engine. ```html
``` **Best for**: Custom visualizations, D3.js integrations, charting libraries, unique interfaces --- ## WebAssembly Power - Large File Processing ### Automatic Performance Optimization ```html ``` ### Performance Breakdown | File Size | Strategy | Processing Time\* | Memory | | --------- | ---------------- | ----------------- | ------------- | | < 1 MB | JavaScript | ~50ms | Low | | 1-8 MB | Web Workers | ~200ms | Medium | | 8-100 MB | WASM (in-memory) | ~800ms | Medium | | 100MB-1GB | WASM + Streaming | ~3-5s | Low (chunked) | **Key Benefits:** - **Zero configuration** - Automatic mode selection - **Smart memory management** - Chunked processing for large files - **Real-time progress** - Built-in loading indicators - **Fallback support** - Graceful degradation if WASM unavailable --- ## API Reference ### Properties / Attributes | Property | Type | Default | Description | | ------------ | ---------------------------------- | ----------- | --------------------------------------------- | | `mode` | `'default' \| 'minimal' \| 'none'` | `'default'` | Rendering mode | | `data` | `Array \| File \| string` | `[]` | Data source (array, CSV File, or JSON string) | | `options` | `object \| string` | `{}` | Pivot configuration | | `filters` | `object \| string` | `[]` | Active filters | | `pagination` | `object \| string` | `{}` | Pagination settings | ### Methods Access via JavaScript: ```javascript const pivot = document.querySelector('pivot-head'); // State Management pivot.getState() // Get current state pivot.refresh() // Refresh the pivot table pivot.getData() // Get raw data pivot.getProcessedData() // Get processed/grouped data // Configuration pivot.setMeasures([...]) // Update measures pivot.setDimensions([...]) // Update dimensions pivot.setGroupConfig({...}) // Update grouping pivot.setLayout(rows, cols, vals) // Set complete layout // Data Manipulation pivot.sort(field, direction) // Sort by field ('asc' | 'desc') pivot.filter(field, operator, val) // Apply filter pivot.clearFilters() // Remove all filters // Pagination pivot.setPageSize(size) // Set page size pivot.goToPage(pageNum) // Navigate to page pivot.getPagination() // Get pagination state // Export pivot.exportToPDF(fileName) // Export to PDF pivot.exportToExcel(fileName) // Export to Excel pivot.exportToHTML(fileName) // Export to HTML // File Operations (ConnectService) await pivot.connectToLocalCSV() // Open CSV file picker await pivot.connectToLocalJSON() // Open JSON file picker await pivot.connectToLocalFile() // Open file picker (any supported format) ``` ### Events | Event | Detail Type | Description | | ------------- | --------------------------- | ------------------------------------------------------ | | `stateChange` | `PivotTableState` | Emitted on any state change (data, sort, filter, etc.) | | `dataLoaded` | `{ recordCount, fileSize }` | Emitted when file loading completes | | `error` | `{ message, code }` | Emitted on errors | ```javascript pivot.addEventListener('stateChange', event => { const state = event.detail; console.log('Headers:', state.processedData.headers); console.log('Rows:', state.processedData.rows); console.log('Totals:', state.processedData.totals); console.log('Performance mode:', state.performanceMode); }); pivot.addEventListener('dataLoaded', event => { console.log(`Loaded ${event.detail.recordCount} records`); }); ``` ### TypeScript Types ```typescript import type { PivotTableState, PivotTableOptions, FilterConfig, PaginationConfig, } from '@mindfiredigital/pivothead'; interface PivotTableState { data: T[]; processedData: { headers: string[]; rows: any[][]; totals: Record; }; filters: FilterConfig[]; pagination: PaginationConfig; performanceMode?: 'standard' | 'workers' | 'wasm' | 'streaming-wasm'; // ... other properties } ``` --- ## Real-World Examples ### Example 1: Sales Dashboard ```html

Sales Analytics

``` ### Example 2: Minimal Mode with Slots ```html

Company Analytics

 ``` ### Example 3: Real-Time Data Streaming ```html ``` --- ## Related Packages Build pivot tables for any framework: | Package | Description | NPM | Documentation | | ------------------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | **[@mindfiredigital/pivothead](../core)** | Core TypeScript engine | [![npm](https://img.shields.io/npm/v/@mindfiredigital/pivothead)](https://www.npmjs.com/package/@mindfiredigital/pivothead) | [README](../core/README.md) | | **[@mindfiredigital/pivothead-react](../react)** | React wrapper component | - | [README](../react/README.md) | | **[@mindfiredigital/pivothead-vue](../vue)** | Vue wrapper | - | Coming soon | --- ### Contributing We welcome contributions! See our [Contributing Guide](../../CONTRIBUTING.md) to get started. ### Show Your Support If PivotHead helps your project, please consider: - ⭐ [Star the repository](https://github.com/mindfiredigital/PivotHead) --- ## Examples Check out complete working examples in the repository: | Example | Description | Path | | --------------------- | ------------------------------------------ | ------------------------------------------------------------------- | | **Vanilla JS** | Pure JavaScript implementation | [simple-js-demo](../../examples/simple-js-demo) | | **Default Mode** | Full UI with all features | [pivothead-default-demo](../../examples/pivothead-default-demo) | | **Minimal Mode** | Custom rendering with slots | [pivothead-minimal-demo](../../examples/pivothead-minimal-demo) | | **Headless Mode** | Complete control for custom visualizations | [pivothead-none-demo](../../examples/pivothead-none-demo) | | **React Integration** | Using web component in React | [react-web-component-demo](../../examples/react-web-component-demo) | | **Vue Integration** | Using web component in Vue | [vue-example](../../examples/vue-example) | ### Running Examples Locally ```bash # Clone the repository git clone https://github.com/mindfiredigital/PivotHead.git cd PivotHead # Navigate to an example (e.g., simple-js-demo) cd examples/simple-js-demo # Install dependencies pnpm install # Start development server pnpm dev ``` --- ## License MIT © [Mindfiredigital](https://github.com/mindfiredigital) ---
**Built with ❤️ by the [Mindfiredigital](https://www.mindfiredigital.com) team** [GitHub](https://github.com/mindfiredigital/PivotHead) • [NPM](https://www.npmjs.com/package/@mindfiredigital/pivothead-web-component) • [Website](https://www.mindfiredigital.com)