GroupingRowsPlugin

Row Grouping Plugin for tbw-grid

Organizes rows into collapsible hierarchical groups. Perfect for organizing data by category, department, status, or any other dimension—or even multiple dimensions for nested grouping. Includes aggregation support for summarizing group data.

Installation

import { GroupingRowsPlugin } from '@toolbox-web/grid/plugins/grouping-rows';

Configuration Options

Option	Type	Default	Description
groupOn	(row) => string[]	-	Callback returning group path array
defaultExpanded	`boolean \	number \	string \
showRowCount	boolean	true	Show row count in group header
indentWidth	number	20	Indentation per level (pixels)
fullWidth	boolean	true	Group row spans full width
animation	`false \	‘slide’ \	‘fade’`
accordion	boolean	false	Only one group open at a time

Programmatic API

Method	Signature	Description
expandGroup	(path: string[]) => void	Expand a specific group
collapseGroup	(path: string[]) => void	Collapse a specific group
expandAll	() => void	Expand all groups
collapseAll	() => void	Collapse all groups
isGroupExpanded	(path: string[]) => boolean	Check if group is expanded
getGroupState	() => GroupState	Get current grouping state

CSS Custom Properties

Property	Default	Description
--tbw-group-indent-width	1.25em	Indentation per group level
--tbw-grouping-rows-bg	var(--tbw-color-panel-bg)	Group row background
--tbw-grouping-rows-count-color	var(--tbw-color-fg-muted)	Count badge color
--tbw-animation-duration	200ms	Expand/collapse animation

Examples

Single-Level Grouping by Department

import { queryGrid } from '@toolbox-web/grid';
import { GroupingRowsPlugin } from '@toolbox-web/grid/plugins/grouping-rows';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Employee' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'currency' },
  ],
  plugins: [
    new GroupingRowsPlugin({
      groupOn: (row) => [row.department],
      showRowCount: true,
      defaultExpanded: false,
    }),
  ],
};

Multi-Level Grouping

new GroupingRowsPlugin({
  groupOn: (row) => [row.region, row.department, row.team],
  indentWidth: 24,
  animation: 'slide',
})

See Also

• GroupingRowsConfig for all configuration options
• GroupState for the group state structure

Extends BaseGridPlugin

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

Methods

detect()

Auto-detect grouping configuration from grid config. Called by plugin system to determine if plugin should activate.

static detect(rows: unknown, config: any): boolean

Parameters

Name	Type	Description
rows	unknown
config	any

---

expandAll()

Expand all groups.

expandAll(): void

---

collapseAll()

Collapse all groups.

collapseAll(): void

---

toggle()

Toggle expansion of a specific group. In accordion mode, expanding a group will collapse all sibling groups.

toggle(key: string): void

Parameters

Name	Type	Description
key	string	The group key to toggle

---

isExpanded()

Check if a specific group is expanded.

isExpanded(key: string): boolean

Parameters

Name	Type	Description
key	string	The group key to check

Returns

boolean - Whether the group is expanded

---

expand()

Expand a specific group.

expand(key: string): void

Parameters

Name	Type	Description
key	string	The group key to expand

---

collapse()

Collapse a specific group.

collapse(key: string): void

Parameters

Name	Type	Description
key	string	The group key to collapse

---

getGroupState()

Get the current group state.

getGroupState(): GroupState

Returns

GroupState - Group state information

---

getRowCount()

Get the total count of visible rows (including group headers).

getRowCount(): number

Returns

number - Number of visible rows

---

refreshGroups()

Refresh the grouped row model. Call this after modifying groupOn or other config options.

refreshGroups(): void

---

getExpandedGroups()

Get current expanded group keys.

getExpandedGroups(): string[]

Returns

string[] - Array of expanded group keys

---

getFlattenedRows()

Get the flattened row model.

getFlattenedRows(): RenderRow[]

Returns

RenderRow[] - Array of render rows (groups + data rows)

---

isGroupingActive()

Check if grouping is currently active.

isGroupingActive(): boolean

Returns

boolean - Whether grouping is active

---

setGroupOn()

Set the groupOn function dynamically.

setGroupOn(fn: (row: any) => any | undefined): void

Parameters

Name	Type	Description
fn	(row: any) => any | undefined	The groupOn function or undefined to disable

---