DataGrid API reference

API reference

This page maps the DataGrid public API to the current package exports. Inputs, outputs, templates, exported types, services, and adapters listed here are available from @angular-bootstrap/ngbootstrap today.

On this page

Overview Basic Example How It Works Configuration API Reference Usage Notes Common Issues

Overview

The DataGrid public surface is spread across the main component export, the filtering and column model exports, the template directives, data operation helpers, and the editing/export services. This page documents only members exported by the package entry point today.

Scroll modes (v2.5.0)

NgbDataGridScrollMode accepts booleans, 'scrollable', 'none' and 'virtual'. Configure height, virtualRowHeight and virtualOverscan.

scrollToRow(index): boolean scrolls within the current processed page after rendering. Invalid indexes or unavailable scrolling return false. virtualScrollActive reports the effective mode; virtualScrollFallbackReason explains incompatible configurations. Scrolling does not change pages. Remote jumps may emit virtualRangeChange.

scrollTo({row?, column?}): reveal row and visible-column indexes. scrollToItem({idField, id}): find a loaded item. Both return a boolean.
virtualRangeChange: EventEmitter<NgbDataGridVirtualRange>: debounced remote request with skip, take and state. requestVirtualRange(force = false): request or retry the viewport.
scrollBottom: EventEmitter<void>: append-on-demand notification, once per collection at the bottom.
expandGroup(path) / collapseGroup(path): root index or nested index array, returns a boolean. setAllGroupsExpanded(expanded): expand all or collapse root groups.

Virtual scrolling example and limitations

Batch editing (2.4.0)

Use cellSelection, cellRangeChange, NgbGridBatchEditingDirective, Apply/Discard tools, clipboard conversion callbacks, batchSave and async batch history.

Import NgbGridBatchApplyToolDirective and NgbGridBatchDiscardToolDirective for native toolbar buttons. Access #batch="ngbGridBatchEditing" to call stagePaste(text), copySelection(), applyBatch() (Promise) and discardBatch(). Read pendingCount(), validating(), canApply(), errors() and message() for custom controls.

The directive accepts batchValidator and emits batchResult for native clipboard operations. The Apply tool emits its own batchResult. Column definitions accept clipboardParse(text, row) and clipboardFormat(value, row) for conversion. The grid exposes cellRange and clearCellRange().

Batch editing example, API contracts and limitations

Saved views (2.3.0)

captureView() returns a versioned NgbDataGridViewSnapshot. restoreView(snapshot) returns NgbDataGridViewRestoreResult and emits one dataStateChange on success. viewChange emits interactive configuration snapshots.

Exported APIs: NgbDataGridColumnView, NgbDataGridSavedView, NgbDataGridViewStore, NgbDataGridViewsComponent, NgbMemoryGridViewStore, NgbLocalStorageGridViewStore, ngbValidateGridView, ngbCloneGridView, ngbSerializeGridView, and ngbDeserializeGridView.

Views control API	Contract
`ngb-datagrid-views`	Standalone NgbDataGridViewsComponent.
`grid / storageKey`	Required grid instance and application-owned collection key.
`store`	NgbDataGridViewStore; defaults to an in-memory store. Local storage is opt-in.
`list(key)`	Returns Promise<NgbDataGridSavedView[]>.
`save(key, view) / delete(key, id)`	Return Promise<void>. Implement these for backend persistence.

Restoration returns to page one, reconciles changed columns and rejects active editors or invalid snapshots. Serialization helpers preserve Date filters; snapshots exclude row data.

Saved Views example and persistence guide

Undo/Redo (2.3.0)

NgbDataGridHistoryDirective adds configuration and saved-row-edit history. Use ngbGridHistory on the grid and #history="ngbGridHistory" to access it.

History API	Contract
`historyLimit`	Maximum retained steps; default 20, integer 1–1000.
`historyKeyboard`	Boolean, default true. Enables grid-scoped Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z and Ctrl+Y. Editable fields retain native undo.
`historyKeyboardResult`	Output: NgbDataGridHistoryResult after a shortcut action; use for live announcements.
`undo() / redo()`	Replay configuration or a single-row step; return NgbDataGridHistoryResult. Batch steps return async-required.
`undoAsync() / redoAsync() / busy()`	Async replay for every step type, including validated batches; busy is a read-only signal.
`record()`	Record application-driven configuration after inputs apply; returns a result.
`clear()`	Clear both stacks using the current configuration as baseline; returns a result.
`canUndo() / canRedo()`	Read-only boolean signals for available steps.
`undoCount() / redoCount()`	Read-only number signals.
`ready() / error()`	Read-only initialization and error-message signals.

