Skip to content
DzGrid

groupZone

Shows the grouping as a band of chips above the rows, which the user can change.

Importimport { groupZone } from '@dzgrid/dom/group-zone';
SignaturegroupZone(o: GroupZoneOptions): GridFeature
Textsimport { EN_GROUP } from '@dzgrid/dom/locales/en-group';
languages: en, fr, ar
Style sheetimport '@dzgrid/theme/grouping.css';
Own CSSZONE_CSS — to add yourself with injectStyles: false
Declared inpackages/dom/src/group-zone/index.ts
OptionsType
use (required){ /** The grouping the chips show and change. */ readonly grouping: { api(grid: Grid): GroupingApiLike | null }; /** Moving columns (`columns()`): a header dragged onto the band groups by it. Absent: no drop (the menu and the keys still work). */ readonly columns?: { api(grid: Grid): { readonly dropTargets: { add(el: Element, t: { accept(column: string): boolean; drop(column: string): void; readonly label?: string }): () => void } } | null } }
texts'pivot'

What it does

Section titled “What it does”

groupZone({ use }) adds a band above the rows. Empty, it reads « Drag a column here to group ». Each grouping column shows as a chip with its name and a × button, in grouping order. A header dragged onto the band groups by its column; × or Delete removes one; Ctrl+Shift+← → or a mouse drag moves one; each change is said. The band is one tab stop: the arrows move between its items, mirrored in Arabic.

It drives the grouping() given in use.grouping, through its API; that feature must be in the grid too. The header drop needs columns() in use.columns: without it, there is no drop, but « Group by this column » in the column menu and the keys still work. A column with groupable: false cannot be dropped and shows no chip. A dropped column stays visible.

Its texts (the -group bundle) are required: an error names any missing key. Beside a pivot, use pivotBar() instead.

Options

Section titled “Options”
  • use (required): grouping, the feature whose columns the band shows and changes; columns, optional, the column moves that let a header be dropped on it.
  • texts: 'pivot' reads the pivot’s texts (pivot.label, pivot.empty…) instead of zone.*, for a second band that holds the pivot columns.

Read when the grid is made.

Example

Section titled “Example”
import { createGrid, type GridMessages } from '@dzgrid/dom';
import { grouping } from '@dzgrid/dom/grouping';
import { groupZone } from '@dzgrid/dom/group-zone';
import { columns } from '@dzgrid/dom/columns';
import { EN } from '@dzgrid/dom/locales/en';
import { EN_GROUP } from '@dzgrid/dom/locales/en-group';
import { EN_COLUMNS } from '@dzgrid/dom/locales/en-columns';
import '@dzgrid/theme/grouping.css';
import '@dzgrid/theme/columns.css';


type Packet = { id: string; kind: string; colour: string; name: string; packets: number };


const messages: GridMessages = { ...EN, text: { ...EN.text, ...EN_GROUP.text, ...EN_COLUMNS.text } };
const groups = grouping({ by: ['kind'] });
const moves = columns();


createGrid<Packet>(document.getElementById('packets')!, {
  rows: [{ id: 'p1', kind: 'Herb', colour: 'Green', name: 'Basil', packets: 40 }],
  columns: [
    { id: 'kind', header: 'Kind' },
    { id: 'colour', header: 'Colour' },
    { id: 'name', header: 'Seed', groupable: false },
    { id: 'packets', header: 'Packets', type: 'number', aggFunc: 'sum' },
  ],
  getRowId: (p) => p.id,
  messages,
  features: [moves, groups, groupZone({ use: { grouping: groups, columns: moves } })],
});

Live demo

Section titled “Live demo”

Drag the Colour title into the band above the titles; × on a chip removes it.

See also

Section titled “See also”