Skip to content
ToolboxJS

Editing Plugin

The Editing plugin enables inline cell editing in the grid. It provides built-in editors for common data types and supports custom editor functions for specialized input scenarios.

Why Opt-In?

Section titled “Why Opt-In?”

Editing is delivered as a plugin rather than built into the core grid for several reasons:

  • Smaller bundle size — Applications that only display data don’t pay for editing code
  • Clear intent — Explicit plugin registration makes editing capability obvious in code
  • Runtime validation — Using editable: true without the plugin throws a helpful error

Installation

Section titled “Installation”
import '@toolbox-web/grid/features/editing';

Basic Usage

Section titled “Basic Usage”

Enable the editing feature to use editable and editor column properties:

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


const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name', editable: true },
    { field: 'price', header: 'Price', type: 'number', editable: true },
    { field: 'active', header: 'Active', type: 'boolean', editable: true },
  ],
  features: { editing: 'dblclick' }, // or 'click'
};


// Listen for commits
grid.on('cell-commit', (detail) => {
  console.log('Cell edited:', detail);
});

Try It

Section titled “Try It”

Double-click any cell to start editing. Press Enter to commit or Escape to cancel.

Add/Remove Rows

Section titled “Add/Remove Rows”

To dynamically add or remove rows from the grid, simply assign a new array to the rows property. The grid reactively updates to display the new data. Use a custom renderer in an “Actions” column to provide a delete button for each row.

Programmatic Row Updates

Section titled “Programmatic Row Updates”

To update individual row values without reassigning the entire rows array, use the Row Update API:

// Update a single row by ID
grid.updateRow('emp-123', { status: 'active', salary: 75000 });


// Batch update multiple rows
grid.updateRows([
  { id: 'emp-123', changes: { status: 'active' } },
  { id: 'emp-456', changes: { department: 'Engineering' } },
]);


// Listen for programmatic updates
grid.on('cell-change', ({ rowId, changes }) => {
  console.log('Row updated:', rowId, changes);
});

See the API Reference for full documentation.

Edit Triggers

Section titled “Edit Triggers”

Configure how editing is triggered with the editOn option:

features: { editing: 'dblclick' } // or 'click', 'manual'
ValueBehavior
'click'Single click on cell enters edit mode
'dblclick'Double-click on cell enters edit mode (default)
'manual'Programmatic only via beginCellEdit(rowIndex, field)

The demo above uses editOn: 'click' — a single click enters edit mode.

Keyboard Shortcuts (Row Mode)

Section titled “Keyboard Shortcuts (Row Mode)”
KeyBehavior
EnterStart editing the entire row (all editable cells get editors)
F2Start editing only the focused cell (single-cell edit)
EscapeCancel the current edit and revert changes
Tab / Shift+TabMove to next/previous editable cell
Arrow Up/DownCommit current edit, exit edit mode, and move to adjacent row
SpaceToggle boolean cells (when not in edit mode)

Grid Mode (Spreadsheet-like Editing)

Section titled “Grid Mode (Spreadsheet-like Editing)”

For data entry forms or spreadsheet-like interfaces, use mode: 'grid' to make all editable cells show their editors at all times:

features: { editing: { mode: 'grid' } }
ModeBehavior
'row'Default. Click/dblclick to enter edit mode, Escape to exit
'grid'All editors visible immediately. Excel-like navigation.

In grid mode:

  • All editable: true cells render with their editors on load
  • Tab/Shift+Tab navigates between editable cells (wraps to next/prev row)
  • cell-commit events fire normally when values change

Excel-like Navigation vs Edit Mode

Section titled “Excel-like Navigation vs Edit Mode”
Grid Mode: All editable cells show editors immediately.
  • Tab/Shift+Tab: Move between editable cells
  • Enter: Commit current cell value
  • Click outside or press Escape: No effect (always in edit mode)
Recent Changes:

Grid mode supports Excel-style keyboard interaction with two modes:

