pivotBar

Draws one bar above the rows where the user builds the pivot table.

Import	import { pivotBar } from '@dzgrid/dom/pivot-bar';
Signature	pivotBar(o: PivotBarOptions): GridFeature
Texts	import { EN_PIVOT_BAR } from '@dzgrid/dom/locales/en-pivot-bar'; languages: en, fr, ar
Style sheet	import '@dzgrid/theme/pivot.css';
Own CSS	PIVOT_BAR_CSS — to add yourself with injectStyles: false
Declared in	packages/dom/src/pivot-bar/index.ts

Options	Type
use (required)	{ /** The row grouping (`grouping({ pivot })`): the « Lignes » part. */ readonly grouping: { api(grid: Grid): { by(): readonly string[]; setBy(by: readonly string[], o?: { readonly user?: boolean }): void } | null }; /** The pivot handed to that grouping: the « Colonnes » and « Valeurs » parts. */ readonly pivot: { api(grid: Grid): PivotApi | null }; /** Moving columns (`columns()`): a header dropped on a part adds its column there. */ readonly columns?: { api(grid: Grid): { readonly dropTargets: { add(el: Element, t: { accept(column: string): boolean; drop(column: string): void; readonly label?: string }): () => void } } | null } }
panel	boolean

What it does

pivotBar({ use }) draws one strip above the rows with three named parts: « Rows » (the grouping columns), « Columns » (the pivot columns) and « Values ». Each part is a toolbar of chips with the keys and moves of groupZone(): × or Delete removes, Ctrl+Shift+← → moves within the part, « + » lists the columns the part accepts (the way without dragging). Ctrl+Shift+↑ ↓, or a chip dropped on another part, moves a column to the previous or next part; a part that refuses it says so.

A value’s chip, such as « sum(Takings) », opens a menu of the functions that fit its column. A pivot column’s chip has an order button (↑ or ↓) that reverses its created columns. With columns() in use.columns, a header dropped on a part adds its column there. When the bar is 30 rem wide or less, the parts stack. With columnsChooser(), the columns panel starts with a « Pivot mode » switch and the same three parts.

It needs the grouping() and the pivot() given in use. Its texts come from three bundles, -pivot-bar, -pivot and -group; an error names any missing key. Use it instead of groupZone() beside a pivot.

Options

• use (required): grouping, the row grouping (« Rows »); pivot, the pivot given to that grouping (« Columns » and « Values »); columns, optional, so a header can be dropped on a part.
• panel: the « Pivot mode » switch and the three parts at the top of the columns panel, with columnsChooser(). On by default.

Read when the grid is made.

Example

import { createGrid, type GridMessages } from '@dzgrid/dom';
import type { ColumnOrGroup } from '@dzgrid/core';
import { grouping } from '@dzgrid/dom/grouping';
import { pivot } from '@dzgrid/dom/pivot';
import { pivotBar } from '@dzgrid/dom/pivot-bar';
import { spans } from '@dzgrid/dom/spans';
import { columns } from '@dzgrid/dom/columns';
import { EN } from '@dzgrid/dom/locales/en';
import { EN_GROUP } from '@dzgrid/dom/locales/en-group';
import { EN_PIVOT } from '@dzgrid/dom/locales/en-pivot';
import { EN_PIVOT_BAR } from '@dzgrid/dom/locales/en-pivot-bar';
import { EN_COLUMNS } from '@dzgrid/dom/locales/en-columns';
import '@dzgrid/theme/grouping.css';
import '@dzgrid/theme/pivot.css';
import '@dzgrid/theme/columns.css';

type Sale = { id: string; shop: string; month: string; bread: string; loaves: number; takings: number };

const cols: ColumnOrGroup<Sale>[] = [
  { id: 'shop', header: 'Bakery' },
  { id: 'month', header: 'Month' },
  { id: 'bread', header: 'Bread' },
  { id: 'loaves', header: 'Loaves', type: 'number' },
  { id: 'takings', header: 'Takings', type: 'number', numberFormat: { style: 'currency', currency: 'EUR', maximumFractionDigits: 0 } },
];
const messages: GridMessages = {
  ...EN,
  text: { ...EN.text, ...EN_GROUP.text, ...EN_PIVOT.text, ...EN_PIVOT_BAR.text, ...EN_COLUMNS.text },
};

const cross = pivot({ columns: ['month'], values: { takings: 'sum' } });
const rowsBy = grouping({ by: ['shop'], pivot: cross });
const moves = columns();
createGrid<Sale>(document.getElementById('bakeries')!, {
  rows: [{ id: 'b1', shop: 'Mill Street', month: '2026-01', bread: 'Rye', loaves: 120, takings: 360 }],
  columns: cols,
  getRowId: (s) => s.id,
  messages,
  features: [spans(), moves, rowsBy, pivotBar({ use: { grouping: rowsBy, pivot: cross, columns: moves }, panel: false })],
});

Live demo

In the bar above the grid, + under Columns adds Bread as a second band; a value’s chip changes its function.

See also

• pivot(): the table the bar builds.
• groupZone(): the band for grouping alone.
• The Pivot guide.