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';

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

Configuration Options

Option	Type	Description
groupOn?	(row: any) => any	Callback to determine group path for a row. Return an array of group keys, a single key, null/false to skip grouping.
groups?	GroupDefinition[]	Pre-defined group structure for server-side grouping.
defaultExpanded?	DefaultExpandedValue	Default expanded state for group rows. - true: Expand all groups initially - false: Collapse all groups initially (default) - number: Expand group at this index (0-based) - string: Expand group with this key (composite key format: “parent
groupRowRenderer?	(params: GroupRowRenderParams) => string | void | HTMLElement	Custom group row renderer - takes full control of group row rendering
showRowCount?	boolean	Show row count in group headers (default: true)
indentWidth?	number	Indent width per depth level in pixels (default: 20)
aggregators?	AggregatorMap	Aggregators for group row cells by field name
formatLabel?	(value: any, depth: number, key: string) => string	Custom format function for group label
fullWidth?	boolean	Whether to render group row as full-width spanning cell (default: true)
animation?	ExpandCollapseAnimation	Animation style for expanding/collapsing groups. - false: No animation - 'slide': Slide animation (default) - 'fade': Fade animation
accordion?	boolean	Accordion mode - only one group can be expanded at a time. Expanding a group will automatically collapse all other groups at the same depth.
groupRowHeight?	number	Height of group header rows in pixels. Used by the variable row height system to provide consistent heights for group rows without needing to measure them.

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.

Properties

Property	Type	Description
dependencies	object[]	Optional dependency on MultiSort for coordinated sort management. When MultiSort is loaded, GroupingRows queries its sort model to determine group header ordering. Without it, falls back to core sort state.

Methods

detect()

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

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

Parameters

Name	Type	Description
rows	readonly any[]
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

---

setGroups()

Replace auto-detected groups with an externally provided group structure.

When groups are set, the plugin switches to pre-defined mode — groupOn is ignored and the plugin renders the provided group headers instead. Row data for each group must be populated via setGroupRows.

setGroups(groups: GroupDefinition[]): void

Parameters

Name	Type	Description
groups	GroupDefinition[]	Array of group definitions, or empty array to clear

---

getGroups()

Get the current pre-defined group structure.

Returns the groups set via setGroups, received from datasource:data, or the groups config array. Returns an empty array when using groupOn-based grouping.

getGroups(): GroupDefinition[]

Returns

GroupDefinition[] - Current group definitions

---

setGroupRows()

Populate row data for an expanded group.

Call this in response to a group-expand event after fetching rows from the server. The plugin will re-render to show the rows.

When ServerSidePlugin is loaded, this is handled automatically via datasource:children events — you only need this for the imperative API.

setGroupRows(groupKey: string, rows: unknown[]): void

Parameters

Name	Type	Description
groupKey	string	The group key to populate
rows	unknown[]	The row data for this group

---

setGroupLoading()

Toggle loading indicator for a group.

When loading is true, the group shows a loading spinner instead of row data. Call with false after rows are loaded (also cleared by setGroupRows).

setGroupLoading(groupKey: string, loading: boolean): void

Parameters

Name	Type	Description
groupKey	string	The group key
loading	boolean	Whether the group is loading

---

clearGroupRows()

Clear cached row data for one or all groups.

Use when the server data has changed and groups need to be re-fetched on next expand.

clearGroupRows(groupKey: string): void

Parameters

Name	Type	Description
groupKey	string	Specific group key to clear, or omit to clear all

---