InternalGrid

Since v0.1.1

Internal-only augmented interface for DataGrid component.

Member prefixes indicate accessibility:

• _underscore = protected members - private outside core, accessible to plugins. Marked with @internal.
• __doubleUnderscore = deeply internal members - private outside core, only for internal functions.

Properties

Property	Type	Description
gridConfig?	GridConfig<T, ColumnFieldKey<T>>	Full config object. Setter merges with other inputs per precedence rules. Getter returns the effective (resolved) config.
columns?	ColumnConfig<T, ColumnFieldKey<T>>[]	Column definitions. Getter returns effective columns (after merging config, light DOM, inference).
rows?	T[]	Current row data (after plugin processing like grouping, filtering).
ready?	() => Promise<void>	Resolves once the component has finished initial work (layout, inference).
forceLayout?	() => Promise<void>	Force a layout / measurement pass (e.g. after container resize).
getConfig?	() => Promise<Readonly<GridConfig<T, ColumnFieldKey<T>>>>	Return effective resolved config (after inference & precedence).
toggleGroup?	(key: string) => Promise<void>	Toggle expansion state of a group row by its generated key.
registerStyles?	(id: string, css: string) => void	Register custom CSS styles to be injected into the grid. Use this to style custom cell renderers, editors, or detail panels.
unregisterStyles?	(id: string) => void	Remove previously registered custom styles.
getRegisteredStyles?	() => string[]	Get list of registered custom style IDs.
columnState?	GridColumnState	Read the current column state. Property-style accessor that mirrors PublicGrid.getColumnState. To restore state, use PublicGrid.applyColumnState.
sortModel?	{ field: string; direction: desc | asc } | unknown	Get the current sort state.
loading?	boolean	Whether the grid is currently in a loading state. When true, displays a loading overlay with spinner.
focusedCell?	{ rowIndex: number; colIndex: number; field: string } | unknown	The currently focused cell position, or null if no rows are loaded.
id	string	The element’s id attribute. Available because DataGridElement extends HTMLElement.
_hostElement	HTMLElement	The grid’s host HTMLElement (this). Use instead of casting grid as unknown as HTMLElement.
_rows	T[]
_columns	ColumnInternal<T>[]
_visibleColumns	ColumnInternal<T>[]	Visible columns only (excludes hidden). Use for rendering.
_headerRowEl	HTMLElement
_bodyEl	HTMLElement
_rowPool	RowElementInternal[]
_resizeController	ResizeController
_sortState	{ field: string; direction: -1 | 1 } | unknown
sourceRows	T[]	Original unfiltered/unprocessed rows.
__frameworkAdapter?	FrameworkAdapter	Framework adapter instance (set by Grid directives).
__originalOrder	T[]
__rowRenderEpoch	number
__didInitialAutoSize?	boolean
__lightDomColumnsCache?	ColumnInternal<any>[]
__originalColumnNodes?	HTMLElement[]
__cellDisplayCache?	Map<number, string[]>	Cell display value cache.
__cellCacheEpoch?	number	Cache epoch for cell display values.
__cachedHeaderRowCount?	number	Cached header row count for virtualization.
__hasSpecialColumns?	boolean	Cached flag for whether grid has special columns (custom renderers, etc.).
__hasRenderRowPlugins?	boolean	Cached flag for whether any plugin has renderRow hooks.
_pluginManager?	{ _hasRowStructurePlugins: boolean; emitPluginEvent?: (eventType: string, detail: D) => void; processConfig?: unknown; hasRowHeightPlugin?: unknown }	Access the plugin manager’s cached state.
_gridTemplate	string
_virtualization	VirtualState
_focusRow	number
_focusCol	number
_activeEditRows?	number	Currently active edit row index. Injected by EditingPlugin.
_isGridEditMode?	boolean	Whether the grid is in ‘grid’ editing mode (all rows editable). Injected by EditingPlugin.
_rowEditSnapshots?	Map<number, T>	Snapshots of row data before editing. Injected by EditingPlugin.
changedRows?	T[]	Get all changed rows. Injected by EditingPlugin.
changedRowIds?	string[]	Get IDs of all changed rows. Injected by EditingPlugin.
_changedRowIdSet?	ReadonlySet<string>	Internal Set for O(1) lookup in the render hot path. Injected by EditingPlugin.
effectiveConfig?	GridConfig<T, ColumnFieldKey<T>>
findHeaderRow?	() => HTMLElement
refreshVirtualWindow	(full: boolean, skipAfterRender: boolean) => boolean
refreshColumns?	() => void	Trigger a COLUMNS-phase re-render.
updateTemplate?	() => void
findRenderedRowElement?	(rowIndex: number) => HTMLElement | unknown
getRow?	(id: string) => T | undefined	Get a row by its ID. Implemented in grid.ts
_getRowEntry	(id: string) => { row: T; index: number } | undefined	Get a row and its current index by ID. Returns undefined if not found.
_getSourceRowEntry	(id: string) => { row: T; index: number } | undefined	Get a row and its index by ID from the full source dataset, including rows filtered/paged out of the visible view. Visible rows return their _rows index; source-only rows return index: -1.
getRowId?	(row: T) => string	Get the unique ID for a row. Implemented in grid.ts
updateRow?	(id: string, changes: Partial<T>, source: keyof UpdateSourceMap) => void	Update a row by ID. Implemented in grid.ts
animateRow?	(rowIndex: number, type: RowAnimationType) => Promise<boolean>	Animate a single row. Returns Promise that resolves when animation completes. Implemented in grid.ts
animateRows?	(rowIndices: number[], type: RowAnimationType) => Promise<number>	Animate multiple rows. Returns Promise that resolves when all animations complete. Implemented in grid.ts
animateRowById?	(rowId: string, type: RowAnimationType) => Promise<boolean>	Animate a row by its ID. Returns Promise that resolves when animation completes. Implemented in grid.ts
beginBulkEdit?	(rowIndex: number) => void	Begin bulk edit on a row. Injected by EditingPlugin.
commitActiveRowEdit?	() => void	Commit active row edit. Injected by EditingPlugin.
_dispatchCellClick?	(event: MouseEvent, rowIndex: number, colIndex: number, cellEl: HTMLElement) => boolean	Dispatch cell click to plugin system, returns true if handled
_dispatchRowClick?	(event: MouseEvent, rowIndex: number, row: any, rowEl: HTMLElement) => boolean	Dispatch row click to plugin system, returns true if handled
_dispatchHeaderClick?	(event: MouseEvent | KeyboardEvent, col: ColumnConfig, headerEl: HTMLElement) => boolean	Dispatch header click to plugin system, returns true if handled
_dispatchKeyDown?	(event: KeyboardEvent) => boolean	Dispatch keydown to plugin system, returns true if handled
_dispatchCellMouseDown?	(event: CellMouseEvent) => boolean	Dispatch cell mouse events for drag operations. Returns true if any plugin started a drag.
_dispatchCellMouseMove?	(event: CellMouseEvent) => void	Dispatch cell mouse move during drag.
_dispatchCellMouseUp?	(event: CellMouseEvent) => void	Dispatch cell mouse up to end drag.
_afterCellRender?	(context: AfterCellRenderContext<T>) => void	Call afterCellRender hook on all plugins. Called from rows.ts after each cell is rendered.
_hasAfterCellRenderHook?	() => boolean	Check if any plugin has registered an afterCellRender hook. Used to skip hook call for performance.
_afterRowRender?	(context: AfterRowRenderContext<T>) => void	Call afterRowRender hook on all plugins. Called from rows.ts after each row is rendered.
_hasAfterRowRenderHook?	() => boolean	Check if any plugin has registered an afterRowRender hook. Used to skip hook call for performance.
_getHorizontalScrollOffsets?	(rowEl: HTMLElement, focusedCell: HTMLElement) => { left: number; right: number; skipScroll?: boolean }	Get horizontal scroll boundary offsets from plugins
_getVerticalScrollOffsets?	(focusedRowIndex: number) => { top: number; bottom: number; skipScroll?: boolean }	Get vertical scroll boundary offsets from plugins that overlay the rows viewport
requestStateChange?	() => void	Request emission of column-state-change event (debounced)
_schedulerIsConnected	boolean
_renderRoot	Element	The render root element for DOM queries.
_accordionIcons	{ expand: IconValue; collapse: IconValue }	Get accordion expand/collapse icons from effective config.
rowClass?	(row: T) => 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.
columnInference?	ColumnInferenceMode	How automatic column inference combines with explicitly provided columns. Can also be set via the columnInference prop or column-inference attribute. v2.17.0+
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: T, 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<T>>	Declarative feature configuration. Alternative to manually creating plugin instances in plugins. Features are resolved using the core feature registry.
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<T>	Custom sort handler for the entire grid.
initialSort?	{ field: string; direction: desc | asc }	Initial sort state applied when the grid first renders.
typeDefaults?	Record<string, TypeDefault<T>>	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.
gridAriaLabelledBy?	string	ID of an element that labels the grid. Sets aria-labelledby on the grid’s internal table element so screen readers can use the referenced element’s text as the accessible name — useful when the grid already sits next to a heading.
gridAriaDescribedBy?	string	ID of an element that describes the grid. Sets aria-describedby on the grid’s internal table element.
gridAriaRoleDescription?	string	Override the screen-reader-announced role name for the grid via aria-roledescription. Useful for localization (e.g. "Tabell" in Norwegian) or domain-specific naming (e.g. "Employee table").
a11y?	A11yConfig	Accessibility configuration for screen reader announcements.
locale?	GridLocale	Translations for the built-in UI chrome rendered by plugins — filter panels, the column visibility panel, the pivot panel, context-menu items, and the print button. v3.5.0+
loadingRenderer?	LoadingRenderer	Custom renderer for the loading overlay.
emptyRenderer?	EmptyRenderer | unknown	Custom renderer shown when the grid has no rows to display (loading === false AND the rendered row count is 0, after all plugin processing such as filtering / grouping / server-side). v2.12.0+
emptyOverlay?	EmptyOverlay	Where the empty-state overlay is mounted. v2.12.0+
editOn?	false | click | dblclick | manual	Edit trigger mode. Requires EditingPlugin to be loaded.
rowEditable?	(row: T) => 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.
shell?	ShellConfig	Shell configuration for header bar and tool panels. When configured, adds an optional wrapper with title, toolbar, and collapsible side panels.