Configuration replay emits one dataStateChange. Saved-edit replay emits one rowSave with historyAction set to undo or redo, without a data-state event. Active editors block replay.

NgbDataGridHistoryResult returns success and ignoredFields on success; failures return reason and message. Reasons: editing, invalid-snapshot, empty-history, not-ready, invalid-state, row-conflict, validation, async-required or busy.

Toolbar tools

Project button[ngbGridUndoTool] and button[ngbGridRedoTool] (NgbGridUndoToolDirective / NgbGridRedoToolDirective) into ngb-datagrid-toolbar. Both accept disabled and emit historyResult; labels, icons and classes are application-owned. Disabling a button does not disable shortcuts; use historyKeyboard for that.

NgbDatagridToolbarComponent requires grid, accepts ariaLabel (default “Grid toolbar”) and customContent (default true), and retains built-in search/export/add controls.

Undo/Redo example and complete directive API

Basic import example

import {
          Datagrid,
          ColumnDef,
          NgbCellTemplate,
          NgbEditorTemplate,
          NgbFilterTemplate,
          NgbRowDetailTemplate,
          NgbDatagridEditService,
          NgbDatagridDefaultEditService,
          NgbDatagridTrackByFn,
          NgbDataGridExportOptions,
          NgbExportService,
          PdfExportAdapter,
          ExcelExportAdapter,
          JsPdfAdapter,
          BrowserExcelExportAdapter
        } from '@angular-bootstrap/ngbootstrap';

How the API is organized

The component export includes the main grid plus selection and table option types declared in the component file.
ColumnDef and the filtering descriptors are exported from their model files.
Template directives are exported separately and matched by field name.
NgbExportService, PdfExportAdapter, ExcelExportAdapter, JsPdfAdapter, and BrowserExcelExportAdapter are public package exports used to wire built-in or custom export behavior.

API Information