StateHow to EnterBehavior
NavigationPress EscapeArrow keys move between cells. Input is blurred.
EditPress Enter, click input, or start typingArrow keys work within the input (cursor position, up/down for numbers).
  • Escape: Blurs the current input, switching to navigation mode where arrow keys move the cell focus
  • Enter: Focuses the current cell’s input, switching to edit mode
  • Click: Clicking directly on an input naturally focuses it (edit mode)
  • Arrow Keys: In navigation mode, use arrow keys to move between cells. In edit mode, arrows work within the input (e.g., moving cursor in text, incrementing numbers)

This mimics Excel/Google Sheets behavior where you can quickly navigate a grid with arrows, then press Enter to edit a cell.

Built-in Editors

Section titled “Built-in Editors”

The grid provides appropriate editors based on column type:

Column TypeEditor
stringText input
numberNumber input with validation
booleanCheckbox
dateDate picker input
selectDropdown (requires options array)

Editor Parameters

Section titled “Editor Parameters”

Configure built-in editors using the editorParams property. This allows you to set constraints and attributes without creating a custom editor.

Double-click cells to edit. Each column uses editorParams to customize the editor — min/max for numbers, maxLength/pattern for text, date ranges, and select placeholders.

Number Editor

Section titled “Number Editor”
{
  field: 'price',
  type: 'number',
  editable: true,
  editorParams: {
    min: 0,           // Minimum value
    max: 1000000,     // Maximum value
    step: 0.01,       // Increment for up/down arrows
    placeholder: 'Enter price'
  }
}

Text Editor

Section titled “Text Editor”
{
  field: 'name',
  editable: true,
  editorParams: {
    maxLength: 100,          // Maximum character length
    pattern: '[A-Za-z\\s]+', // HTML5 validation pattern
    placeholder: 'Enter name'
  }
}

Date Editor

Section titled “Date Editor”
{
  field: 'startDate',
  type: 'date',
  editable: true,
  editorParams: {
    min: '2024-01-01',      // Minimum date (ISO format)
    max: '2024-12-31',      // Maximum date (ISO format)
    placeholder: 'Select date',
    default: '2024-01-01'   // Fallback when non-nullable column is cleared
  }
}

Select Editor

Section titled “Select Editor”
{
  field: 'status',
  type: 'select',
  editable: true,
  options: [
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' }
  ],
  editorParams: {
    includeEmpty: true,          // Add empty option at start
    emptyLabel: '-- Select --'   // Label for empty option
  }
}

TypeScript Types

Section titled “TypeScript Types”
import type {
  EditorParams,
  NumberEditorParams,
  TextEditorParams,
  DateEditorParams,
  SelectEditorParams
} from '@toolbox-web/grid/plugins/editing';

Nullable Columns

Section titled “Nullable Columns”

Use the nullable column property to control whether a field can be set to null. Both true and false actively manage empty-input behaviour; omitting nullable preserves the default behaviour for each editor type.

nullable: true

Section titled “nullable: true”

Editors allow clearing the field and commit null:

columns: [
  // Text & number: clearing the input commits null
  { field: 'nickname', editable: true, nullable: true },
  { field: 'bonus', type: 'number', editable: true, nullable: true },


  // Select: a "(Blank)" option is prepended that commits null
  {
    field: 'department', type: 'select', editable: true, nullable: true,
    options: [{ label: 'Engineering', value: 'eng' }, { label: 'Sales', value: 'sales' }],
  },


  // Date: clearing the date commits null
  { field: 'endDate', type: 'date', editable: true, nullable: true },
]

The select editor’s blank-option label defaults to "(Blank)" and can be customised via editorParams.emptyLabel.

nullable: false

Section titled “nullable: false”

Editors prevent null values by providing sensible defaults when the user clears a field:

EditorBehaviour when cleared
TextCommits "" (empty string)
NumberCommits editorParams.min if set, otherwise 0
DateCommits editorParams.default if set, otherwise today’s date
SelectNo blank option is shown — the user must pick a value
columns: [
  { field: 'name', editable: true, nullable: false },
  { field: 'price', type: 'number', editable: true, nullable: false,
    editorParams: { min: 1 } },              // clears to 1
  { field: 'startDate', type: 'date', editable: true, nullable: false,
    editorParams: { default: '2024-01-01' } }, // clears to Jan 1, 2024
]

Custom editors receive column.nullable via the ColumnEditorContext.column reference and can implement their own nullable logic.