Property Details

columnState

const snapshot = grid.columnState;

---

sortModel

Get the current sort state.

Returns null when no sort is active.

const sort = grid.sortModel;
// { field: 'id', direction: 'desc' } | null

---

loading

Whether the grid is currently in a loading state. When true, displays a loading overlay with spinner.

Can also be set via the loading HTML attribute.

// Show loading overlay
grid.loading = true;
const data = await fetchData();
grid.rows = data;
grid.loading = false;

---

rowClass

Dynamic CSS class(es) for data rows. Called for each row during rendering. Return class names to add to the row element.

Applies to custom-rendered rows too (e.g. a Responsive cardRenderer card), but not to rows a plugin both synthesizes and renders itself — group headers, pivot rows and grouped loading placeholders are skipped because they are not TRow values. ServerSide’s { __loading: true } placeholders take the default render path and are NOT skipped.

// 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' : ''

---

columnInference

How automatic column inference combines with explicitly provided columns. Can also be set via the columnInference prop or column-inference attribute.

• 'auto' (default): infer only when no columns are provided (current behavior).
• 'merge': always infer from data, then overlay provided columns by field.

See also: ColumnInferenceMode

---

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 }),
]

---

features

Declarative feature configuration. Alternative to manually creating plugin instances in plugins. Features are resolved using the core feature registry.