Datagrid · Inputs
Property	Type	Default	Description
`[cellSelection]`	`'none' \| 'range'`	`'none'`	Opt in to current-page rectangular selection and cell keyboard navigation. Batch editing requires range mode and unique trackBy IDs.
`[columns]`	`ColumnDef<T>[]`	`[]`	Column definitions. Declarative `ngb-grid-column` content takes precedence when both are present.
`[data]`	`T[]`	`[]`	Row data bound into the grid.
`[loading]`	`boolean`	`false`	Shows a loading overlay and sets the grid busy state.
`[total]`	`number \| null`	`null`	Total row count for server-side paging when `data` contains only the current page.
`[enableSorting]`	`boolean`	`false`	Turns on header sorting for columns marked `sortable`.
`[enableFiltering]`	`boolean`	`false`	Legacy compatibility flag that enables filtering features.
`[filterable]`	`boolean \| 'row' \| 'menu' \| 'multi' \| 'none'`	`false`	Preferred filtering mode API. `true` maps to row filtering.
`[enableGlobalFilter]`	`boolean`	`false`	Shows the global filter input in the toolbar.
`[filterMode]`	`'row' \| 'menu' \| 'multi' \| 'none'`	`'row'`	Fallback mode used when `filterable` is not explicit.
`[filter]`	`NgbCompositeFilterDescriptor \| null`	`null`	Controlled filter descriptor for descriptor-based filtering.
`[filterOperators]`	`Partial<Record<ColumnType, NgbFilterOperator[]>>`	`undefined`	Overrides the allowed operators by column type.
`[filterManual]`	`boolean`	`false`	Emits `filterChange` without applying the descriptor locally.
`[externalFiltering]`	`boolean`	`false`	Treats `data` as already filtered while still rendering the filter UI.
`[dataOperations]`	`boolean \| NgbDataGridProcessOptions<T>`	`false`	Uses the reusable local operation helper for sort, filter, page, and aggregate processing.
`[groupable]`	`boolean \| NgbDataGridGroupingSettings`	`false`	Enables the group panel, group drag handles, and grouped row rendering. Use `showFooter` for grouped footer rows, `stickyHeaders` for pinned grouped headers, and `stickyFooters` for pinned grouped footers.
`[group]`	`NgbDataGridGroupDescriptor[]`	`[]`	Controlled group descriptors for one or more grouped fields.
`[groupedData]`	`NgbDataGridGroupResult<T>[] \| null`	`null`	Optional processed grouped result input for manual or server-owned grouping flows.
`[state]`	`NgbDataGridState \| null`	`null`	Controlled state for page, page size, skip, sort descriptors, group descriptors, filter descriptor, and global search.
`[enablePagination]`	`boolean`	`false`	Renders the built-in footer pager and page-size selector.
`[pageSize]`	`number`	`10`	Current page size used by the built-in pagination logic.
`[pageSizeOptions]`	`number[]`	`[5, 10, 25, 50]`	Page-size options shown in the footer selector.
`[enableEdit]`	`boolean`	`false`	Shows row edit actions and enables the edit form.
`[enableDelete]`	`boolean`	`false`	Shows row delete actions.
`[enableAdd]`	`boolean`	`false`	Shows the add-row button and renders the add form row.
`[newRowDefaults]`	`Partial<T> \| (() => Partial<T>) \| null`	`null`	Provides initial values for the add-row form.
`[strictEmail]`	`boolean`	`false`	Switches email validation to the stricter custom validator.
`[editOnRowClick]`	`boolean`	`false`	Starts editing when a non-interactive area of a row is clicked.
`[singleExpand]`	`boolean`	`false`	Limits detail-row expansion to one row at a time.
`[selectionMode]`	`'none' \| 'single' \| 'multiple'`	`'none'`	Enables row selection.
`[selectionBehavior]`	`'row' \| 'checkbox' \| 'both'`	`'row'`	Controls whether rows, checkboxes, or both can toggle selection.
`[selectionKeyMode]`	`'desktop' \| 'mobile'`	`'desktop'`	Desktop mode enables Ctrl/Cmd and Shift range selection behavior.
`[selectAllEnabled]`	`boolean`	`true`	Enables the current-page select-all checkbox when multi-select is active.
`[selectionA11yLabels]`	`NgbSelectionLabels`	`{}`	Overrides accessible labels for selection controls.
`[selectionDisabledFn]`	`(row: T, index: number) => boolean`	`undefined`	Disables selection for specific rows.
`[rowReorderable]`	`boolean`	`false`	Enables row drag handles and row reordering.
`[stickyRows]`	`boolean`	`false`	Shows the sticky-row utility column and keeps pinned rows at the top.
`[stickyHeader]`	`boolean`	`false`	Enables the sticky header when scrolling is active.
`[stickyFooter]`	`boolean`	`false`	Enables the sticky footer when scrolling is active.
`[stickyRowHeight]`	`number`	`40`	Height used to stack multiple sticky rows.
`[stickyHeaderHeight]`	`number`	`40`	Header offset used for stacked sticky rows.
`[stickyFooterHeight]`	`number`	`56`	Footer height used by the sticky-footer styling.
`[scrollable]`	`NgbDataGridScrollMode`	`true`	true / 'scrollable', false / 'none', or 'virtual'. Virtual mode renders local rows or application-managed remote windows; incompatible configurations use regular scrolling with a visible notice (v2.5.0).
`[height]`	`number \| null`	`null`	Body viewport height in pixels. Null retains the regular 24rem maximum or a 384px virtual viewport.
`[virtualRowHeight]`	`number`	`48`	Fixed virtual row height in pixels, minimum 32. Custom content must fit.
`[virtualOverscan]`	`number`	`5`	Extra virtual rows above and below the viewport, clamped to 0–100.
`[maxHeight]`	`number \| null`	`null`	Content-sized body maximum in regular scrolling; height takes precedence.
`[detailRowHeight]`	`number`	`160`	Fixed expanded detail height in virtual mode, minimum 32px.
`[virtualRemote]`	`boolean`	`false`	Requests flat remote windows through virtualRangeChange. Disable pagination; bind processed data, total and virtualSkip.
`[virtualSkip]`	`number`	`0`	Absolute offset of the loaded remote data array.
`[virtualPageSize]`	`number`	`60`	Requested remote buffer, at least three viewports plus overscan.
`[virtualDebounce]`	`number`	`80`	Delay in milliseconds before emitting the latest remote range request.
`[loadingCellTemplate]`	`TemplateRef<{ $implicit: ColumnDef; index: number }> \| null`	`null`	Custom placeholder cells for unloaded remote rows.
`[tableOptions]`	`NgbTableOptions`	`{}`	Applies Bootstrap table classes plus caption, responsive wrapper, and sticky flags.
`[theme]`	`'bootstrap' \| 'material' \| 'tailwind'`	`'bootstrap'`	Adds theme-specific CSS variables and button/table styling.
`[responsive]`	`boolean \| NgbDataGridResponsiveOptions`	`false`	Enables the small-screen stacked layout.
`[highlightedIndex]`	`Array<{ row: unknown; columnKey?: unknown }>`	`[]`	Declares highlighted rows or row/cell pairs.
`[highlightRowKey]`	`string \| ((row, rowIndex) => unknown) \| null`	`null`	Computes the row key used by `highlightedIndex`.
`[highlightColKey]`	`string \| ((column, columnIndex) => unknown) \| null`	`null`	Computes the column key used by `highlightedIndex`.
`[searchHighlightTerm]`	`string`	`''`	Highlights matching text fragments inside visible cells.
`[searchHighlightFields]`	`string[] \| null`	`null`	Limits search highlighting to specific column fields.
`[trackBy]`	`NgbDatagridTrackByFn<T>`	`undefined`	Provides a stable row identifier value for tracking, selection, sticky rows, and editing.
`[editService]`	`NgbDatagridEditService<T>`	`default service`	Overrides the built-in edit service for immutable or stateful editing workflows.
`[exportOptions]`	`NgbDataGridExportOptions`	`{ enabled: false, ... }`	Enables PDF and/or Excel export and configures the export mode.
`[dataProviderAll]`	`() => Observable<T[]> \| Promise<T[]> \| T[]`	`undefined`	Required when export pages mode is `all`.
`[dataProviderSelection]`	`() => T[]`	`undefined`	Required when export pages mode is `selection`.
`[columnReorderable]`	`boolean`	`false`	Enables drag-drop reordering for columns.
`[resizable]`	`boolean`	`false`	Enables drag resizing for explicit-width columns.

