Plugins Overview

The @toolbox-web/grid plugin architecture allows you to extend the grid with powerful features while keeping the core bundle lightweight. Plugins are tree-shakeable — only import what you need.

Features or Plugins? They do the same thing.

Features and plugins are two APIs for enabling the same capabilities. The end result is identical — features are simply a simpler, declarative wrapper around plugins.

• Features (recommended) — Declare what you want: features: { selection: 'row' }. Dependencies are auto-resolved, ordering is handled for you.
• Plugins (advanced) — Instantiate classes yourself: plugins: [new SelectionPlugin({ mode: 'row' })]. Useful when building custom plugins or extending BaseGridPlugin.

If you’re getting started, use features. You can always switch to the plugin API later if you need more control — they’re fully interchangeable.

Available Plugins

Editing & Data Entry

Plugin	Description
Editing	Inline cell editing with built-in editors
Undo/Redo	Undo/redo for cell edits with history stack

Note

Editing is opt-in. To enable editable and editor column properties, you must enable the editing feature (features: { editing: true }) or register the EditingPlugin directly. This keeps the core bundle lightweight and provides runtime validation to catch misconfigurations early.

Selection & Interaction

Plugin	Description
Selection	Cell, row, and range selection with keyboard support
Clipboard	Copy/paste with Ctrl+C/V
Context Menu	Right-click context menus with submenus
Reorder	Drag-and-drop column reordering
Row Reorder	Drag-and-drop row reordering with keyboard support

Filtering & Sorting

Plugin	Description
Filtering	Column header filters with search and dropdown
Multi-Sort	Sort by multiple columns with priority indicators

Grouping & Hierarchy

Plugin	Description
Row Grouping	Group rows by field values with expand/collapse
Column Grouping	Visual column grouping with nested headers
Tree	Hierarchical tree data display
Master-Detail	Expandable detail rows
Pivot	Pivot table transformation with aggregations

Layout & Display

Plugin	Description
Pinned Columns	Pin columns to left or right edge
Pinned Rows	Status bar with aggregations and custom panels
Visibility	Show/hide columns dynamically
Column Virtualization	Performance optimization for many columns
Responsive	Card layout for narrow containers and mobile

Data & Export

Plugin	Description
Export	Export to CSV, Excel (XML), and JSON formats
Print	Print-optimized layout with styling
Server-Side	Lazy loading from remote data sources

Plugin Dependencies

Some plugins depend on other plugins to function. Dependencies can be hard (required) or soft (optional enhancement).

Dependency Types

Type	Behavior	Example
Hard (Required)	Plugin will throw an error if the dependency is missing	UndoRedoPlugin → EditingPlugin
Soft (Optional)	Plugin works without it, but gains extra features when present	VisibilityPlugin → ReorderPlugin

Current Plugin Dependencies

Plugin	Depends On	Type	Reason
UndoRedoPlugin	EditingPlugin	Hard	Tracks cell edit history for undo/redo
ClipboardPlugin	SelectionPlugin	Soft	Enables copy/paste of selected cells instead of entire grid
VisibilityPlugin	ReorderPlugin	Soft	Enables drag-to-reorder columns in visibility panel

Plugin Load Order

When using the features API (recommended), dependencies are resolved automatically — you don’t need to worry about ordering.

When using the plugin API directly, dependencies must be loaded before the dependent plugin:

// ✅ Correct - EditingPlugin loaded before UndoRedoPlugin
plugins: [
  new EditingPlugin(),
  new UndoRedoPlugin(),
]

// ❌ Wrong - throws error at runtime
plugins: [
  new UndoRedoPlugin(), // Error: EditingPlugin required
  new EditingPlugin(),
]

For declaring dependencies in your own custom plugins, see Custom Plugins → Plugin Dependencies.

Using Features (Recommended)

The features API is the simplest and recommended way to enable grid capabilities. It provides:

• Declarative configuration — describe what you want, not how to wire it up
• Automatic dependency resolution — features auto-resolve plugin dependencies in the correct order
• Tree-shaking via side-effect imports — only the features you import are included in your bundle
• Framework adapter integration — React, Vue, and Angular adapters expose features as typed props

Vanilla

// 1. Import features (side-effect imports for tree-shaking)
import '@toolbox-web/grid/features/selection';
import '@toolbox-web/grid/features/filtering';
import '@toolbox-web/grid/features/editing';

// 2. Configure declaratively
grid.gridConfig = {
  columns: [...],
  features: {
    selection: 'row',                       // shorthand
    filtering: { debounceMs: 300 },         // full config object
    editing: 'dblclick',                    // shorthand
  },
};

