GroupingColumnsPlugin

Column Grouping Plugin for tbw-grid

Enables visual grouping of columns under shared headers. Supports two approaches: declarative columnGroups at the grid level, or inline group property on columns.

Installation

import { GroupingColumnsPlugin } from '@toolbox-web/grid/plugins/grouping-columns';

Grid Config: columnGroups

Property	Type	Description
id	string	Unique group identifier
header	string	Display label for the group header
children	string[]	Array of column field names in this group

Column Config: group

Type	Description
string	Simple group ID (used as both id and label)
{ id: string; label?: string }	Group object with explicit id and optional label

Configuration Options

Option	Type	Description
columnGroups?	ColumnGroupDefinition[]	Declarative column group definitions. When provided here, takes precedence over gridConfig.columnGroups.
groupHeaderRenderer?	(params: GroupHeaderRenderParams) => string | void | HTMLElement	Group header renderer called for each column group. Receives the group’s id, label, and columns in the params, so a single function can handle all groups or differentiate per group via params.id.
showGroupBorders?	boolean	Whether to show group borders (default: true)
lockGroupOrder?	boolean	Prevent columns from being reordered outside their group. When enabled, column moves that would break group contiguity are blocked. Works with both header drag-and-drop and visibility panel drag-and-drop.

Examples

Declarative columnGroups (Recommended)

import '@toolbox-web/grid';
import { GroupingColumnsPlugin } from '@toolbox-web/grid/plugins/grouping-columns';

grid.gridConfig = {
  columnGroups: [
    { id: 'personal', header: 'Personal Info', children: ['firstName', 'lastName', 'email'] },
    { id: 'work', header: 'Work Info', children: ['department', 'title', 'salary'] },
  ],
  columns: [
    { field: 'firstName', header: 'First Name' },
    { field: 'lastName', header: 'Last Name' },
    // ...
  ],
  plugins: [new GroupingColumnsPlugin()],
};

Inline group Property

grid.gridConfig = {
  columns: [
    { field: 'firstName', header: 'First Name', group: { id: 'personal', label: 'Personal Info' } },
    { field: 'lastName', header: 'Last Name', group: 'personal' }, // string shorthand
  ],
  plugins: [new GroupingColumnsPlugin()],
};

See Also

• GroupingColumnsConfig for all configuration options
• ColumnGroup for the group structure
• ReorderPlugin for drag-to-reorder within groups

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Methods

detect()

Auto-detect column groups from column configuration. Detects both inline column.group properties and declarative columnGroups config.

static detect(rows: readonly any[], config: any): boolean

Parameters

Name	Type	Description
rows	readonly any[]
config	any

---

isGroupingActive()

Check if column groups are active.

isGroupingActive(): boolean

Returns

boolean - Whether grouping is active

---

getGroups()

Get the computed column groups.

getGroups(): ColumnGroup<any>[]

Returns

ColumnGroup<any>[] - Array of column groups

---

getGroupColumns()

Get columns in a specific group (aggregated across all fragments).

getGroupColumns(groupId: string): ColumnConfig<any>[]

Parameters

Name	Type	Description
groupId	string	The group ID to find

Returns

ColumnConfig<any>[] - Array of columns in the group

---

refresh()

Refresh column groups (recompute from current columns).

refresh(): void

---