Type-Level Defaults

Section titled “Type-Level Defaults”

Instead of configuring renderers and editors on every column, you can define type-level defaults that apply to all columns of a given type. This is especially useful for custom types like country, currency, or status that appear across multiple grids.

Grid-Level Type Defaults

Section titled “Grid-Level Type Defaults”

Define type defaults in your grid configuration:

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


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


// Define custom renderers/editors for types
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name', editable: true },
    { field: 'country', header: 'Country', type: 'country', editable: true },
    { field: 'priority', header: 'Priority', type: 'priority' },
  ],
  // Type defaults apply to all columns with matching type
  typeDefaults: {
    country: {
      renderer: (ctx) => {
        const span = document.createElement('span');
        span.textContent = `🌍 ${ctx.value}`;
        return span;
      },
      editor: (ctx) => {
        const select = document.createElement('select');
        ['USA', 'UK', 'Germany', 'France'].forEach(c => {
          const opt = document.createElement('option');
          opt.value = c;
          opt.textContent = c;
          select.appendChild(opt);
        });
        select.value = ctx.value;
        select.onchange = () => ctx.commit(select.value);
        return select;
      },
    },
    priority: {
      renderer: (ctx) => {
        const div = document.createElement('div');
        div.className = `priority-${ctx.value}`;
        div.textContent = ctx.value;
        return div;
      },
    },
  },
  features: { editing: true },
};

Application-Level Type Defaults

Section titled “Application-Level Type Defaults”

For defaults that apply across all grids in your application, use the framework adapter’s type registry:

Vanilla JS does not have an app-level provider — use gridConfig.typeDefaults on each grid instance as shown in the Grid-Level Type Defaults section above.

Resolution Priority

Section titled “Resolution Priority”

When resolving a renderer or editor, the grid checks in this order:

  1. Column-level — column.renderer or column.editor
  2. Grid-level — gridConfig.typeDefaults[column.type]
  3. App-level — Framework adapter’s type registry
  4. Built-in — Default editors for string, number, boolean, etc.

A column-level renderer/editor always takes precedence, allowing overrides when needed.

Editor Parameters Merging

Section titled “Editor Parameters Merging”

When using type defaults with editorParams, parameters are merged with column-level params taking precedence:

// Grid config
typeDefaults: {
  number: {
    editorParams: { min: 0, step: 1 }, // Type-level defaults
  },
}


// Column config
{ field: 'price', type: 'number', editorParams: { step: 0.01 } }


// Result: { min: 0, step: 0.01 } — column's step overrides type default

Custom Type Names

Section titled “Custom Type Names”

The type property accepts any string, not just built-in types. Use descriptive names for your domain:

type: 'country'    // Geographic data
type: 'currency'   // Money values
type: 'priority'   // High/Medium/Low
type: 'status'     // Active/Pending/Archived
type: 'rating'     // Star ratings

TypeScript provides IntelliSense for built-in types while allowing custom strings:

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


const type: ColumnType = 'country'; // Works! Custom types allowed

Custom Editors

Section titled “Custom Editors”

For specialized input needs, provide a custom editor function:

{
  field: 'status',
  header: 'Status',
  editable: true,
  editor: (ctx) => {
    const select = document.createElement('select');
    select.innerHTML = `
      <option value="pending">Pending</option>
      <option value="active">Active</option>
      <option value="completed">Completed</option>
    `;
    select.value = ctx.value;


    // Commit on change
    select.onchange = () => ctx.commit(select.value);


    // Cancel on Escape
    select.onkeydown = (e) => {
      if (e.key === 'Escape') ctx.cancel();
    };


    return select;
  },
}

Double-click the Priority column to see button-based editing:

Editor Context

Section titled “Editor Context”

The ctx object passed to custom editors contains:

PropertyTypeDescription
valueunknownCurrent cell value
rowTFull row data
columnColumnConfigColumn configuration
fieldstringField name
rowIdstringRow ID (from getRowId)
commit(value)functionCall to save new value
cancel()functionCall to discard changes
updateRow(changes)functionUpdate other fields on the same row (triggers cell-change events)
onValueChange(cb)functionRegister a callback to receive pushed values when the cell’s value changes externally (e.g., via updateRow from another cell’s commit)