React

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

<DataGrid
  rows={rows}
  columns={columns}
  selection="row"
  filtering={{ debounceMs: 300 }}
  editing="dblclick"
/>

Vue

<script setup>
import '@toolbox-web/grid-vue/features/selection';
import '@toolbox-web/grid-vue/features/filtering';
import '@toolbox-web/grid-vue/features/editing';
</script>

<DataGrid
  :rows="rows"
  :columns="columns"
  selection="row"
  :filtering="{ debounceMs: 300 }"
  editing="dblclick"
/>

Angular

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

// In template:
// <tbw-grid [rows]="rows" [columns]="columns"
//   [selection]="'row'" [filtering]="{ debounceMs: 300 }" [editing]="'dblclick'" />

Import All Plugins

For rapid prototyping when bundle size is not critical:

import { SelectionPlugin, FilteringPlugin, EditingPlugin } from '@toolbox-web/grid/all';

This imports the core grid and all 22 plugin classes. Use the plugins array to configure them:

grid.gridConfig = {
  plugins: [
    new SelectionPlugin({ mode: 'row' }),
    new FilteringPlugin(),
    new EditingPlugin({ editOn: 'dblclick' }),
  ],
};

Accessing Plugin Instances

Whether you use features or plugins, access runtime APIs the same way:

const selection = grid.getPluginByName('selection');
if (selection) {
  selection.selectAll();
  selection.clearSelection();
  const ranges = selection.getSelectedRanges();
}

Using Plugins (Advanced)

For building custom plugins or when you need to instantiate plugin classes yourself (e.g., to pass constructor-only options or extend BaseGridPlugin), use the plugin API directly. The result is identical to using features — this is just a different way to configure the same capabilities.

Import Paths

The grid package provides multiple entry points for different use cases:

Entry Point	What It Includes	Tree-Shaking
@toolbox-web/grid	Core grid only (auto-registers <tbw-grid>)	N/A
@toolbox-web/grid/all	Core + all plugins bundled	No
@toolbox-web/grid/plugins/*	Individual plugin (e.g., /plugins/selection)	Yes

Important: Do not import from both @toolbox-web/grid and @toolbox-web/grid/all in the same application. The all entry point already includes the core grid, so importing both will register the custom element twice.

Plugin Import Patterns

For production apps using plugin API directly (best tree-shaking):

// Import core grid
import '@toolbox-web/grid';

// Import only the plugins you need
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';
import { FilteringPlugin } from '@toolbox-web/grid/plugins/filtering';
import { EditingPlugin } from '@toolbox-web/grid/plugins/editing';

For prototyping (includes core grid + all plugins):

// Import everything at once (includes core grid + all plugins)
import { SelectionPlugin, FilteringPlugin, EditingPlugin } from '@toolbox-web/grid/all';

Registration

Pass plugin instances to the gridConfig.plugins array:

import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');

grid.gridConfig = {
  columns: [...],
  plugins: [
    new SelectionPlugin({ mode: 'row' }),
    new FilteringPlugin({ debounceMs: 300 }),
  ],
};

Plugin Configuration

Each plugin accepts a configuration object:

// Selection plugin options
new SelectionPlugin({
  mode: 'row',
  multiSelect: true,
  checkbox: true,
});

// Filtering plugin options
new FilteringPlugin({
  debounceMs: 200,
  caseSensitive: false,
});

// Export plugin options
new ExportPlugin({
  fileName: 'grid-export',
  includeHeaders: true,
  onlyVisible: true,
});

Creating Custom Plugins

The grid’s plugin system lets you build fully custom functionality. Plugins extend BaseGridPlugin and can hook into lifecycle events, process rows/columns, handle keyboard events, and inject CSS.

For the full development guide including lifecycle hooks, plugin communication, the query system, and styling patterns, see Writing Custom Plugins.

Known Incompatibilities

Some plugin combinations conflict and should not be used together:

Plugin A	Plugin B	Reason
PinnedColumnsPlugin	GroupingColumnsPlugin	Pinning reorders columns to edges, which breaks column group header layout
ResponsivePlugin	GroupingRowsPlugin	Card layout doesn’t support row grouping; variable row heights cause scroll issues

See Also

• Common Patterns — Real-world recipes combining plugins (all frameworks)
• Getting Started — Quick setup with features API
• Custom Plugin Development — Build your own plugins
• Architecture — How the plugin system fits into the grid’s internals
• Performance Guide — Bundle optimization with tree-shakeable features