GridConfig

Grid configuration object - the single source of truth for grid behavior.

Users can configure the grid via multiple input methods, all of which converge into an effective GridConfig internally:

Configuration Input Methods:

• gridConfig property - direct assignment of this object
• columns property - shorthand for gridConfig.columns
• fitMode property - shorthand for gridConfig.fitMode
• Light DOM <tbw-grid-column> - declarative columns (merged into columns)
• Light DOM <tbw-grid-header> - declarative shell header (merged into shell.header)

Precedence (when same property set multiple ways): Individual props (fitMode) > columns prop > Light DOM > gridConfig

Example

// Via gridConfig (recommended for complex setups)
grid.gridConfig = {
  columns: [{ field: 'name' }, { field: 'age' }],
  fitMode: 'stretch',
  plugins: [new SelectionPlugin()],
  shell: { header: { title: 'My Grid' } }
};

// Via individual props (convenience for simple cases)
grid.columns = [{ field: 'name' }, { field: 'age' }];
grid.fitMode = 'stretch';

Properties

Property	Type	Description
columns?	ColumnConfigMap<TRow>	Column definitions. Can also be set via columns prop or <tbw-grid-column> light DOM.
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. Provides consistent icons across all plugins (tree, grouping, sorting, etc.). Plugins will use these by default but can override with their own config.
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 full control over sorting behavior.
getRowId?	(row: TRow) => string	Function to extract a unique identifier from a row. Used by updateRow(), getRow(), and ID-based tracking.
typeDefaults?	Record<string, TypeDefault<TRow>>	Type-level renderer and editor defaults.
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.
loadingRenderer?	LoadingRenderer	Custom renderer for the loading overlay.
editOn?	false | click | dblclick | manual	Edit trigger mode. 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.

Property Details

columns

See also: ColumnConfig for column options · ColumnConfigMap

---

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 full control over sorting behavior.

When provided, this handler is called instead of the built-in sorting logic. Enables custom sorting algorithms, server-side sorting, or plugin-specific sorting.

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 the sorted array (async). For server-side sorting, return a Promise that resolves when data is fetched.

// Custom stable sort
sortHandler: (rows, state, cols) => {
  return stableSort(rows, (a, b) => compare(a[state.field], b[state.field]) * state.direction);
}

// Server-side sorting
sortHandler: async (rows, state) => {
  const response = await fetch(`/api/data?sort=${state.field}&dir=${state.direction}`);
  return response.json();
}

---

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

---

typeDefaults

Type-level renderer and editor defaults.

Keys can be:

• Built-in types: 'string', 'number', 'date', 'boolean', 'select'
• Custom types: 'currency', 'country', 'status', etc.

Resolution order (highest priority first):

1. Column-level (column.renderer / column.editor)
2. Grid-level (gridConfig.typeDefaults[column.type])
3. App-level (Angular GridTypeRegistry, React GridTypeProvider)
4. Built-in (checkbox for boolean, select for select, etc.)
5. Fallback (plain text / text input)

typeDefaults: {
  date: { editor: myDatePickerEditor },
  country: {
    renderer: (ctx) => {
      const span = document.createElement('span');
      span.innerHTML = `<img src="/flags/${ctx.value}.svg" /> ${ctx.value}`;
      return span;
    },
    editor: (ctx) => createCountrySelect(ctx)
  }
}

---

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

---

loadingRenderer

Custom renderer for the loading overlay.

When provided, replaces the default spinner with custom content. Receives a context object with the current loading size.

// Simple text loading indicator
loadingRenderer: () => {
  const el = document.createElement('div');
  el.textContent = 'Loading...';
  return el;
}

// Custom spinner component
loadingRenderer: (ctx) => {
  const spinner = document.createElement('my-spinner');
  spinner.size = ctx.size === 'large' ? 48 : 24;
  return spinner;
}

---

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

---