Import feature modules as side effects to register them:

import '@toolbox-web/grid/features/selection';
import '@toolbox-web/grid/features/filtering';

Then configure declaratively:

gridConfig = {
  features: {
    selection: 'range',
    filtering: { debounceMs: 200 },
    editing: 'dblclick',
  },
};

Both features and plugins can be used together — features-generated plugins are created first, then manual plugins are appended. Duplicates are skipped (manual plugins take precedence).

---

icons

Grid-wide icon configuration.

The grid uses a CSS-first hybrid icon system:

• Default (CSS): Icons render via --tbw-icon-* CSS custom properties on tbw-grid. Override them in your theme CSS — no JavaScript needed.
• JS override: Setting gridConfig.icons takes precedence over CSS for any key provided. Use this for dynamic icons, icon libraries, or HTMLElement instances.

All icons are optional — sensible defaults are used when not specified. Plugins will use these by default but can override with their own config.

---

sortHandler

Custom sort handler for the entire grid.

Caution

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: DataGridElement.sort for runtime sorting · DataGridElement.sortModel for reading current sort state

---

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.

If gridAriaLabelledBy is also set, aria-labelledby takes precedence per WAI-ARIA accessible-name computation and aria-label is omitted.

gridConfig = { gridAriaLabel: 'Employee data' };

