DetailGridOptions
Detail grid configuration object. Defines columns, paging, height, and recursive nesting configuration.
Props
The following table outlines the props for the DetailGridOptions:
| Name | Type | Default | Description |
|---|---|---|---|
| aggregates | null | Configures summary rows with aggregate functions.
The aggregates property allows you to add summary rows to the grid, such as totals, averages, or counts.
Each aggregate row can contain multiple aggregations that apply functions like | |
| allowKeyboard | boolean | true | Controls whether keyboard navigation is enabled for the Data Grid. By default, navigation and interaction with grid elements can be performed using keyboard shortcuts and arrow keys. When set to false, the grid's default focus navigation behavior is disabled. |
| autoFillSettings | undefined | Enables cell fill (autofill) behavior when selection and editing are active. Allows dragging selected cells to fill adjacent cells with repeated or sequential values. | |
| autoFit | null | Defines the default auto-fit scope applied to columns that omit a per-column | |
| childDataPath | string | undefined | Path to child data in the parent row object.
Specifies which property contains the array of child rows for nested detail grids.
Used in conjunction with |
| clipMode | ClipMode | string | ClipMode.Ellipsis | 'Ellipsis' | Defines the cell content's overflow mode. The available modes are:
|
| clipboardSettings | { enabled: true } | Configures clipboard copy and paste functionality for the grid. Enables or disables copy/paste operations on selected cells or rows. | |
| columnChooserSettings | { enableSearch: true, operator: 'startsWith', ignoreAccent: false, sortDirection: 'None', selectedColumns: [] } | Defines the configuration for the Column Chooser dialog, controlling both its behavior and appearance. Enables customization of:
| |
| columnMenuSettings | - | Settings for the inline column menu displayed inside header cells.
When | |
| columns | - | Array of column definitions for detail grid. Specifies visible columns and their properties. | |
| contextMenuSettings | { enabled: false, items: [], menuSettings: {} } | Configures the context menu settings for the Data Grid component. Enables and customizes the context menu that appears on right‑click interactions. Provides options to:
| |
| customizePivotColumn | (context: PivotColumnContext<T>) => PivotColumnOverrides | undefined | - | Returns presentation overrides for generated pivot value columns on the UI thread. Pure callbacks may run repeatedly. User presentation adjustments take precedence. Templates receive generated pivot rows, not source records. Omitted callbacks preserve defaults. |
| customizePivotColumnGroup | (context: PivotColumnGroupContext<T>) => PivotColumnGroupOverrides | undefined | - | Returns presentation overrides for generated pivot group headers on the UI thread. Custom header templates retain the built-in expand/collapse control. Pure callbacks may run repeatedly; exceptions propagate to the React error boundary. |
| dataSource | [ ] | Supplies the data to be displayed in the grid. The data source can be provided as:
| |
| defaultExpandedRows | number[] | [ ] | Specifies row indices that should be expanded by default when the grid loads.
Applies only when the master-detail feature enabled using |
| detailCellRendererParams | undefined | Recursive detail grid configuration for third level. Enables 3-level nesting by specifying detail config for child detail grids. | |
| detailRowHeight | number | 300 | Defines the height of the detail row.
By default, the detail row height is set to "300px".
A custom height can be applied when the master‑detail feature is enabled |
| detailRowTemplate | - | Template for rendering the content of a detail row. Invoked for each expanded master row, providing its row data. Commonly used to render a nested Grid or other custom components. | |
| dragAndDropSettings | { enabled: false } | Configures row drag-and-drop between grid instances. | |
| editSettings | { allowAdd: false, allowEdit: false, allowDelete: false, mode: 'Normal', editOnDoubleClick: true, confirmOnEdit: true, confirmOnDelete: false, newRowPosition: 'Top' } | Configures the editing behavior of the Data Grid. The editSettings property enables and controls editing functionality. It defines which editing operations are permitted, such as adding, editing, and deleting rows, and specifies the editing mode to be used. | |
| emptyRecordTemplate | ComponentType<void> | ReactElement | string | null | Template for displaying content when the grid has no records. Customizes what is displayed when the grid has no data to show. This can be provided as a string, React element, or a function that returns content. It provides better user experience by explaining why the grid is empty or suggesting actions to take. |
| enableAltRow | boolean | true | Determines whether the |
| enableAutoSpan | boolean | false | Enables automatic row and column span behavior for grid cells.
When set to true, adjacent cells with matching values automatically merge using both row and column spanning.
When set to false, automatic spanning is disabled and only explicit numeric span values are applied.
Cells must have |
| enableDevMode | boolean | true | Enables development-specific diagnostics for the grid component. When set to true, the grid outputs additional console warnings, validation messages, and debugging information to assist in identifying configuration issues and improving integration. When set to false, these development diagnostics are suppressed to reduce console noise and minimize runtime overhead. This is a non-reactive property and applies only during initial render. |
| enableGridChart | boolean | false | Enables chart options in the context menu. |
| enableHover | boolean | true | Controls whether hover effect is applied to grid rows. By default, rows are visually highlighted on pointer hover. When set to false, rows retain a static appearance regardless of pointer hover movement. |
| enableHtmlSanitizer | boolean | false | Controls HTML sanitization for grid content. When set to true, the grid will sanitize any suspected untrusted HTML content before rendering it. This helps prevent cross-site scripting (XSS) attacks by removing or neutralizing potentially malicious scripts and HTML. |
| enableStickyHeader | boolean | false | Makes the grid header remain visible during scrolling. When enabled, column headers will "sticky" to the top of the viewport and remain visible even when the user scrolls down through the grid data. This improves usability by keeping column headers in view at all times. |
| excludeChildrenWithFiltering | boolean | false | Excludes child nodes from filtered tree results when a parent row matches the active filter.
Useful when filtering a tree should keep only matching parent rows and hide descendant rows unless they individually match.
Used when |
| filterSettings | { enabled: false, columns: [], type: 'FilterBar', mode: 'Immediate', immediateModeDelay: 1500, ignoreAccent: false, operators: null, caseSensitive: false } | Specifies the filtering configuration for the grid, controlling the filter UI and behavior. Includes options to enable/disable filtering, set the filter UI type, define custom operators, and configure case or accent sensitivity. Used to tailor the filtering experience to match application requirements and data types. | |
| formulaSettings | { enabled: false } | Configures spreadsheet-style formula processing for explicitly enabled columns. | |
| getRowHeight | (props: Partial<RowInfo<T | GroupedData<T>>>) => number | - | Gets the height of a specific row dynamically at runtime. Accepts a callback function that returns the height in pixels based on row information, allowing row-specific height customization. This property enables dynamic row sizing based on content, data values, or other custom logic. |
| gridLines | GridLine | string | 'Default' | Configures the visibility of grid lines between cells. Determines which grid lines are displayed in the grid. Available options are:
|
| groupSettings | { enabled: false, columns: [], defaultExpanded: false, captionFormat: 'compact', showDropArea: false, showGroupedColumn: false, showUngroupButton: false } | Specifies the grouping configuration for the grid, enabling hierarchical data organization by column values. Controls group expansion, drag-drop UI, caption formatting, and visibility of grouped columns. Used to organize data into collapsible groups for improved readability and analysis. | |
| height | string | number | '100%' | Grid height in pixels or percentage. Constrains detail grid height in expanded row. |
| id | string | React.useId() | Specifies a unique identifier for the grid component. Provides a distinct ID for the grid instance, enabling targeted interactions, styling, or accessibility features. Used to differentiate multiple grid instances within the same application or DOM. |
| isMasterDetail | boolean | false | Enable master-detail (expandable rows) feature for this grid. When enabled, all data rows become expandable master rows. |
| isRowPinnable | (row: T) => boolean | undefined | Callback that determines whether a row is eligible for pinning.
Invoked for each row to determine if pinning actions (such as context menu options)
should be available for that row. Returning |
| isRowPinned | (row: T) => 'top' | 'bottom' | null | undefined | undefined | Callback that determines whether a row should be pinned and to which position.
Invoked for each data row during rendering to determine its pinning bucket.
Returning |
| isRowSelectable | - | Callback to determine whether a row is selectable and how its checkbox renders. | |
| isTreeMode | boolean | false | Enable tree mode for hierarchical data display. When enabled, uses individual tree props for configuration instead of treeDataSettings object. Provides a simplified root-level API for tree grid functionality. |
| loadingIndicatorSettings | { indicatorType: LoadingIndicatorType.Spinner, params: { visible: true, thickness: '3px', animationDuration: '1s', overlay: true, size: '36px', color: Color.Primary }} | Configures loading indicator settings for the Data Grid component. Applies spinner or skeleton customization during data operations. | |
| maxNestingDepth | number | 3 | Maximum nesting levels allowed in hierarchical grids. Limits recursive detail grid expansion depth. Level 1: Master grid, Level 2: First detail grid, Level 3: Second detail grid. |
| modules | {} | Defines the feature modules to be injected into the Grid.
Injecting modules enables optional functionality and improves tree-shaking by
including only the required features in the application bundle.
To enable clipboard operations such as copy, paste, cut, and copy with headers,
inject the | |
| pageSettings | { /** * Number of rows per page in detail grid. */ pageSize?: number; } | undefined (no paging) | Paging configuration for detail grid rows per page. Enables pagination for large child datasets. |
| pinningSettings | undefined | Global configuration settings for pinning behavior across both rows and columns.
Controls whether pinning is enabled, which dimensions ( | |
| pivotSettings | undefined | Configures client-side relational pivoting for the Grid.
Defines report fields, aggregate values, member filters, result totals,
expansion defaults, generated-column limits and execution behavior.
Requires | |
| query | new Query() | Defines a query to execute against the data source.
Allows you to apply a predefined | |
| reorderSettings | { enabled: false } | Configures the column reorder feature at grid scope. | |
| resizeSettings | { enabled: false, mode: ResizeMode.Auto, throttle: 150, resizeKeyboardStep: 10 } | Configures the column resize feature at grid scope. Controls the resize handle rendering, drag and keyboard resize interactions, distribution mode, keyboard step, and throttle interval. | |
| rowClass | string | ((props?: RowClassProps<T>) => string) | - | Applies a CSS class to each grid row either globally or conditionally.
Accepts a static class name or a callback function that returns a class name based on row context.
The callback receives a
|
| rowHeight | number | 36 | Grid row height in pixels. Sets uniform row height for all detail grid rows. |
| rowNumberSettings | { enabled: false } | Configures the display of sequential row numbers in the grid. | |
| rowTemplate | ComponentType<CT> | ReactElement | string | null | Specifies a custom template for rendering rows in the grid. Allows complete customization of row rendering by providing a template that replaces the default row structure. This can be a string template, React element, or function that returns the row content. |
| searchSettings | { enabled: false, fields: [], value: undefined, operator: 'contains', caseSensitive: true, ignoreAccent: false } | Specifies the search configuration for the grid, controlling how data is searched. Defines settings for enabling the search bar, specifying searchable fields, initial search terms, operators, and case/accent sensitivity. Used to customize the search experience for filtering grid data. | |
| selectionSettings | { enabled: true, mode: 'Single', enableToggle: false } | Configures the grid's selection settings, determines whether | |
| showColumnChooser | boolean | false | Determines whether the column chooser functionality is enabled. When set to false (default), the column chooser button will be disabled in the toolbar (but still visible if included in toolbar array). When set to true, the column chooser button will be enabled and the dialog can be opened. This property controls the enabled/disabled state of the column chooser feature, not its visibility. To show the column chooser button, you must include 'ColumnChooser' in the toolbar array. |
| sideBar | undefined | Configures the optional grid sidebar and its tool panels. | |
| sortSettings | { columns: [], allowUnsort: true, enabled: false, mode: 'Multiple' } | Specifies the sorting configuration for the grid, includes options to enable/disable sorting and controlling how data is ordered. Used to customize sorting behavior for data presentation and user interactions. | |
| textWrapSettings | { enabled: false, wrapMode: 'Both' } | Specifies the text wrapping configuration for the grid, controlling how text is displayed. Defines the wrap mode to determine which grid sections (header, content, or both) apply text wrapping. Used to customize text display for readability and layout optimization. | |
| theme | Theme.Material | Specifies the theme configuration for the Data Grid component.
Used internally to determine default values for theme-dependent properties (e.g., row height in virtualization).
The theme property defines static default values and calculations used during grid initialization and rendering,
such as the default | |
| toolbar | Array<string | ToolbarItemProps> | null | Configures the grid toolbar with predefined or custom items. The toolbar property allows you to add a toolbar to the grid with both predefined actions (add, edit, delete, update, cancel, search) and custom items. Custom items can include text, template content, and click handlers. |
| treeColumnIndex | number | 0 | Column index where tree expand/collapse UI should render.
Specifies which column displays the expand/collapse buttons and indentation.
Used when |
| treeDataChildrenField | string | null | Field name containing children array for nested tree data mode.
Expects an array field at the specified field name containing child objects.
Used when |
| treeDataIdMapping | string | null | Unique identifier field name for parent ID tree mode.
Used in conjunction with |
| treeDataParentIdField | string | null | Parent identifier field name for parent ID tree mode.
References the parent node using the value from |
| virtualizationSettings | { enabled: true, type: VirtualDomType.Both, viewPortBuffer: { rows: 5, columns: 5 }, scrollMode: ScrollMode.Auto, preventMaxRenderedRows: false} | Configures virtualization behavior for grid rendering. Includes options for enabling virtualization, defining DOM type, and customizing buffer and scroll settings. | |
| width | number | string | 'auto' | Sets the width of the grid component. Controls the horizontal size of the grid. Can be specified as:
|
Events
The following table outlines the events for the DetailGridOptions:
| Name | Type | Description |
|---|---|---|
| onCellClick | (event: CellFocusEvent<T>) => void | Fires when a grid cell is clicked. Provides details about the clicked cell. |
| onCellDeselect | (event: CellDeselectEvent<T>) => void | Fires after cells are successfully deselected in the grid. Provides details about the deselected cells. Only fires when selectionSettings.type is 'Cell'. |
| onCellEditStart | (event: CellEditEvent<T>) => void | Fires when cell editing begins in |
| onCellFillComplete | (args: CellFillCompletedEvent<T>) => void | Fires when a cell fill operation completes. |
| onCellFillStart | (args: CellFillStartedEvent) => void | Fires when a cell fill operation begins. |
| onCellFocus | (event: CellFocusEvent<T>) => void | Fires when a grid cell gains focus. Provides details about the focused cell. |
| onCellSelect | (event: CellSelectEvent<T>) => void | Fires after cells are successfully selected in the grid. Provides details about the selected cells including data and positions. Only fires when selectionSettings.type is 'Cell'. |
| onClipboardCopy | (args: ClipboardCopyEvent) => void | Fires when data is copied to the clipboard from the Grid. Triggered after the copy operation completes, providing details about the copied content, selected rows/cells, and allowing cancellation of the operation. Use Cases:
|
| onClipboardCut | (args: ClipboardCutEvent) => void | Fires when data is cut from the grid using Ctrl+X. Triggered when cut operation completes, providing details about the cut content, selected rows/cells, and allowing cancellation of the operation. Use Cases:
|
| onClipboardPaste | (args: ClipboardPasteEvent) => void | Fires when data is pasted from the clipboard into the Grid. Triggered after paste operation completes, providing details about the pasted data, target location, and allowing cancellation of the operation. Use Cases:
|
| onColumnChooserApply | (event: ColumnChooserApplyEvent) => void | Fires when column changes are applied in the Column Chooser dialog. Triggered when the user clicks OK/Apply button with the final column visibility configuration. Used to track which columns were shown/hidden and perform post-apply actions. |
| onColumnChooserBeforeOpen | (event: ColumnChooserBeforeOpenEvent) => void | Fires before the Column Chooser dialog is displayed or opened. Allows customization of column visibility or cancellation before the dialog appears. |
| onColumnDrag | (event: ColumnReorderEvent<T>) => void | Fires while a column reorder drag is in progress. |
| onColumnMenuClick | (event: ColumnMenuClickEvent) => void | Fires when a column menu item is selected. Provides the item identifier and the target column for custom logic. |
| onColumnMenuClose | (event: ColumnMenuCloseEvent) => void | Fires when the column menu is closed. Useful for resetting UI state after the menu finishes interacting. |
| onColumnMenuOpen | (event: ColumnMenuOpenEvent) => void | ColumnMenuOpenEvent | Promise<ColumnMenuOpenEvent> | Fires when the column menu is opened for a specific header column. Provides the menu items and the target column for customization or cancellation. |
| onColumnReorderEnd | (event: ColumnReorderEndEvent<T>) => void | Fires when a column reorder interaction ends. |
| onColumnReorderStart | (event: ColumnReorderStartEvent<T>) => void | Fires when a column reorder interaction begins. |
| onColumnResize | (event: ColumnResizeEvent) => void | Fires as the column width changes during an active resize interaction. Triggered continuously while the user drags the resize handle, steps with the keyboard, or when a programmatic resize/auto-fit updates a column. |
| onColumnResizeEnd | (event: ColumnResizeEndEvent) => void | Fires when a column resize interaction ends. Triggered on pointer-up of the resize handle, end of a keyboard resize step, or completion of a programmatic resize/auto-fit on each updated column. |
| onColumnResizeStart | (event: ColumnResizeStartEvent) => void | Fires when a column resize interaction begins. Triggered on pointer-down of the resize handle, keyboard focus activation, or the start of a programmatic resize/auto-fit. |
| onContextMenuClick | (event: ContextMenuClickEvent) => void | Fires when a context menu item is selected or clicked by the user.
Handles the action associated with the selected menu item, such as |
| onContextMenuClose | ( ) => void | Fires when the context menu is closed or hidden on the grid. Suitable for cleanup operations or resetting UI state after the context menu interaction completes. Triggered when the user dismisses the menu through selection, clicking outside, or pressing Escape. |
| onContextMenuOpen | (event: ContextMenuOpenEvent) => ContextMenuOpenEvent | Promise<ContextMenuOpenEvent> | Fires when the context menu is about to be opened or displayed on the grid. Allows customization, validation, or cancellation of the context menu before it appears. Provides access to the target element, menu items, and associated row/column data. Supports both synchronous and asynchronous menu item loading:
|
| onDataChangeCancel | (event: FormCancelEvent<T>) => void | Fires when a CRUD operation is cancelled. |
| onDataChangeComplete | (event: SaveEvent<T> | DeleteEvent<T>) => void | Fires when a create, update, or delete operation is completed. |
| onDataChangeRequest | (event: DataChangeRequestEvent<T>) => void | Fires when the grid's data source is changed. Monitors and responds to updates in the grid's data source. |
| onDataChangeStart | (event: SaveEvent<T> | DeleteEvent<T>) => void | Fires when a create, update, or delete operation is started. |
| onDataLoad | ( ) => void | Fires after data is successfully bound to the grid. Suitable for actions requiring fully loaded data. |
| onDataRequest | (event: DataRequestEvent) => void | Fires when grid data state changes due to sorting or paging. Monitors and responds to changes in grid state. |
| onDeleteDialogOpen | (eventArgs: DeleteDialogEventArgs) => void | Fires when the bulk‑delete confirmation dialog opens with cross‑page selection enabled. Allows customization of dialog options, such as disabling specific choices or setting the default selection. Use Cases:
|
| onError | (event: Error) => void | Fires when grid operations like sorting or filtering fail. Provides error details for handling and user feedback. |
| onFilter | (event: FilterEvent) => void | Fires after a filtering operation completes on the grid. Provides filter state details for post-filter actions. |
| onFilterDialogAfterOpen | (event: FilterDialogAfterOpenEvent) => void | Fires after the filter Dialog is fully displayed and ready for interaction. Suitable for initializing custom filter components or DOM manipulation. |
| onFormRender | (event: FormRenderEvent<T>) => void | Fires when the edit or add form is fully loaded and ready for user input. |
| onGridRenderComplete | ( ) => void | Fired when the grid is fully loaded and ready for user interaction. Suitable for actions requiring only on grid initially fully loaded data. |
| onGridRenderStart | ( ) => void | Fires at the start of grid initialization before data processing. and component mount.
This event is triggered during the React render phase, before the component is mounted to the DOM.
Useful for initial configurations or showing loading indicators.
Do not perform state updates in this callback, as they will trigger React warnings
about updating unmounted components. Use |
| onGroup | (args: OnGroupArgs) => void | Fires when a grouping operation occurs on the grid. Triggered by add/remove column, expand/collapse, or reorder group operations. Provides current grouped columns and operation type for custom handling. |
| onPageChange | (event: PageEvent) => void | Event triggered after a paging operation is completed on the grid. |
| onPinnedRowsChanged | (event: RowPinningEvent<T>) => void | Fires when a row changes its pinning state due to user interaction or programmatic update. Provides the affected row, its previous pin bucket, its current pin bucket, and the action performed. |
| onPivotChange | (event: PivotChangeEvent<T>) => void | Fires after interactive pivot configuration changes are applied. Triggered when report fields, member filters, sorting, totals or other pivot settings change through the integrated pivot controls. |
| onPivotError | (event: PivotErrorEvent) => void | Fires when pivot calculation or configuration validation fails. Triggered when the pivot report contains invalid fields or settings, unsupported data-source or scroll-mode combinations, exceeds the column limit, or encounters a calculation failure. |
| onRedoComplete | (event: RedoCompleteEvent) => void | Fires after a Grid-level redo request completes. |
| onRedoStart | (event: RedoStartEvent) => void | Fires before a Grid-level redo request is applied. |
| onRefresh | ( ) => void | Fired when the grid data is refreshed or updated. |
| onRowAddStart | (event: RowAddEvent<T>) => void | Fires when the process of adding a new row starts. |
| onRowDeselect | (event: RowSelectEvent<T>) => void | Fires after a row is successfully deselected. Provides details about the deselected row. |
| onRowDoubleClick | (event: RecordDoubleClickEvent<T>) => void | Fires when a grid row is clicked. Provides details about the clicked row for custom actions. |
| onRowDrag | (args: RowDragEventArgs<T>) => void | Fires while a data row drag operation is in progress. |
| onRowDragStart | (args: RowDragEventArgs<T>) => void | Fires when a data row drag operation starts. |
| onRowDrop | (args: RowDragEventArgs<T>) => void | Fires when a data row drag operation ends. |
| onRowEditStart | (event: RowEditEvent<T>) => void | Fires when editing begins on a grid record. Allows validation or field modification before editing. |
| onRowSelect | (event: RowSelectEvent<T>) => void | Fires after a row is successfully selected. Provides details about the selected row. |
| onSearch | (event: SearchEvent) => void | Fires after a searching operation completes on the grid. Provides search result details for post-search actions. |
| onSort | (event: SortEvent) => void | Fires after a sorting operation completes on the grid. Provides sort state details for post-sort actions. |
| onToolbarItemClick | (event: ToolbarClickEvent) => void | Fires when a toolbar item is clicked. Enables custom actions for toolbar buttons. |
| onUndoComplete | (event: UndoCompleteEvent) => void | Fires after a Grid-level undo request completes. |
| onUndoStart | (event: UndoStartEvent) => void | Fires before a Grid-level undo request is applied. |
| shouldExpandGroup | (event: ShouldExpandGroupEvent) => boolean | Fires before a group is expanded or collapsed. Allows validation or cancellation of group expand/collapse behavior. |