Datagrid · Outputs
Property	Type	Default	Description
`(cellRangeChange)`	`NgbGridCellRange \| null`	`-`	Selected anchor/focus addresses, or null when cleared. Ranges are excluded from view snapshots.
`(batchSave)`	`NgbGridBatchSaveEvent<T>`	`-`	One event after local batch Apply or replay, containing original/updated rows and optional historyAction. Update the bound array and persist through the application.
`(rowAdd)`	`{ newRow: T }`	`-`	Emits after a new row passes validation and the add flow saves.
`(rowEdit)`	`{ row: T; index: number }`	`-`	Emits when inline or toolbar editing starts for an existing row. In-cell and external editing do not emit this event.
`(viewChange)`	`NgbDataGridViewSnapshot`	`-`	Emits grid configuration snapshots for saved views and history; excludes row data.
`(rowSave)`	`{ original: T; updated: T; index: number; historyAction?: 'undo' \| 'redo' }`	`-`	Emits after saving an edit, including history replay. historyAction identifies Undo/Redo; persist replayed edits through this handler.
`(rowCancel)`	`{ row: T; index: number }`	`-`	Emits when edit mode is cancelled.
`(rowDelete)`	`{ row: T; index: number }`	`-`	Emits after a row delete action runs.
`(groupChange)`	`NgbDataGridGroupChange`	`-`	Emits the current ordered group descriptors after panel or API grouping changes.
`(sortChange)`	`{ active: string \| null; direction: 'asc' \| 'desc' \| '' }`	`-`	Emits the current sort state after the header cycle changes.
`(filterChange)`	`NgbCompositeFilterDescriptor`	`-`	Preferred filtering event for descriptor-driven filtering.
`(filtersChange)`	`{ global: string; columns: Record<string, string> }`	`-`	Legacy compatibility event for global and column filter text state.
`(pageChange)`	`{ page: number; pageSize: number }`	`-`	Emits when the built-in pager changes page or page size.
`(dataStateChange)`	`NgbDataGridState`	`-`	Emits complete sort, filter, page, page size, skip, and global filter state.
`(selectionChange)`	`{ selected: T[]; lastAction: { row: T; index: number; selected: boolean } \| null }`	`-`	Emits the selected rows and the last selection action.
`(rowReorder)`	`{ row: T; fromIndex: number; toIndex: number; data: T[] }`	`-`	Emits after row drag-drop reorders the data.
`(columnReorder)`	`NgbColumnReorderEvent<ColumnDef<T>>`	`-`	Emits after column drag-drop reorders visible columns.