---

gridAriaLabelledBy

ID of an element that labels the grid. Sets aria-labelledby on the grid’s internal table element so screen readers can use the referenced element’s text as the accessible name — useful when the grid already sits next to a heading.

Per WAI-ARIA accessible-name precedence, aria-labelledby takes priority over aria-label and over the auto-derived shell title. When this option is set, the grid omits aria-label to avoid conflicting names.

<h2 id="grid-heading">Employees</h2>
<tbw-grid></tbw-grid>

gridConfig = { gridAriaLabelledBy: 'grid-heading' };

---

gridAriaDescribedBy

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

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

---

gridAriaRoleDescription

Override the screen-reader-announced role name for the grid via aria-roledescription. Useful for localization (e.g. "Tabell" in Norwegian) or domain-specific naming (e.g. "Employee table").

Caution

Per WAI-ARIA 1.2, the value should still describe a grid-like widget. Overriding with an unrelated label confuses assistive-technology users about the available interactions (cell navigation, sort, etc.). Leave unset to use the default role name announced by the AT.

gridConfig = { gridAriaRoleDescription: 'Employee table' };

---

a11y

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

---

locale

Translations for the built-in UI chrome rendered by plugins — filter panels, the column visibility panel, the pivot panel, context-menu items, and the print button.

Keys are namespaced per plugin (filter.apply, columns.showAll, pivot.removeField, …). Any key you omit falls back to its English default, so a partial map is valid. Unknown keys are ignored.

ARIA live-region announcements are configured separately via A11yConfig.messages, because those are functions of runtime values.

gridConfig = {
  locale: {
    'filter.apply': 'Appliquer',
    'filter.clear': 'Effacer le filtre',
    'filter.search': 'Rechercher…',
    'columns.showAll': 'Tout afficher',
  },
};

---

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

---

emptyRenderer

Custom renderer shown when the grid has no rows to display (loading === false AND the rendered row count is 0, after all plugin processing such as filtering / grouping / server-side).

• When omitted, a built-in message is rendered (“No data to display” or “No matching rows” when source rows existed but were filtered out).
• When set to a function, the function receives an EmptyContext and returns an HTMLElement or HTML string.
• When explicitly null, the empty overlay is suppressed entirely.

The empty overlay is mutually exclusive with the loading overlay; if loading === true, the loading overlay always wins.

// Show a backend error message via a closure over the consumer's state.
gridConfig.emptyRenderer = () =>
  error
    ? `Failed to load deals: ${error.message}`
    : 'No deals to display';

See also: EmptyOverlay to control where the overlay is mounted.

---

emptyOverlay

Where the empty-state overlay is mounted.

• 'rows' (default) — overlays the .rows-container. Headers stay visible so users can clear filters or see the column schema.
• 'grid' — overlays the .tbw-grid-root. Hides headers and any shell/toolbar content too.

---

editOn

Edit trigger mode. Requires EditingPlugin to be loaded.

Configure via new EditingPlugin({ editOn: 'click' }) or set on gridConfig. Plugin config takes precedence over gridConfig.

• 'click': Single click to edit
• 'dblclick': Double-click to edit (default)
• 'manual': Only via programmatic API (beginEdit)
• false: Disable editing entirely

---

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

---

shell

Shell configuration for header bar and tool panels. When configured, adds an optional wrapper with title, toolbar, and collapsible side panels.

