# svelte-pivottable `svelte-pivottable` is a Svelte 5 pivot table library with drag-and-drop data exploration, grouping, and subtotals — similar to the pivot table experience in older versions of Microsoft Excel. It is a Svelte port of [react-pivottable-grouping](https://github.com/jjagielka/react-pivottable-grouping), itself a fork of [react-pivottable](https://react-pivottable.js.org/) by [Nicolas Kruchten](https://github.com/nicolaskruchten), which is a React port of his jQuery-based [PivotTable.js](https://pivottable.js.org/). ## What does it do? `svelte-pivottable` lets you summarize a dataset into a cross-tabulated table or a [Plotly.js](https://plot.ly/javascript/) chart using a drag-and-drop interface. You can move attributes between rows, columns, filters, and aggregation slots interactively. A [live demo is available here](https://jjagielka.github.io/svelte-pivottable-demo/). ![screencap](https://raw.githubusercontent.com/jjagielka/react-pivottable-grouping/master/examples/basic.gif) ## Installation ``` npm install svelte-pivottable ``` ## Basic usage ### Interactive UI with table output `PivotTableUI` is the full drag-and-drop component. It manages its own UI state but delegates data rendering to `PivotTable`. ```svelte ``` Data can also be provided as an array of arrays (first row is headers): ```svelte ``` ### Non-interactive snapshot rendering `PivotTable` renders a saved configuration without any drag-and-drop UI. Use it for embedding fixed pivot views in dashboards. ```svelte ``` ## Renderers ### Table renderers `TableRenderers` is the default renderer set. Import it from `svelte-pivottable` or the `svelte-pivottable/TableRenderers` subpath. | Key | Description | |-----|-------------| | `Table` | Plain cross-tabulation table | | `Table Heatmap` | Table with full color scale across all cells | | `Table Col Heatmap` | Heatmap scaled per column | | `Table Row Heatmap` | Heatmap scaled per row | | `TsvExport` | Tab-separated values export view | ```svelte ``` ### Plotly renderers Plotly.js is injected as a dependency to avoid mandatory bundling. Pass the Plotly object to `PlotlyRenderers()` to get the renderer map. ```svelte ``` If you load Plotly via a ` ``` ## Aggregators ### Built-in aggregators The `aggregators` export is a ready-to-use map of aggregation functions. Pass it (or a subset) to `PivotTableUI` via the `aggregators` prop, or use individual entries as the `aggregator` prop on `PivotTable`. ```svelte ``` Available built-in aggregators: | Key | Description | |-----|-------------| | `Count` | Number of records | | `Count Unique Values` | Number of distinct values | | `List Unique Values` | Comma-separated distinct values | | `Sum` | Sum of a numeric field | | `Integer Sum` | Sum formatted as integer | | `Average` | Mean | | `Median` | Median | | `Sample Variance` | Sample variance | | `Sample Standard Deviation` | Sample standard deviation | | `Minimum` | Minimum value | | `Maximum` | Maximum value | | `First` | First value seen | | `Last` | Last value seen | | `Sum over Sum` | Ratio of two sums | | `Sum as Fraction of Total` | Each cell as % of grand total | | `Sum as Fraction of Rows` | Each cell as % of its row total | | `Sum as Fraction of Columns` | Each cell as % of its column total | | `Count as Fraction of Total` | Count as % of grand total | | `Count as Fraction of Rows` | Count as % of row total | | `Count as Fraction of Columns` | Count as % of column total | ### Limiting the aggregator dropdown Pass a subset of `aggregators` to restrict what appears in the UI: ```svelte ``` ### Custom aggregators with `aggregatorTemplates` Use `aggregatorTemplates` as building blocks for your own aggregation logic: ```svelte ``` ## Derived attributes Use `derivedAttributes` to compute new fields on the fly without modifying the source data. The built-in `derivers` helper provides common patterns: ```svelte ``` ## Sorting ### Custom sort order with `sortAs` Use `sortAs` to enforce a fixed value ordering (e.g. month names, priority levels): ```svelte ``` ## Grouping and subtotals Set `grouping={true}` to display hierarchical row and column groups with subtotals at each level. This is the main feature added over the original `react-pivottable`. ```svelte ``` | Prop | Type | Default | Description | |------|------|---------|-------------| | `grouping` | `boolean` | `false` | Enable hierarchical grouping with subtotals | | `compactRows` | `boolean` | `true` | Render row group headers inline rather than as separate rows | | `rowGroupBefore` | `boolean` | `true` | Show row subtotals above their children | | `colGroupBefore` | `boolean` | `false` | Show column subtotals to the left of their children | ## All properties The component stack passes props downward: `PivotTableUI → PivotTable → Renderer → PivotData`. | Layer | Prop | Type | Default | Description | |-------|------|------|---------|-------------| | `PivotData` | `data` | array or function | *(required)* | Dataset to summarize — see [accepted formats](#accepted-formats-for-data) | | `PivotData` | `rows` | `string[]` | `[]` | Attribute names to pre-populate in the row area | | `PivotData` | `cols` | `string[]` | `[]` | Attribute names to pre-populate in the column area | | `PivotData` | `vals` | `string[]` | `[]` | Attribute names passed to the aggregator function | | `PivotData` | `aggregator` | function | `aggregators['Count']` | Aggregation function (see `aggregators`) | | `PivotData` | `valueFilter` | `Record>` | `{}` | Values to exclude per attribute; populates the filter menus | | `PivotData` | `sorters` | object or function | `{}` | Per-attribute sort functions; defaults to natural sort | | `PivotData` | `rowOrder` | `string` | `"key_a_to_z"` | Row sort order: `key_a_to_z`, `value_a_to_z`, or `value_z_to_a` | | `PivotData` | `colOrder` | `string` | `"key_a_to_z"` | Column sort order: `key_a_to_z`, `value_a_to_z`, or `value_z_to_a` | | `PivotData` | `derivedAttributes` | object of functions | `{}` | Functions that add computed fields to each record | | `PivotData` | `grouping` | `boolean` | `false` | Enable subtotal rows and columns | | `PivotData` | `rowGroupBefore` | `boolean` | `true` | Place row subtotals above their group | | `PivotData` | `colGroupBefore` | `boolean` | `false` | Place column subtotals to the left of their group | | `PivotTable` | `renderers` | object | `TableRenderers` | Map of renderer name → Svelte component | | `PivotTable` | `rendererName` | `string` | first key in `renderers` | Which renderer to use | | `PivotTableUI` | `aggregators` | object | `aggregators` from Utilities | Map of aggregator name → function, shown in the dropdown | | `PivotTableUI` | `aggregatorName` | `string` | first key in `aggregators` | Which aggregator to use initially | | `PivotTableUI` | `hiddenAttributes` | `string[]` | `[]` | Attributes to hide from the entire UI | | `PivotTableUI` | `hiddenFromAggregators` | `string[]` | `[]` | Attributes to hide from the aggregator field picker | | `PivotTableUI` | `hiddenFromDragDrop` | `string[]` | `[]` | Attributes to hide from the drag-and-drop zone | | `PivotTableUI` | `menuLimit` | `number` | `500` | Maximum number of values to show in a filter menu | | `PivotTableUI` | `unusedOrientationCutoff` | `number` | `85` | Total character length of attribute names above which unused attributes are shown vertically instead of horizontally. `0` = always vertical, `Infinity` = always horizontal | | `PivotTableUI` | `compactRows` | `boolean` | `true` | Compact rendering for grouped row headers | ## Accepted formats for `data` ### Array of objects ```js const data = [ { attr1: 'value1', attr2: 'value2' }, { attr1: 'value3', attr2: 'value4' }, ]; ``` ### Array of arrays First row is treated as headers. Compatible with CSV parser output (e.g. PapaParse). ```js const data = [ ['attr1', 'attr2'], ['value1', 'value2'], ['value3', 'value4'], ]; ``` ### Callback function The function receives a record callback and calls it once per record. Useful for streaming or lazy data sources. ```js const data = (callback) => { callback({ attr1: 'value1', attr2: 'value2' }); callback({ attr1: 'value3', attr2: 'value4' }); }; ``` Missing attributes and `null` values are treated as the string `"null"` in all formats. ## Component architecture ``` PivotTableUI — stateful drag-and-drop UI └─ PivotTable — stateless renderer selector └─ Renderer — TableRenderer, PlotlyRenderer, TSVExportRenderer, etc. └─ PivotData — aggregation, filtering, sorting, subtotal tree ``` ## License MIT