Datagrid · Template directives
Property	Type	Default	Description
`<ng-template ngbCell="field">`	`directive`	`-`	Overrides read-mode rendering for a column and receives `value`, `row`, `col`, and `index`.
`<ng-template ngbEditor="field">`	`directive`	`-`	Overrides the edit control for a column and receives `control`, `row`, `col`, `form`, `index`, and `isNew`.
`<ng-template ngbFilter="field">`	`directive`	`-`	Overrides the row-filter UI for a column and receives filter context helpers.
`<ng-template ngbFilterMenu="field">`	`directive`	`-`	Overrides the menu-filter UI for a column.
`<ng-template ngbGlobalFilter>`	`directive`	`-`	Overrides the toolbar global filter input and receives the global control.
`<ng-template ngbDatagridGroupHeaderTemplate>`	`directive`	`-`	Overrides the main grouped header row and receives field, value, items, level, count, and aggregates.
`<ng-template ngbDatagridGroupHeaderColumnTemplate="field">`	`directive`	`-`	Renders inside a grouped header cell for a specific column.
`<ng-template ngbDatagridGroupFooterTemplate="field">`	`directive`	`-`	Renders inside a grouped footer cell for a specific column when grouped footers are enabled.
`<ng-template ngbRowDetail>`	`directive`	`-`	Renders expandable detail content for each row and receives the row plus the paged index.
`<ng-template ngbExportButton>`	`directive`	`-`	Overrides the export toolbar buttons and receives a trigger function for `pdf` or `excel`.
`<ngb-grid-column ...>`	`directive`	`-`	Declarative column definition with the same inputs as `ColumnDef`.