Provided via module augmentation by the built-in ShellPlugin (#370), mirroring how feature plugins augment FeatureConfig. Import the ShellConfig type from @toolbox-web/grid/plugins/shell.

---

Methods

insertRow()

Insert a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default.

insertRow(index: number, row: T, animate: boolean): Promise<void>

Parameters

Name	Type	Description
index	number
row	T
animate	boolean

---

removeRow()

Remove a row at a visible index, bypassing the sort/filter pipeline. Auto-animates by default.

removeRow(index: number, animate: boolean): Promise<T | undefined>

Parameters

Name	Type	Description
index	number
animate	boolean

---

applyTransaction()

Apply a batch of add/update/remove mutations in a single render cycle.

applyTransaction(transaction: RowTransaction<T>, animate: boolean): Promise<TransactionResult<T>>

Parameters

Name	Type	Description
transaction	RowTransaction<T>
animate	boolean

---

applyTransactionAsync()

Batch-friendly version — merges rapid calls within a single animation frame.

applyTransactionAsync(transaction: RowTransaction<T>): Promise<TransactionResult<T>>

Parameters

Name	Type	Description
transaction	RowTransaction<T>

---

getPlugin()

Get a plugin instance by its class.

Prefer getPluginByName — it avoids importing the plugin class and returns the actual registered instance with full type narrowing.

getPlugin(PluginClass: (args: any[]) => P): P | undefined

Parameters

Name	Type	Description
PluginClass	(args: any[]) => P

Example

// Preferred: by name
const selection = grid.getPluginByName('selection');

// Alternative: by class
const selection = grid.getPlugin(SelectionPlugin);
if (selection) {
  selection.selectAll();
}

---

getPluginByName()

Get a plugin instance by its name.

When a plugin augments the PluginNameMap interface, the return type is narrowed automatically:

const editing = grid.getPluginByName('editing');
editing?.beginBulkEdit(0); // ✅ typed as EditingPlugin

For unknown names the return type falls back to GridPlugin | undefined.

getPluginByName(name: K): unknown | undefined

Parameters

Name	Type	Description
name	K

---

refreshShellHeader()

Re-render the shell header (title, column groups, toolbar). Call this after dynamically adding/removing tool panels or toolbar buttons.

refreshShellHeader(): void

---

registerToolPanel()

Register a custom tool panel in the sidebar.

registerToolPanel(panel: ToolPanelDefinition): void

Parameters

Name	Type	Description
panel	ToolPanelDefinition

Example

grid.registerToolPanel({
  id: 'analytics',
  title: 'Analytics',
  icon: '📊',
  render: (container) => {
    container.innerHTML = '<div>Charts here...</div>';
  }
});

---

unregisterToolPanel()

Unregister a previously registered tool panel.

unregisterToolPanel(panelId: string): void

Parameters

Name	Type	Description
panelId	string

---

openToolPanel()

Open the tool panel sidebar.

openToolPanel(panelId: string): void

Parameters

Name	Type	Description
panelId	string	Optional ID of the section to expand on open. Takes precedence
over shell.toolPanel.defaultOpen. Falls back to default behavior with a
warning if the ID is not registered.

---

closeToolPanel()

Close the tool panel sidebar.

closeToolPanel(): void

---

toggleToolPanel()

Toggle the tool panel sidebar open or closed.

toggleToolPanel(): void

---

toggleToolPanelSection()

Toggle an accordion section expanded or collapsed within the tool panel.

toggleToolPanelSection(sectionId: string): void

Parameters

Name	Type	Description
sectionId	string	The ID of the section to toggle

---

getColumnState()

Get the current column state including order, width, visibility, and sort. Use for persisting user preferences to localStorage or a backend.

getColumnState(): GridColumnState

Example

const state = grid.getColumnState();
localStorage.setItem('gridState', JSON.stringify(state));

---

applyColumnState()

Apply a previously saved column state, restoring column order, widths, visibility, sort, and any plugin-contributed state. Can be called before or after grid initialization — pre-init calls are deferred and applied during setup.

applyColumnState(state: GridColumnState | undefined): void

Parameters

Name	Type	Description
state	GridColumnState | undefined

Example

const saved = localStorage.getItem('gridState');
if (saved) grid.applyColumnState(JSON.parse(saved));

---

sort()

Sort by a column, toggle a column’s sort direction, or clear sorting.

• sort('id', 'desc') — apply sort with explicit direction
• sort('id') — toggle: none → asc → desc → none
• sort(null) — clear sort, restore original row order

sort(field: string | null, direction: "desc" | "asc"): void

Parameters

Name	Type	Description
field	string | unknown	Column field to sort by, or null to clear
direction	desc | asc	Explicit direction; omit to toggle

Example

grid.sort('id', 'desc');  // sort descending
grid.sort('price');       // toggle sort on price
grid.sort(null);          // clear sort

---

setRowLoading()

Set loading state for a specific row. Displays a small spinner indicator on the row.

Use when persisting row data or performing row-level async operations.

setRowLoading(rowId: string, loading: boolean): void

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier (from getRowId)
loading	boolean	Whether the row is loading

Example

// Show loading while saving row
grid.setRowLoading('emp-123', true);
await saveRow(row);
grid.setRowLoading('emp-123', false);

---

setCellLoading()

Set loading state for a specific cell. Displays a small spinner indicator on the cell.

Use when performing cell-level async operations (e.g., validation, lookup).

setCellLoading(rowId: string, field: string, loading: boolean): void

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier (from getRowId)
field	string	The column field
loading	boolean	Whether the cell is loading

Example

// Show loading while validating cell
grid.setCellLoading('emp-123', 'email', true);
const isValid = await validateEmail(email);
grid.setCellLoading('emp-123', 'email', false);

---

isRowLoading()

Check if a row is currently in loading state.

isRowLoading(rowId: string): boolean

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier

---

isCellLoading()

Check if a cell is currently in loading state.

isCellLoading(rowId: string, field: string): boolean

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier
field	string	The column field

---

clearAllLoading()

Clear all row and cell loading states.

clearAllLoading(): void

---

registerExternalFocusContainer()

Register an external DOM element as a logical focus container of this grid.

Focus moving into a registered container is treated as if it stayed inside the grid: data-has-focus is preserved, click-outside commit is suppressed, and the editing focus trap (when enabled) won’t reclaim focus.

Typical use case: overlay panels (datepickers, dropdowns, autocompletes) that render at <body> level to escape grid overflow clipping.

registerExternalFocusContainer(el: Element): void

Parameters

Name	Type	Description
el	Element	The external element to register

Example

const overlay = document.createElement('div');
document.body.appendChild(overlay);

// Tell the grid this overlay is "part of" the grid
grid.registerExternalFocusContainer(overlay);

// Later, when overlay is removed
grid.unregisterExternalFocusContainer(overlay);

---

unregisterExternalFocusContainer()

Unregister a previously registered external focus container.

unregisterExternalFocusContainer(el: Element): void

Parameters

Name	Type	Description
el	Element	The element to unregister

---

containsFocus()

Check whether focus is logically inside this grid.

Returns true when document.activeElement (or the given node) is inside the grid’s own DOM or inside any element registered via registerExternalFocusContainer.

containsFocus(node: Node | null): boolean

Parameters

Name	Type	Description
node	Node | unknown	Optional node to test. Defaults to document.activeElement.

Example

if (grid.containsFocus()) {
  console.log('Grid or one of its overlays has focus');
}

---

focusCell()

Move focus to a specific cell.

focusCell(rowIndex: number, column: string | number): void

Parameters

Name	Type	Description
rowIndex	number	Row index (0-based, in the current processed row array)
column	string | number	Column index (0-based into visible columns) or field name

---

scrollToRow()

Scroll to make a row visible by its index.

scrollToRow(rowIndex: number, options: ScrollToRowOptions): void

Parameters

Name	Type	Description
rowIndex	number	Row index (0-based, in the current processed row array)
options	ScrollToRowOptions	Scroll alignment and behavior

---

scrollToRowById()

Scroll to make a row visible by its unique ID.

scrollToRowById(rowId: string, options: ScrollToRowOptions): void

Parameters

Name	Type	Description
rowId	string	The row’s unique identifier (from getRowId)
options	ScrollToRowOptions	Scroll alignment and behavior

---

querySelector()

querySelector(selectors: K): HTMLElementTagNameMap[K] | null

Parameters

Name	Type	Description
selectors	K

---

querySelectorAll()

querySelectorAll(selectors: K): NodeListOf<HTMLElementTagNameMap[K]>

Parameters

Name	Type	Description
selectors	K

---