Cascade Updates (onValueChange)

Section titled “Cascade Updates (onValueChange)”

When one cell’s commit updates other fields via updateRow(), any editors open on those fields receive the new value automatically. The grid does this for built-in editors out of the box.

For custom editors, use onValueChange to keep your inputs in sync:

{
  field: 'total',
  editable: true,
  editor: (ctx) => {
    const input = document.createElement('input');
    input.type = 'number';
    input.value = String(ctx.value);


    // Stay in sync when another cell updates this field
    ctx.onValueChange?.((newValue) => {
      input.value = String(newValue ?? '');
    });


    input.onchange = () => ctx.commit(Number(input.value));
    return input;
  },
}

This is especially useful when fields are interdependent — for example, updating quantity recalculates total:

grid.on('cell-commit', ({ field, row, value, updateRow }) => {
  if (field === 'quantity') {
    const price = row.price;
    updateRow({ total: price * value });
  }
});

Keyboard Shortcuts

Section titled “Keyboard Shortcuts”
KeyAction
Enter (not editing)Start editing focused row
Enter (while editing)Commit edit and move down
TabCommit and move to next editable cell
Shift+TabCommit and move to previous editable cell
EscapeCancel edit, restore original value

Events

Section titled “Events”
Event Log:

The EditingPlugin emits events during the editing lifecycle. Double-click a cell to edit, then press Enter or click away to see the events:

EventTypeDescription
edit-openEditOpenDetailFired when a row enters edit mode (row mode only)
before-edit-closeBeforeEditCloseDetailFires synchronously before edit state is cleared on commit (row mode only). Managed editors (e.g. Angular Material overlay, MUI Popover) can flush pending values. Does not fire on revert.
edit-closeEditCloseDetailFired when a row exits edit mode — commit or cancel (row mode only)
cell-commitCellCommitDetailFired when a cell value is committed (cancelable)
row-commitRowCommitDetailFired when a row editing session ends (cancelable)
changed-rows-resetChangedRowsResetDetailFired when resetChangedRows() is called
dirty-changeDirtyChangeDetailFired when a row’s dirty state changes (requires dirtyTracking: true)

Cell Validation

Section titled “Cell Validation”
Validation Rules:
  • Email: Must contain @
  • Salary: Must be positive (> 0)

Try entering invalid values, then click outside the row.

Use setInvalid() in the cell-commit event to mark cells as invalid without canceling the edit. Invalid cells are highlighted with a red outline and can be styled with CSS custom properties.

Use preventDefault() in the row-commit event to reject the entire row if validation fails, reverting all changes to the original values.

Validation Methods

Section titled “Validation Methods”

The EditingPlugin provides these methods for managing validation state:

MethodDescription
setInvalid(rowId, field, message?)Mark a cell as invalid
clearInvalid(rowId, field)Clear invalid state for a cell
clearRowInvalid(rowId)Clear all invalid cells in a row
clearAllInvalid()Clear all invalid cells
isCellInvalid(rowId, field)Check if a cell is invalid
hasInvalidCells(rowId)Check if a row has any invalid cells
getInvalidMessage(rowId, field)Get the validation message

CSS Custom Properties

Section titled “CSS Custom Properties”

Style invalid cells by overriding these CSS variables:

tbw-grid {
  --tbw-invalid-bg: #fef2f2;
  --tbw-invalid-border-color: #ef4444;
}

Configuration Validation

Section titled “Configuration Validation”

If you use editable: true or editor without enabling the editing feature, the grid throws a helpful error:

[tbw-grid] Configuration error:


Column(s) [name, price] use the "editable" column property, but the required plugin is not loaded.
  → Enable the feature:
    import '@toolbox-web/grid/features/editing';
    features: { editing: true }

This runtime validation helps catch misconfigurations early during development.

Focus Management

Section titled “Focus Management”

Focus Trap

Section titled “Focus Trap”

Enable focusTrap to prevent accidental focus loss during editing. When focus leaves the grid during an active edit, it is automatically returned to the editing cell:

