DataGrid Feature Guide

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.

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
`[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]`	`boolean`	`true`	Controls whether the body wrapper becomes vertically scrollable.
`[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
`(rowAdd)`	`{ newRow: T }`	`-`	Emits after a new row passes validation and the add flow saves.
`(rowEdit)`	`{ row: T; index: number }`	`-`	Emits when a row enters edit mode.
`(rowSave)`	`{ original: T; updated: T; index: number }`	`-`	Emits after the edit form is validated and saved.
`(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
`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.