Pivot Table

Demo & usage

More examples

When to use

• Summarizing a flat dataset by one or more dimensions, with grand totals and subtotals.
• You want the end user to reconfigure what's being summarized (drag fields, not a form).
• For row grouping without cross-tab columns or aggregators, the Data Table's grouping is lighter weight.

Async states

• loading
• empty
• error
• retry

Item identity & owned state

Restorable state

• collapsedIds

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Saved state

Stored kinds

• sv-pivot-table/view

What you will find under your own storage key. You choose the key; the blob names its own kind and schema version, so a component never reads state another one wrote.

Reading it back

Restore through the component's own restore… helper rather than casting the parsed JSON. A blob from an older release is migrated where it can be and refused with a reason where it cannot — so an upgrade never silently applies last month's shape to this month's fields.

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `data`, `loading` and `error`.
• `serverSide` switches **off** the built-in filtering, sorting and paging. Leave it false and the component works entirely from the array you pass — which is what you want for a few hundred rows.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Six aggregators (sum, average, count, min, max, distinct count) and five number formats (general, integer, decimal, currency, percent). Every subtotal is the aggregator applied to that group's own source rows, so an average is a true average and a distinct count is a true distinct count — never a roll-up of the numbers on the rows beneath.
• Sort any row level by a measure, ascending or descending.
• Top-N filters the outermost row groups by a measure's total.
• Excel/PDF export serializes exactly what's on screen — collapsed groups stay collapsed, the label column and Grand Total row are always present because the grid always draws them, and each measure's format carries across. XLSX keeps true numeric cells (with the format as a real Excel number format, so host formulas still work) while PDF takes the formatted strings, because a picture of the grid that reads `0.42` where the screen reads `42.0%` is the wrong picture.
• `maxAxisGroups` (default 1000) caps how many groups either axis may render. Past it the grid is replaced by a notice naming the axis, its group count and the widest field responsible, with a "Render it anyway" waiver that is re-armed as soon as the axes change again. `0` switches the guard off; `serverSide` skips it, since the host is already deciding what to aggregate.

Best practices

• Do: Mark numeric fields with `numeric: true` in `SvPivotField` — it drives the drag-drop default aggregator guess (sum vs. count).
• Do: Pair `serverSide` with a real aggregation endpoint once the source dataset is too large to pivot client-side — the same `buildPivot()` engine runs unchanged on the server.
• Tip: Bind `[(config)]` (two-way) to persist a user's layout, same as `data-table`'s saved column state.
• Do: Lower `maxAxisGroups` (default 1000) for embedded or mobile hosts, and raise it only when you know the dimensions are bounded. The guard counts groups without building the pivot, so it costs nothing on a config that stays under the limit.
• Don't: Don't offer a per-record identifier (`orderId`, `email`) as a dimension field at all if you can help it — grouping by it produces one row per record, which is the source table, not a summary. As a measure with `countDistinct` it answers the question the user actually had.

Accessibility

• The grid IS a `<table>`, so it gets no second off-screen copy — a companion summary here would read every figure twice. What it gets instead is its own semantics: an `sr-only` `<caption>` naming the fields in play rather than counting them, `scope="col"`/`scope="row"` on both header axes, and a Grand Total row that is a row header, not a stray cell.
• The row hierarchy is in the accessible name, not the indent. Nesting reached the page as `padding-left` alone, so "West" and "West → Seattle" announced identically; each row header now carries its branch.
• The scroll container is a labelled `role="region"` with `tabindex="0"`. A scrollable box is a keyboard tab stop whether or not you name it, and an unnamed stop announces as nothing at all.
• Expand/collapse buttons expose `aria-expanded` and a computed label ("Expand West" / "Collapse West").
• Drag is one path, not the path. Native HTML5 drag is reachable by pointer only — not keyboard, not switch access, not voice control — so every field carries a zone menu naming where it sits (Unused / Rows / Columns / Values) and every placed field carries move buttons for its position. Order is not decoration here: `rows` order IS the nesting order, so a configurator without reorder could only express the arrangement the fields happened to be dropped in. Focus follows the field across the re-render, because a zone change destroys the control that triggered it.
• Every value cell carries a `title` naming the measure, the row path and the column it came from, and marks a subtotal as one — the sighted answer to "is this a subtotal, and of what", which a grid of bare numbers cannot give. It is deliberately not an `aria-label`: on a `<td>` that REPLACES the cell's own content, and the `scope` headers already carry the association.
• Loading, error and empty states follow the kit-wide async contract (`data-sv-state`). A pivot blocked by `maxAxisGroups` is not one of them — it has too much data, not none, so it gets a `role="status"` notice that keeps the configurator on screen rather than an empty shell that would hide the only way out.