features: {
  editing: {
    editOn: 'dblclick',
    focusTrap: true,
  },
}

Elements registered via grid.registerExternalFocusContainer() are excluded from the trap — overlays (datepickers, dropdowns) continue to work normally.

External Focus Containers

Section titled “External Focus Containers”

Custom editors that append elements to <body> (e.g., datepicker overlays, dropdown panels) should register with the grid so focus inside them doesn’t close the editor:

// In your editor function — get the grid element from the DOM
editor: (ctx) => {
  const input = document.createElement('input');
  const overlay = document.createElement('div');
  overlay.className = 'my-overlay';
  document.body.appendChild(overlay);


  // Get the grid element to register the overlay
  const grid = input.closest('tbw-grid');
  grid?.registerExternalFocusContainer(overlay);


  // When done, unregister
  const origCancel = ctx.cancel;
  ctx.cancel = () => {
    grid?.unregisterExternalFocusContainer(overlay);
    overlay.remove();
    origCancel();
  };


  return input;
}

Angular: BaseOverlayEditor handles registration automatically.

Dirty Tracking

Section titled “Dirty Tracking”

Enable dirty tracking to compare each row’s current data against its original (baseline) snapshot. This lets you detect which rows have been modified, display visual indicators, and revert changes — useful for “save changes” workflows.

Configuration

Section titled “Configuration”
features: {
  editing: {
    dirtyTracking: true,
  },
}

When enabled, the plugin captures a deep-clone baseline of each row when data is first loaded (or when grid.rows is reassigned). Baselines are keyed by row ID, so gridConfig.getRowId (or a row id/_id property) is required.

API Methods

Section titled “API Methods”

Access via grid.getPluginByName('editing'):

Method / PropertyReturnsDescription
isDirty(rowId)booleanWhether the row differs from its baseline
isPristine(rowId)booleanOpposite of isDirty
dirtybooleanWhether any row is dirty
pristinebooleanWhether all rows are pristine
getDirtyRows()DirtyRowEntry[]All dirty rows with { id, original, current }
dirtyRowIdsstring[]IDs of all dirty rows
getOriginalRow(rowId)T | undefinedDeep clone of the baseline row
markAsPristine(rowId)voidRe-snapshot baseline from current data (call after save)
markAsDirty(rowId)voidForce-mark a row dirty (e.g., after external mutation)
markAllPristine()voidRe-snapshot all baselines (call after batch save)
revertRow(rowId)voidRevert a row to its baseline values

Events

Section titled “Events”

The dirty-change event fires whenever a row’s dirty state changes:

grid.on('dirty-change', ({ rowId, row, original, type }) => {
  // type: 'modified' | 'new' | 'reverted' | 'pristine'
  console.log(`Row ${rowId}: ${type}`);
});

Example: Save Workflow

Section titled “Example: Save Workflow”
const editing = grid.getPluginByName('editing');


// Check if there are unsaved changes
if (editing.dirty) {
  const dirtyRows = editing.getDirtyRows();
  await api.saveAll(dirtyRows.map(r => r.current));
  editing.markAllPristine();
}

Row CSS Classes

Section titled “Row CSS Classes”

When dirty tracking is enabled, the EditingPlugin automatically applies CSS classes to rows based on their state:

CSS ClassApplied When
tbw-row-dirtyRow data differs from its baseline
tbw-row-newRow was inserted via insertRow()

These classes are toggled after every render, so they stay in sync with the data.

Styling Dirty Rows

Section titled “Styling Dirty Rows”
tbw-grid .data-grid-row.tbw-row-dirty {
  background-color: #fffde7; /* Light yellow highlight */
}
tbw-grid .data-grid-row.tbw-row-new {
  background-color: #e8f5e9; /* Light green highlight */
}

Editing Stability

Section titled “Editing Stability”

When rows are sorted, filtered, or grouped while a row is being edited, the EditingPlugin preserves the active edit session. The plugin tracks the editing row by identity (object reference) and remaps the edit index after the data pipeline runs, so the editor stays attached to the correct row even when its position changes.

If the editing row is removed from the processed data (e.g., filtered out), the edit session is automatically canceled to prevent stale state.

See Also

Section titled “See Also”
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