GridConfig

Grid configuration for Angular applications.

Extends the base GridConfig to use Angular-augmented ColumnConfig and TypeDefault. This allows component classes as renderers/editors.

Example

import type { GridConfig, ColumnConfig } from '@toolbox-web/grid-angular';

const config: GridConfig<Employee> = {
  columns: [...],
  plugins: [...],
};

Properties

Property	Type	Description
`rowClass?`	`(row: TRow) => string \| string[]`	Dynamic CSS class(es) for data rows. Called for each row during rendering. Return class names to add to the row element.
`fitMode?`	`FitMode`	Sizing mode for columns. Can also be set via `fitMode` prop.
`sortable?`	`boolean`	Grid-wide sorting toggle. When false, disables sorting for all columns regardless of their individual `sortable` setting. When true (default), columns with `sortable: true` can be sorted.
`resizable?`	`boolean`	Grid-wide resizing toggle. When false, disables column resizing for all columns regardless of their individual `resizable` setting. When true (default), columns with `resizable: true` (or resizable not set, since it defaults to true) can be resized.
`rowHeight?`	`number \| (row: TRow, index: number) => number \| undefined`	Row height in pixels for virtualization calculations. The virtualization system assumes uniform row heights for performance.
`plugins?`	`GridPlugin[]`	Array of plugin instances. Each plugin is instantiated with its configuration and attached to this grid.
`features?`	`Partial<FeatureConfig<TRow>>`	Declarative feature configuration. Alternative to manually creating plugin instances in `plugins`. Features are resolved using the core feature registry.
`columnState?`	`GridColumnState`	Saved column state to restore on initialization. Includes order, width, visibility, sort, and plugin-contributed state.
`shell?`	`ShellConfig`	Shell configuration for header bar and tool panels. When configured, adds an optional wrapper with title, toolbar, and collapsible side panels.
`icons?`	`GridIcons`	Grid-wide icon configuration.
`animation?`	`AnimationConfig`	Grid-wide animation configuration. Controls animations for expand/collapse, reordering, and other visual transitions. Individual plugins can override these defaults in their own config.
`sortHandler?`	`SortHandler<TRow>`	Custom sort handler for the entire grid.
`initialSort?`	`object`	Initial sort state applied when the grid first renders.
`getRowId?`	`(row: TRow) => string`	Function to extract a unique identifier from a row. Used by `updateRow()`, `getRow()`, and ID-based tracking.
`gridAriaLabel?`	`string`	Accessible label for the grid. Sets `aria-label` on the grid’s internal table element for screen readers.
`gridAriaDescribedBy?`	`string`	ID of an element that describes the grid. Sets `aria-describedby` on the grid’s internal table element.
`a11y?`	`A11yConfig`	Accessibility configuration for screen reader announcements.
`editOn?`	`false \| click \| dblclick \| manual`	Edit trigger mode. Requires `EditingPlugin` to be loaded.
`rowEditable?`	`(row: TRow) => boolean`	Row-level editability gate. Requires `EditingPlugin` to be loaded.
`filterable?`	`boolean`	Grid-wide filtering toggle. Requires `FilteringPlugin` to be loaded.
`columnGroups?`	`ColumnGroupDefinition[]`	Declarative column group definitions for the GroupingColumnsPlugin. Each group specifies an id, header label, and array of column field names. The plugin will automatically assign the `group` property to matching columns.
`selectable?`	`boolean`	Grid-wide selection toggle. Requires `SelectionPlugin` to be loaded.
`columns?`	`ColumnConfig<TRow>[]`
`typeDefaults?`	`Record<string, TypeDefault<TRow>>`	Type-level defaults that can use Angular component classes
`loadingRenderer?`	`Type<unknown> \| LoadingRenderer`	Custom loading renderer - can be: - A function `(ctx: LoadingContext) => HTMLElement

Property Details

rowClass

// Highlight inactive rows
rowClass: (row) => row.active ? [] : ['inactive', 'dimmed']

// Status-based row styling
rowClass: (row) => [`priority-${row.priority}`]

// Single class as string
rowClass: (row) => row.isNew ? 'new-row' : ''

sortable

Grid-wide sorting toggle. When false, disables sorting for all columns regardless of their individual sortable setting. When true (default), columns with sortable: true can be sorted.

This affects:

Header click handlers for sorting
Sort indicator visibility
Multi-sort plugin behavior (if loaded)

Default: true

// Disable all sorting
gridConfig = { sortable: false };

// Enable sorting (default) - individual columns still need sortable: true
gridConfig = { sortable: true };

resizable

Grid-wide resizing toggle. When false, disables column resizing for all columns regardless of their individual resizable setting. When true (default), columns with resizable: true (or resizable not set, since it defaults to true) can be resized.

This affects:

Resize handle visibility in header cells
Double-click to auto-size behavior

Default: true

// Disable all column resizing
gridConfig = { resizable: false };

// Enable resizing (default) - individual columns can opt out with resizable: false
gridConfig = { resizable: true };

rowHeight

Row height in pixels for virtualization calculations. The virtualization system assumes uniform row heights for performance.

If not specified, the grid measures the first rendered row’s height, which respects the CSS variable --tbw-row-height set by themes.

Set this explicitly when:

Row content may wrap to multiple lines (also set --tbw-cell-white-space: normal)
Using custom row templates with variable content
You want to override theme-defined row height
Rows have different heights based on content (use function form)

Variable Row Heights: When a function is provided, the grid enables variable height virtualization. Heights are measured on first render and cached by row identity.

Default: Auto-measured from first row (respects --tbw-row-height CSS variable)

// Fixed height for all rows
gridConfig = { rowHeight: 56 };

// Variable height based on content
gridConfig = {
  rowHeight: (row, index) => row.hasDetails ? 80 : 40,
};

// Return undefined to trigger DOM auto-measurement
gridConfig = {
  rowHeight: (row) => row.isExpanded ? undefined : 40,
};

plugins

plugins: [
  new SelectionPlugin({ mode: 'range' }),
  new MultiSortPlugin(),
  new FilteringPlugin({ debounceMs: 150 }),
]

sortHandler

Custom sort handler for the entire grid.

Prefer BaseColumnConfig.sortComparator over sortHandler.

sortHandler is a low-level escape hatch with significant limitations:

Only consulted by the single-column sort path (core header click, TreePlugin per-level sort, ServerSidePlugin sortMode: 'local').
Bypassed entirely when MultiSortPlugin is loaded.
Owns ALL columns at once — your handler must implement field/direction dispatch and null handling for every sortable column itself.

For per-column custom sort logic, use BaseColumnConfig.sortComparator instead. It is honored by every sort code path in the grid (core, multi-sort, tree, server-side) and is composable across columns.

For server-side sort, prefer ServerSideConfig.dataSource — the sortModel is shipped to your getRows handler so the backend can return pre-sorted blocks.

Use sortHandler only when you need to replace the grid’s sort engine wholesale (e.g. integrating a third-party sort library that operates on the full row array, or routing every sort through a single async pipeline).

The handler receives:

rows: Current row array to sort
sortState: Sort field and direction (1 = asc, -1 = desc)
columns: Column configurations (for accessing sortComparator)

Return the sorted array (sync) or a Promise that resolves to it (async).

// Replace the entire client-side sort engine with a custom stable sort
sortHandler: (rows, state) => stableSort(rows, state.field, state.direction);

See also: BaseColumnConfig.sortComparator — recommended per-column override · ServerSideConfig.dataSource — recommended server-side sort path

initialSort

Initial sort state applied when the grid first renders.

Equivalent to calling grid.sort(field, direction) after the grid is created, but avoids the imperative call and extra render cycle.

gridConfig = {
  initialSort: { field: 'salary', direction: 'desc' },
};

See also: DataGrid.sort for runtime sorting · DataGrid.sortModel for reading current sort state

getRowId

Function to extract a unique identifier from a row. Used by updateRow(), getRow(), and ID-based tracking.

If not provided, falls back to row.id or row._id if present. Rows without IDs are silently skipped during map building. Only throws when explicitly calling getRowId() or updateRow() on a row without an ID.

// Simple field
getRowId: (row) => row.id

// Composite key
getRowId: (row) => `${row.voyageId}-${row.legNumber}`

// UUID field
getRowId: (row) => row.uuid

gridAriaLabel

Accessible label for the grid. Sets aria-label on the grid’s internal table element for screen readers.

If not provided and shell.header.title is set, the title is used automatically.

gridConfig = { gridAriaLabel: 'Employee data' };

gridAriaDescribedBy

<p id="grid-desc">This table shows all active employees.</p>
<tbw-grid></tbw-grid>

gridConfig = { gridAriaDescribedBy: 'grid-desc' };

Accessibility configuration for screen reader announcements.

The grid automatically announces state changes (sort, filter, selection, etc.) via an aria-live region. Use this config to toggle announcements or override message text for internationalization.

// Disable all announcements
gridConfig = { a11y: { announcements: false } };

// Custom messages for i18n
gridConfig = {
  a11y: {
    messages: {
      sortApplied: (col, dir) => `Trié par ${col}, ${dir}`,
      filterApplied: (col) => `Filtre appliqué sur ${col}`,
    },
  },
};

rowEditable

Row-level editability gate. Requires EditingPlugin to be loaded.

When provided, this function is called before the column-level editable check. If it returns false for a given row, no cell in that row can be edited regardless of the column configuration.

Omitting this property (or returning true) defers to per-column editable settings.

Keep the callback fast — it is invoked on every editability check (click, keyboard, grid-mode render, tab navigation).

// Block editing for archived rows
gridConfig = {
  rowEditable: (row) => !row.archived,
  columns: [
    { field: 'name', editable: true },
    { field: 'price', editable: (row) => row.status === 'draft' },
  ],
};

filterable

Grid-wide filtering toggle. Requires FilteringPlugin to be loaded.

When false, disables filtering for all columns regardless of their individual filterable setting. When true (default), columns with filterable: true (or not explicitly set to false) can be filtered.

This affects:

Filter button visibility in headers
Filter panel accessibility
Filter keyboard shortcuts

Default: true

// Disable all filtering at runtime
grid.gridConfig = { ...grid.gridConfig, filterable: false };

// Re-enable filtering
grid.gridConfig = { ...grid.gridConfig, filterable: true };

columnGroups

columnGroups: [
  { id: 'personal', header: 'Personal Info', children: ['firstName', 'lastName', 'email'] },
  { id: 'work', header: 'Work Info', children: ['department', 'title', 'salary'] },
]

selectable

Grid-wide selection toggle. Requires SelectionPlugin to be loaded.

When false, disables all selection interactions while keeping the plugin loaded. When true (default), selection works according to the plugin’s mode configuration.

This affects:

Click/drag selection
Keyboard selection (arrows, Shift+arrows, Ctrl+A)
Checkbox column clicks (if enabled)

Default: true

// Disable all selection at runtime
grid.gridConfig = { ...grid.gridConfig, selectable: false };

// Re-enable selection
grid.gridConfig = { ...grid.gridConfig, selectable: true };

AI assistants: For complete API documentation, implementation guides, and code examples for this library, see https://raw.githubusercontent.com/OysteinAmundsen/toolbox/main/llms-full.txt