DataGrid batch editing

Example

The following example demonstrates updating dispatch quantities for several orders. Select the first Quantity cell, then paste two lines such as 12 and 18. Drafts have a dashed border. Apply commits both rows as one Undo step.

Pending cells: 0 · Undo: 0 · Redo: 0

Select a Quantity cell to begin.

No batch events yet.

Enable batch editing

Add ngbGridBatchEditing, enable range selection and editing, and supply a stable, unique string or number trackBy key. Mark protected columns with editable: false.

The following standalone example includes Apply, Discard and optional history controls. Customize their labels, icons and order in the existing grid toolbar.

      import { Component, signal } from '@angular/core';
import {
  ColumnDef, Datagrid, NgbDatagridToolbarComponent,
  NgbGridBatchEditingDirective, NgbGridBatchApplyToolDirective,
  NgbGridBatchDiscardToolDirective, NgbDataGridHistoryDirective,
  NgbGridUndoToolDirective, NgbGridRedoToolDirective,
  NgbGridBatchSaveEvent, NgbGridBatchRowChange, NgbGridBatchCellError,
} from '@angular-bootstrap/ngbootstrap';

interface Order { id: string; quantity: number; }

@Component({
  selector: 'app-order-batch',
  standalone: true,
  imports: [Datagrid, NgbDatagridToolbarComponent,
    NgbGridBatchEditingDirective, NgbGridBatchApplyToolDirective,
    NgbGridBatchDiscardToolDirective, NgbDataGridHistoryDirective,
    NgbGridUndoToolDirective, NgbGridRedoToolDirective],
  template: `
    <ngb-datagrid #grid ngbGridHistory ngbGridBatchEditing
      #batch="ngbGridBatchEditing" cellSelection="range"
      [enableEdit]="true" [trackBy]="rowKey"
      [columns]="columns" [data]="rows" [batchValidator]="validate"
      (batchSave)="onSave($event)">
      <ngb-datagrid-toolbar [grid]="grid" ariaLabel="Order editing">
        <button ngbGridBatchApplyTool>Apply changes</button>
        <button ngbGridBatchDiscardTool>Discard</button>
        <button ngbGridUndoTool>Undo</button>
        <button ngbGridRedoTool>Redo</button>
      </ngb-datagrid-toolbar>
    </ngb-datagrid>
    <p role="status">{{ batch.message() || saved() }}</p>
    @for (error of batch.errors(); track $index) {
      <p>{{ error.rowId }} / {{ error.field }}: {{ error.message }}</p>
    }
  `,
})
export class OrderBatchComponent {
  readonly saved = signal('');
  readonly rowKey = (_index: number, row: Order) => row.id;
  rows: Order[] = [
    { id: 'ORD-4201', quantity: 4 },
    { id: 'ORD-4202', quantity: 6 },
  ];
  readonly columns: ColumnDef<Order>[] = [
    { field: 'id', header: 'Order', editable: false },
    { field: 'quantity', header: 'Quantity', type: 'number', required: true },
  ];
  readonly validate = (
    changes: readonly NgbGridBatchRowChange<Order>[],
    _signal: AbortSignal,
  ): NgbGridBatchCellError[] => changes
    .filter(change => change.updated.quantity < 1 || change.updated.quantity > 100)
    .map(change => ({ rowId: change.rowId, field: 'quantity',
      message: 'Use a quantity from 1 to 100.' }));

  onSave(event: NgbGridBatchSaveEvent<Order>): void {
    const updated = new Map(event.changes.map(change => [change.rowId, change.updated]));
    this.rows = this.rows.map(row => updated.get(row.id) ?? row);
    this.saved.set(event.changes.length + ' rows saved locally.');
    // Send event.changes to your backend here, including undo/redo events.
    // This example has no server persistence.
  }
}
    

A paste starts at the upper-left cell of the selected range and targets existing editable cells on the current page. It does not insert rows or repeat values to fill a larger selection.

Validate and save changes

Apply checks column types and required fields, then runs your optional batchValidator. Return cell errors, or a Promise of errors, to prevent the entire batch from committing. Invalid drafts remain visible for correction; Discard clears them without changing saved values.

For asynchronous validation, use the supplied AbortSignal to cancel requests when drafts are discarded. Show batch.errors() in a visible summary and batch.message() in a status region.

Persist batchSave.changes as one backend transaction. This demo reports events locally; it does not contact a server. Replayed batches use the same event. No per-row rowSave or dataStateChange is emitted.

Apply updates the grid’s local data before batchSave fires. Update your bound array from the event as shown above; it does not wait for a server response. Your app must prevent further editing while a save is pending and handle authorization and failure recovery. If saving fails, reload authoritative data and clear history before allowing more edits.

Undo and redo

Add ngbGridHistory to record each successful Apply as one history step. Undo and Redo validate and restore the whole batch together, and emit one batchSave event with historyAction set to undo or redo. Save these events through the same persistence handler.

Toolbar tools and keyboard shortcuts handle asynchronous replay automatically. For custom application controls, use await history.undoAsync() or redoAsync(). Conflicts or validation errors leave all rows and the history step unchanged.

Keyboard and accessibility

Use arrows to move, Shift+arrows to extend the range, Home/End within the row and Escape to clear selection. Ctrl/Cmd+C and V copy/paste. Ctrl/Cmd+Z undoes; Ctrl/Cmd+Shift+Z or Ctrl+Y redoes. Tab reaches toolbar buttons; Enter/Space activates them.

Native editors retain text shortcuts. Selection uses aria-selected, errors use aria-invalid, and the grid announces status. Save/cancel an editor or apply/discard drafts before replay. Async replay disables history tools. Provide visible labels and a validation summary when building custom controls. Touch-drag range selection is not supported.