NestedHeaders

Options

nestedHeaders

Ask AI

Source code

nestedHeaders.nestedHeaders : boolean | Array<Array>

The nestedHeaders option configures the NestedHeaders plugin.

You can set the nestedHeaders option to one of the following:

Setting	Description
false (default)	Disable the NestedHeaders plugin
true	- Enable the NestedHeaders plugin - Don’t configure any nested headers
Array of arrays	- Enable the NestedHeaders plugin - Configure headers that are nested on Handsontable’s initialization

If you set the nestedHeaders option to an array of arrays, each array configures one row of nested headers (top row first). Within a row, headers are listed left to right.

Each array element configures one header, and can be one of the following:

Array element	Description
A string	The header’s label
An object	A header configuration object (see the properties below)

A header configuration object accepts the following properties:

Property	Type	Description
label	string	The header’s label.
colspan	number	The number of data columns the header spans (an integer greater than 1). Groups the columns it covers.
rowspan	number	The number of header rows the header spans (an integer greater than 1).
headerClassName	string	One or more space-separated CSS class names added to the header element (for example, 'htRight').
visibleWhen	string	For a header inside a collapsible group, sets in which collapse state the header (and its columns) stays visible: 'collapsed' (visible only while the group is collapsed), 'expanded' (visible only while the group is expanded), or 'always' (visible in both states). When omitted, a header in such a group defaults to 'expanded' - it is hidden when the group collapses. At least one column of a group always stays visible.
columnDropMode	string	Controls what a group does when a column move (with the ManualColumnMove plugin) drops a foreign column (one belonging to another group) into its span. With 'adopt' (default), the group adopts that column as a child and stays one banner. With 'split', the group keeps its identity and renders as several same-label banners around the foreign column (it splits). A group always reclaims its own columns when they move back into its span, regardless of this setting. Meaningful only on a header that spans columns.

Tip

A header group is made collapsible through the collapsibleColumns option, not through nestedHeaders. Once a group is collapsible, mark the column(s) you want to keep visible when it collapses with visibleWhen: 'always' (or 'collapsed'); the remaining columns are hidden on collapse by default.

Tip

When nestedHeaders is configured, the label defined in the columns option for the same column is replaced by the label from nestedHeaders. The nestedHeaders label takes precedence.

Read more:

• Column groups: Nested headers
• Column groups: Choose which columns stay visible when collapsed

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// group headers with `label` and `colspan`
nestedHeaders: [
  ['A', {label: 'B', colspan: 8}, 'C'],
  ['D', {label: 'E', colspan: 4}, {label: 'F', colspan: 4}, 'G'],
  ['H', 'I', 'J', 'K', 'L', 'M', 'N', 'R', 'S', 'T']
],

// choose which columns stay visible when a collapsible group is collapsed:
// unmarked headers (Jan, Feb, Mar) are hidden on collapse; `Total` appears only when collapsed
nestedHeaders: [
  ['Region', {label: 'Q1 2025', colspan: 4}],
  ['Region', 'Jan', 'Feb', 'Mar', {label: 'Total', visibleWhen: 'collapsed'}]
],
collapsibleColumns: true,

Members

detectedOverlappedHeaders

Ask AI

Source code

nestedHeaders.detectedOverlappedHeaders

The flag which determines that the nested header settings contains overlapping headers configuration.

ghostTable

Ask AI

Source code

nestedHeaders.ghostTable

Custom helper for getting widths of the nested headers.

PLUGIN_KEY

Ask AI

Source code

NestedHeaders.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Ask AI

Source code

NestedHeaders.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

Methods

_getHeaderTreeNodeDataByCoords

Ask AI

Source code

nestedHeaders._getHeaderTreeNodeDataByCoords()

Returns the header tree node data for the given coordinates, or undefined if the coordinates do not point to a header cell.

clearColspans

Ask AI

Source code

nestedHeaders.clearColspans()

Removes all colspan and rowspan attributes from the rendered header cells in all overlays.

destroy

Ask AI

Source code

nestedHeaders.destroy()

Destroys the plugin instance.

disablePlugin

Ask AI

Source code

nestedHeaders.disablePlugin()

Disables the plugin by removing all registered hooks, clearing header state, and resetting visual indicators.

enablePlugin

Ask AI

Source code

nestedHeaders.enablePlugin()

Enables the plugin by registering all required hooks and initializing the header state.

getColumnHeaderValue

Ask AI

Source code

nestedHeaders.getColumnHeaderValue()

Returns the display value for a nested header cell at the given visual column index and header level.

getHeaderSettings

Ask AI

Source code

nestedHeaders.getHeaderSettings()

Returns the header settings node for the specified header level and column index.

getLayersCount

Ask AI

Source code

nestedHeaders.getLayersCount()

Returns the number of nested header rows currently configured in the plugin.

getStateManager

Ask AI

Source code

nestedHeaders.getStateManager()

Returns the internal state manager that tracks the nested header spans and their layout configuration.

headerRendererFactory

Ask AI

Source code

nestedHeaders.headerRendererFactory()

Creates and returns a header renderer function for the specified header layer level.

isEnabled

Ask AI

Source code

nestedHeaders.isEnabled()

Returns whether the plugin is enabled based on the presence of the nestedHeaders settings key.

updatePlugin

Ask AI

Source code

nestedHeaders.updatePlugin()

Updates the plugin state when Handsontable settings change, rebuilding the header tree and refreshing column widths.