Datagrid · Exported types
Property	Type	Default	Description
`NgbGridCellAddress / NgbGridCellRange`	`interface`	`-`	Stable rowId and field addresses; a range contains anchor and focus.
`NgbGridBatchRowChange<T> / NgbGridBatchSaveEvent<T>`	`interface`	`-`	A change contains rowId, original and updated. A save contains changes plus optional undo/redo historyAction.
`NgbGridBatchResult / NgbGridClipboardResult`	`type`	`-`	Discriminated success/failure results: changedCells or copied text on success; reason and message on failure.
`NgbGridBatchValidator<T> / NgbGridBatchCellError`	`type / interface`	`-`	Validator receives proposed changes and AbortSignal, returning cell errors or a Promise. Errors contain rowId, field and message.
`ColumnDef<T>`	`interface`	`-`	Column metadata for the grid, including sorting, filtering, editing, sticky, locked, width, and validation settings.
`NgbFilterDescriptor`	`interface`	`-`	Single filter rule with `field`, `operator`, optional `value`, and `ignoreCase`.
`NgbCompositeFilterDescriptor`	`interface`	`-`	Root filter tree with `logic` and nested filter descriptors.
`NgbFilterState`	`interface`	`-`	Convenience state shape with `global` plus a descriptor root.
`NgbFilterOperator`	`type`	`-`	Supported operators such as `contains`, `eq`, `gt`, `isnull`, and `isempty`.
`NgbFilterable`	`type`	`-`	Filtering mode input type: `boolean`, `row`, `menu`, `multi`, or `none`.
`NgbTableOptions`	`interface`	`-`	Bootstrap table presentation options plus caption, responsive wrapper, and sticky flags.
`NgbSelectionMode / Behavior / KeyMode`	`type`	`-`	Selection configuration types used by the row selection API.
`NgbSelectionLabels`	`interface`	`-`	Optional accessible labels for select-all and per-row selection controls.
`NgbDataGridExportOptions`	`interface`	`-`	Export configuration for PDF/Excel, page source, file names, and adapter-specific options.
`NgbDataGridGroupDescriptor`	`interface`	`-`	Grouped field descriptor with `field`, optional ascending/descending `dir`, and optional per-group `aggregates`.
`NgbDataGridGroupingSettings`	`interface`	`-`	Grouping configuration object with `showFooter`, `stickyHeaders`, and `stickyFooters`.
`NgbDataGridGroupChange`	`interface`	`-`	Event payload emitted by `(groupChange)` with the active descriptor list.
`NgbDataGridGroupResult<T>`	`interface`	`-`	Nested local or provided grouping result with field, value, level, count, optional aggregate results, and child items.
`NgbDataGridState`	`interface`	`-`	Unified data-operation state with page, page index, skip, page size, sort, group, filter, and global filter.
`NgbDataGridDataResult<T>`	`interface`	`-`	Processed rows plus total count, optional grouped data, and aggregate results.
`NgbDataGridProcessOptions<T>`	`interface`	`-`	Options for local data operations, global filter fields, columns, aggregate descriptors, provided grouped data, and paging.
`NgbDataGridAggregateDescriptor`	`interface`	`-`	Aggregate field and function descriptor for count, sum, avg, average, min, or max.
`NgbDataGridAggregateType`	`type`	`-`	Supported aggregate names used by descriptors and grouped aggregate results.
`NgbDataGridTheme`	`type`	`-`	Grid-scoped theme token name used by the DataGrid and theme picker.
`NgbDataGridResponsiveOptions`	`interface`	`-`	Responsive mode settings. The current implementation only checks `enabled`.
`NgbDatagridEditService<T>`	`interface`	`-`	Edit workflow contract used by the grid for create, update, delete, save, and cancel handling.
`NgbDatagridTrackByFn<T>`	`type`	`-`	Track-by callback that returns a stable row identifier value.
`NgbGridChartConfig<T>`	`interface`	`-`	Configuration for the Grid to Chart composite widget.
`NgbDataChartConfig`	`interface`	`-`	Standalone chart renderer configuration.
`NgbAdvancedSearchField / Rule`	`interfaces`	`-`	Reusable advanced search field and rule configuration.
`NgbSearchHighlightField`	`interface`	`-`	Field metadata for the search highlight widget.

Datagrid · Services and adapters
Property	Type	Default	Description
`NgbDatagridDefaultEditService<T>`	`class`	`-`	Default immutable edit service that tracks original rows and removes unsaved new rows on cancel.
`NgbExportService`	`class`	`-`	Delegates export calls to an injected PDF or Excel adapter.
`PdfExportAdapter / ExcelExportAdapter`	`abstract class`	`-`	Adapter contracts that power PDF and Excel export.
`JsPdfAdapter`	`class`	`-`	Built-in dependency-free PDF adapter that creates a simple browser-generated table PDF.
`BrowserExcelExportAdapter`	`class`	`-`	Built-in dependency-free Excel adapter that creates a browser-generated workbook.
`ngbApplyDataGridOperations`	`function`	`-`	Processes local arrays with filtering, global search, sorting, paging, and aggregates.
`ngbGroupData`	`function`	`-`	Groups local arrays by one or more field descriptors and returns nested group metadata.
`ngbCalculateDataGridAggregates`	`function`	`-`	Calculates local aggregate values for configured fields.
`NgbAdvancedSearchComponent`	`standalone component`	`-`	Reusable advanced search builder that emits DataGrid filter descriptors.
`NgbSearchHighlightComponent`	`standalone component`	`-`	Reusable search-highlight controls for DataGrid or any external list/grid.
`NgbGridChartComponent`	`standalone component`	`-`	Composite grid and Chart.js-backed chart widget.
`NgbDataChartComponent`	`standalone component`	`-`	Standalone chart renderer.
`NgbDataSparklineComponent`	`standalone component`	`-`	Inline sparkline renderer for cells or standalone layouts.
`NgbDatagridThemePickerComponent`	`standalone component`	`-`	Grid theme picker that emits NgbDataGridTheme values.

Usage notes

The package still exposes some legacy filtering inputs and outputs for compatibility, but new examples should prefer the descriptor-based API.
The responsive options type includes breakpoint fields that are not currently honored by the component logic. The docs intentionally describe only the implemented behavior.

Common issues

Do not document or depend on internal directives or helpers unless they are exported from the package public API.