Row parent-child
Reflect the parent-child relationship of your data, using the NestedRows plugin’s interactive UI elements such as expand and collapse
buttons or an extended context menu.
Handsontable DataGrid renders this structure as a tree grid. The same pattern is also called a master-detail view or grouping rows.
Quick setup
To enable the NestedRows plugin, set the nestedRows option to true.
const hotSettings = { nestedRows: true,};Note that using all the functionalities provided by the plugin requires enabling the row headers and the Handsontable context menu. To do this set
rowHeaders and contextMenu to true. The collapse / expand buttons are located in the
row headers, and the row modification options add row, insert child, etc., are in the Context Menu.
Prepare the data source
The data source must have a specific structure to be used with the Nested Rows plugin.
The plugin requires the data source to be an array of objects. Each object in the array represents a single 0-level entry. 0-level refers to an entry, which
is not a child of any other entry. If an entry has any child entries, they need to be declared again as an array of objects. To assign them to a row, create a
__children property in the parent element. Child objects can define their own __children arrays, so you can nest rows to any depth. Handsontable does not
impose a fixed nesting limit — the depth is determined by your data structure, and row header indentation grows with each level.
Here’s an example:
<script setup lang="ts">import { ref } from 'vue';import { HotTable } from '@handsontable/vue3';import { registerAllModules } from 'handsontable/registry';import type { GridSettings } from 'handsontable/settings';
registerAllModules();
interface MusicRow { category?: string; artist?: string | null; title?: string | null; label?: string | null; __children?: MusicRow[];}
const sourceDataObject: MusicRow[] = [ { category: 'Best Rock Performance', artist: null, title: null, label: null, __children: [ { category: 'Major label releases', artist: null, title: null, label: null, __children: [ { title: "Don't Wanna Fight", artist: 'Alabama Shakes', label: 'ATO Records', }, { title: 'What Kind Of Man', artist: 'Florence & The Machine', label: 'Republic', }, { title: 'Something From Nothing', artist: 'Foo Fighters', label: 'RCA Records', }, ], }, { category: 'Independent releases', artist: null, title: null, label: null, __children: [ { title: 'Moaning Lisa Smile', artist: 'Wolf Alice', label: 'RCA Records/Dirty Hit', }, { title: "Ex's & Oh's", artist: 'Elle King', label: 'RCA Records', }, ], }, ], }, { category: 'Best Metal Performance', __children: [ { title: 'Cirice', artist: 'Ghost', label: 'Loma Vista Recordings', }, { title: 'Identity', artist: 'August Burns Red', label: 'Fearless Records', }, { title: '512', artist: 'Lamb Of God', label: 'Epic Records', }, { title: 'Thank You', artist: 'Sevendust', label: '7Bros Records', }, { title: 'Custer', artist: 'Slipknot', label: 'Roadrunner Records', }, ], }, { category: 'Best Rock Song', __children: [ { title: "Don't Wanna Fight", artist: 'Alabama Shakes', label: 'ATO Records', }, { title: "Ex's & Oh's", artist: 'Elle King', label: 'RCA Records', }, { title: 'Hold Back The River', artist: 'James Bay', label: 'Republic', }, { title: 'Lydia', artist: 'Highly Suspect', label: '300 Entertainment', }, { title: 'What Kind Of Man', artist: 'Florence & The Machine', label: 'Republic', }, ], }, { category: 'Best Rock Album', __children: [ { title: 'Drones', artist: 'Muse', label: 'Warner Bros. Records', }, { title: 'Chaos And The Calm', artist: 'James Bay', label: 'Republic', }, { title: 'Kintsugi', artist: 'Death Cab For Cutie', label: 'Atlantic', }, { title: 'Mister Asylum', artist: 'Highly Suspect', label: '300 Entertainment', }, { title: '.5: The Gray Chapter', artist: 'Slipknot', label: 'Roadrunner Records', }, ], },];
const hotSettings = ref<GridSettings>({ data: sourceDataObject, preventOverflow: 'horizontal', rowHeaders: true, colHeaders: ['Category', 'Artist', 'Title', 'Album', 'Label'], nestedRows: true, contextMenu: true, bindRowsWithHeaders: true, autoWrapRow: true, autoWrapCol: true, height: 'auto', // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/ afterInit() { this.getPlugin('nestedRows').collapseParent(8); },});</script>
<template> <div id="example1"> <HotTable :settings="hotSettings" /> </div></template>In the example above, we’ve created a data object consisting of 2016’s Grammy nominees of the “Rock” genre. Each 0-level entry declares a category. Under
Best Rock Performance, nominees are grouped into subcategories (Major label releases and Independent releases) at the next level, with individual nominees
nested one level deeper. The other categories use two levels: category and nominee, assigned under the __children properties.
Note that the first 0-level object in the array needs to have all columns defined to display the table properly. They can be declared as null or an empty
string '', but they need to be defined. This is optional for the other objects.
Nested data vs. a flat array
A nested rows data source differs from a regular flat array of objects in one respect: child rows live inside their parent’s __children property, instead of being separate top-level elements. For example, the same three records can be represented either way:
// flat array -- three independent top-level rowsconst flatData = [ { category: 'Best Rock Performance', artist: null }, { category: null, artist: 'Twenty One Pilots' }, { category: null, artist: 'Coldplay' },];
// nested rows -- two nominees grouped under one categoryconst nestedData = [ { category: 'Best Rock Performance', artist: null, __children: [ { category: null, artist: 'Twenty One Pilots' }, { category: null, artist: 'Coldplay' }, ], },];getSourceData() returns this nested structure, __children arrays and all. getData() returns the flattened, currently visible rows — collapsed child rows are excluded. For more on how Handsontable relates source data to what’s displayed, see Understanding data and indexes.
User interface
The Nested Rows plugin’s user interface is placed in the row headers and the Handsontable’s context menu.
Row headers
Each parent row header contains a +/- button. It is used to collapse or expand its child rows.
The child row headers have a bigger indentation, to enable the user to clearly recognize the child and parent elements. In the example above, the
Best Metal Performance category loads collapsed so you can see the expand/collapse controls right away.
Selection
Collapsing or expanding a row changes which rows are visible, not which rows are selected. The selection stays on the rows you selected, and it moves with them:
- A selected range keeps its first and last row. Rows that an expand reveals between them join the range, and rows that a collapse folds away leave it.
- A single selected row stays a single row. When you expand it, its child rows are not added to the selection.
- When you collapse the parent of the focused row while you work in the grid, the selection moves to the nearest visible parent row. When your code collapses it while the grid does not have the focus, the selection is cleared.
The same applies when you undo or redo a collapse or an expand, and when you insert, remove, or detach rows above the selection: the selection stays on the rows you selected. When you remove a selected row, the selection stays at its place. When you move rows, the moved rows are selected.
The afterSelection and afterSelectionEnd hooks run when a collapse or an expand moves the selection. This includes a collapse or an expand that your code makes, for example with collapseAll() or collapseParent(), also while the grid does not have the focus. The grid does not scroll to the moved selection and does not take the focus. When a collapse removes the focused row from view and the selection is cleared, the afterDeselect hook runs.
Context menu
The context menu has been extended with a few Nested Rows related options, such as:
- Insert child row
- Detach from parent
The “Insert row above” and “Insert row below” options were modified to work properly with the nested data structure.
Result
After completing this guide, your grid displays rows in a parent-child hierarchy with collapse and expand toggle buttons in row headers and context menu options for inserting and detaching child rows.
Collapse and expand rows from your code
The NestedRows plugin lets you collapse and expand parent rows from your own code, and tells you
when it happens.
Methods
Get the plugin instance first, from your Handsontable instance:
const plugin = hot.getPlugin('nestedRows');| Method | What it does |
|---|---|
collapseAll() | Collapses every top-level parent |
expandAll() | Expands every parent, at every level |
collapseParent(row) | Collapses one parent |
expandParent(row) | Expands one parent |
toggleParent(row) | Collapses an expanded parent, or expands a collapsed one |
getCollapsedParents() | Physical indexes of the collapsed parents |
isParentCollapsed(row) | Checks one parent |
isParent(row) | Checks whether a row has children |
getRowLevel(row) | How deeply a row is nested. Top-level rows are at level 0 |
getRowParent(row) | The parent of a row |
countChildren(row) | How many children a row has |
expandToRow(row) | Expands every ancestor, to reveal a hidden row |
expandToLevel(level) | Shows rows down to a nesting level, and collapses everything deeper |
The example below calls four of them and prints what each one returns.
<script setup lang="ts">import { ref, useTemplateRef } from 'vue';import { HotTable } from '@handsontable/vue3';import { registerAllModules } from 'handsontable/registry';import type { GridSettings } from 'handsontable/settings';
registerAllModules();
type TaskRow = { task: string; owner: string; status: string; __children?: TaskRow[];};
const projectPlan: TaskRow[] = [ { task: 'Marketing', owner: 'Dana', status: 'In progress', __children: [ { task: 'Website refresh', owner: 'Ivy', status: 'In progress', __children: [ { task: 'Copywriting', owner: 'Leo', status: 'Done' }, { task: 'Visual design', owner: 'Mia', status: 'In review' }, ], }, { task: 'Ad campaign', owner: 'Nico', status: 'Planned' }, ], }, { task: 'Engineering', owner: 'Sam', status: 'In progress', __children: [ { task: 'API v2', owner: 'Ravi', status: 'In progress', __children: [{ task: 'Auth endpoints', owner: 'Tess', status: 'Done' }], }, { task: 'Bug triage', owner: 'Kai', status: 'Planned' }, ], },];
const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');const output = ref('Click a button to call a method.');
// A plain const, so a status change beside the grid never triggers `updateSettings()`.const hotSettings: GridSettings = { data: projectPlan, columns: [{ data: 'task' }, { data: 'owner' }, { data: 'status' }], colHeaders: ['Task', 'Owner', 'Status'], rowHeaders: true, nestedRows: true, contextMenu: true, height: 'auto', // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/};
const getPlugin = () => hotRef.value?.hotInstance?.getPlugin('nestedRows');const countRows = () => hotRef.value?.hotInstance?.countRows();
const collapseAll = () => { getPlugin()?.collapseAll(); output.value = `collapseAll() -> ${countRows()} rows are visible now`;};
const expandAll = () => { getPlugin()?.expandAll(); output.value = `expandAll() -> ${countRows()} rows are visible now`;};
// `toggleParent` takes a visual row index and returns `true` when the state changed.const toggleFirst = () => { const plugin = getPlugin(); const changed = plugin?.toggleParent(0);
output.value = `toggleParent(0) -> ${changed}, collapsed: ${plugin?.isParentCollapsed(0)}`;};
// `getCollapsedParents` returns physical row indexes, because a parent collapsed inside another// collapsed parent has no visual index at all.const readState = () => { const plugin = getPlugin();
output.value = `getCollapsedParents() -> [${plugin?.getCollapsedParents()}]\n` + `getRowLevel(0) -> ${plugin?.getRowLevel(0)}\n` + `countChildren(0) -> ${plugin?.countChildren(0)}`;};</script>
<template> <div id="example2"> <div class="example-controls-container"> <div class="controls"> <button class="button button--primary" @click="collapseAll">collapseAll()</button> <button class="button button--primary" @click="expandAll">expandAll()</button> <button class="button button--primary" @click="toggleFirst">toggleParent(0)</button> <button class="button button--primary" @click="readState">Read the state</button> </div> <output class="console">{{ output }}</output> </div> <HotTable ref="hotRef" :settings="hotSettings" /> </div></template>Which index type to pass
Collapsing a parent trims its children, which removes them from the grid. A trimmed row has no visual index at all, so the plugin uses two index types:
- Methods that act on a row you can see take a visual row index. That covers
collapseParent(),expandParent(),toggleParent(),isParentCollapsed(),isParent(),getRowLevel(),getRowParent(), andcountChildren(). - Methods that address a row the collapse itself hid take or return a physical row index. That
covers
getCollapsedParents()andexpandToRow().
Convert between the two with toVisualRow() and
toPhysicalRow().
Jump to a row inside a collapsed branch
This is where the two index types earn their keep. To reveal a row the user cannot see, you need
expandToRow(), and you have to address that row by its
physical index — a hidden row has no visual index to pass.
The example starts fully collapsed. Each button looks up a task’s physical row, expands whatever ancestors are hiding it, then selects it. Notice how the physical row stays the same while the visual row changes with whatever else is open.
<script setup lang="ts">import { ref, useTemplateRef } from 'vue';import { HotTable } from '@handsontable/vue3';import { registerAllModules } from 'handsontable/registry';import type { GridSettings } from 'handsontable/settings';
registerAllModules();
type TaskRow = { task: string; owner: string; status: string; __children?: TaskRow[];};
const projectPlan: TaskRow[] = [ { task: 'Marketing', owner: 'Dana', status: 'In progress', __children: [ { task: 'Website refresh', owner: 'Ivy', status: 'In progress', __children: [ { task: 'Copywriting', owner: 'Leo', status: 'Done' }, { task: 'Visual design', owner: 'Mia', status: 'In review' }, ], }, { task: 'Ad campaign', owner: 'Nico', status: 'Planned' }, ], }, { task: 'Engineering', owner: 'Sam', status: 'In progress', __children: [ { task: 'API v2', owner: 'Ravi', status: 'In progress', __children: [{ task: 'Auth endpoints', owner: 'Tess', status: 'Done' }], }, { task: 'Bug triage', owner: 'Kai', status: 'Planned' }, ], },];
// Physical row indexes follow the source data, depth first. Walk the tree once to map every task// name to its physical row - that is the index `expandToRow` needs.const physicalRowOf = new Map<string, number>();
let physicalRow = 0;
(function walk(rows: TaskRow[]) { rows.forEach((row) => { physicalRowOf.set(row.task, physicalRow); physicalRow += 1; walk(row.__children ?? []); });})(projectPlan);
const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');const output = ref('Everything starts collapsed. Pick a task to jump to.');
const hotSettings: GridSettings = { data: projectPlan, columns: [{ data: 'task' }, { data: 'owner' }, { data: 'status' }], colHeaders: ['Task', 'Owner', 'Status'], rowHeaders: true, nestedRows: true, height: 'auto', // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/ afterInit() { this.getPlugin('nestedRows').collapseAll(); },};
// Reveals a task that is currently hidden inside collapsed parents, then selects it.const revealTask = (taskName: string) => { const hot = hotRef.value?.hotInstance;
if (!hot) { return; }
const plugin = hot.getPlugin('nestedRows'); const row = physicalRowOf.get(taskName)!; const wasHidden = hot.toVisualRow(row) === null;
// `expandToRow` takes a PHYSICAL index, because a hidden row has no visual index yet. plugin.expandToRow(row);
const visualRow = hot.toVisualRow(row)!;
hot.selectCell(visualRow, 0);
output.value = `"${taskName}" was ${wasHidden ? 'hidden' : 'already visible'}.\n` + `physical row ${row} -> visual row ${visualRow}, nesting level ${plugin.getRowLevel(visualRow)}`;};
const collapseEverything = () => { const hot = hotRef.value?.hotInstance;
hot?.getPlugin('nestedRows').collapseAll(); output.value = `Collapsed again - ${hot?.countRows()} rows are visible.`;};</script>
<template> <div id="example3"> <div class="example-controls-container"> <div class="controls"> <button class="button button--primary" @click="revealTask('Auth endpoints')"> Find "Auth endpoints" </button> <button class="button button--primary" @click="revealTask('Visual design')"> Find "Visual design" </button> <button class="button button--primary" @click="collapseEverything"> Collapse everything </button> </div> <output class="console">{{ output }}</output> </div> <HotTable ref="hotRef" :settings="hotSettings" /> </div></template>Hooks
Four hooks report every collapse and expand, whether it came from the row header button, the Enter shortcut, or one of the methods above:
They carry physical row indexes. Return false from either before hook to block the action:
const configurationOptions = { // Stop the user from collapsing anything. beforeRowCollapse() { return false; },};One case fires no hooks: when updateData() collapses the same parents
again on the new data. That is not a new action, only the state the user already chose, so it stays
silent. If you mirror the collapsed state somewhere, read it back with
getCollapsedParents() after updateData() instead of
counting on a hook.
Save and restore the collapsed rows
The two data methods treat the collapsed rows differently, and the difference decides whether you have to restore anything at all:
updateData()keeps the collapsed parents. It matches them by their position in the tree, so they stay collapsed even when the number of children changes. Do not restore them yourself here. A saved list holds physical row indexes, and those move as soon as a parent gains or loses a child, so replaying it collapses the wrong rows.loadData()drops them, along with every other row state.getCollapsedParents()returns an empty array afterwards. Restore the state yourself if you want it back.
The example below covers the loadData() case. The hooks carry physical indexes, which is what you
want to store. Collapse the deepest parents first: collapsing a parent hides its children, so a
nested parent has to be collapsed while it is still visible.
const plugin = hot.getPlugin('nestedRows');let saved = [];
hot.addHook('afterRowCollapse', (currentCollapsedRows, destinationCollapsedRows) => { saved = destinationCollapsedRows;});
hot.addHook('afterRowExpand', (currentCollapsedRows, destinationCollapsedRows) => { saved = destinationCollapsedRows;});
// Later, after replacing the whole data set:hot.loadData(nextDataSet);
hot.batchExecution(() => { [...saved] .sort((a, b) => (plugin.getRowLevel(hot.toVisualRow(b)) ?? 0) - (plugin.getRowLevel(hot.toVisualRow(a)) ?? 0)) .forEach((physicalRow) => { const visualRow = hot.toVisualRow(physicalRow);
if (visualRow !== null) { plugin.collapseParent(visualRow); } });}, true);Filtering
You can use the Filters plugin together with the NestedRows plugin. Enable both the nestedRows and filters options, and add the dropdownMenu option so users can open the filter menu.
Filtering keeps the tree intact:
- A row that matches the filter is shown together with all its parent rows.
- A parent row that matches the filter is shown together with all its child rows, at every level, whether the children match or not.
- A parent row that matches only because its filtered cells are empty (for example, with (Blank cells) selected) keeps its place in the tree, but not its other child rows.
- Kept parent and child rows look like any other row. Nothing marks them as kept.
The Filter by value list shows the values of every row that the other columns’ filters keep: parents and children at every level, including rows inside collapsed parents.
Because a filter keeps parents and children that don’t match, the list can show a value that belongs only to a kept row. Clearing that value’s checkbox may not hide the row, because the row stays as the parent of a match or as part of a matching parent’s subtree.
Collapsing and expanding rows work while a filter is on. When you collapse all rows, the kept top-level parents stay visible.
For how screen readers count rows in a filtered tree, see Screen readers.
Notes
Known limitations
When you use the parent-child row structure, the following Handsontable features are not supported:
- Data source as an array of arrays
- Rows sorting
- Manual row moving via
moveRows()- usedragRows()instead
When the NestedRows plugin is enabled, the ManualRowMove plugin’s moveRows() method has no effect and logs a console warning. To move rows programmatically, use dragRows() instead.
Subtotals in parent rows
To show a subtotal in a parent row, use the ColumnSummary plugin. Set up the summaries with a function, and give each parent row a summary of its child rows. To make a parent row count the subtotal of a nested group, set the includeSummaryResults option on its summary. For the rules and an example, see Include nested summary results.
Rows added below the last row
When fillHandle.autoInsertRow is enabled, dragging the fill handle
past the last row adds new rows. The new rows continue the level of the last row you can see. If that
row is a child, the new rows are added to the same parent. If it’s a top-level row, or a collapsed
parent at the top level, the new rows are top-level rows.
When you call alter('insert_row_below', index) with the index of the last row,
and that row is not a collapsed parent, the new row is added to the same parent as the last row.
Inserting a row by index below a collapsed parent isn’t supported: expand the parent first. A call
without an index, a row added by minSpareRows, and a paste or an edit
past the last row still add top-level rows.
Row header width with custom labels
The NestedRows plugin sizes the row header column from the depth of your data, not from the text in
the headers. It then spends part of that width on the indentation and on the collapse or expand
button. If you pass your own labels through rowHeaders, they can be
cut off, and the indentation that separates parents from children gets squeezed.
You have two ways to give the labels room:
- Set
rowHeaderWidthto a fixed number of pixels. The plugin treats the width it computes as a minimum, so a larger value of your own wins. - Enable the
AutoRowHeaderSizeplugin by settingautoRowHeaderSizetotrue. It measures the headers as they are rendered, so the indentation and the button are counted, and it sizes the column to the longest label.
Accessibility
The NestedRows plugin follows the WAI-ARIA treegrid pattern: rows tell assistive technologies where they sit in the tree, and keyboard users can collapse or expand parent rows from a focused row header. To let keyboard users reach the row headers, enable navigableHeaders. As in the pattern’s cell-only focus mode, the arrow keys keep moving the selection, and Enter toggles the row.
Screen readers
With ariaTags (the default) and rowHeaders enabled, each row element (role="row") gets:
aria-level: the row’s depth in the tree. A top-level row has level 1.aria-posinsetandaria-setsize: the row’s position among its siblings, and the number of siblings.
The row header of a parent row gets aria-expanded, set to true or false. Rows without children don’t get this attribute.
The attributes update when you collapse or expand a row and when you load new data. They are removed when you disable the plugin or switch off rowHeaders. Not every screen reader reads them: VoiceOver on macOS announces the expanded state but not the level or the position.
The position and the number of siblings come from your data. Rows that the HiddenRows plugin hides still count. Rows that a filter or the TrimRows plugin removes don’t, so the numbers describe the rows you can reach.
When you collapse or expand a row with the keyboard or with the row header button, Handsontable announces the change through a polite live region: for example, “Expanded row 1, expanded rows shown: 5” or “Collapsed row 1”. The row is named after the text its row header shows, the same label sighted users see next to the row, or after its row number when the header is empty. Changes made through the API methods are not announced, so your application can describe them in its own words. With ariaTags set to false, nothing is announced.
When the selection moves to another row, Handsontable also announces the row’s level and position, for example “Level 2, 1 of 3”. A parent row adds ”, expanded” or ”, collapsed”.
The announcement text is translated. To change it, override the NestedRows:announcement.expanded, NestedRows:announcement.collapsed, NestedRows:announcement.level, NestedRows:announcement.level.expanded, and NestedRows:announcement.level.collapsed keys in your language dictionary.
Keyboard shortcuts
The Shift+Alt+→ and Shift+Alt+← shortcuts work from any data cell of the row or from its row header, with or without navigableHeaders. The other shortcuts work only when a row header is focused. Enable navigableHeaders: true to move focus onto headers with the arrow keys. For more details, see Keyboard navigation.
| Windows | macOS | Action |
|---|---|---|
| Enter | Enter | Collapse or expand the row group |
| Ctrl+→ | ⌘+→ | Expand a collapsed parent row |
| Ctrl+← | ⌘+← | Collapse an expanded parent row. Otherwise, move the focus to the header of the parent row, if any |
| Shift+Alt+→ | ⇧+⌥+→ | Expand the current row, if it is a collapsed parent row |
| Shift+Alt+← | ⇧+⌥+← | Collapse the current row, if it is an expanded parent row. Otherwise, move the selection to the parent row, in the same column |
In a right-to-left layout (layoutDirection: 'rtl'), the ← and → keys swap their actions, including with Shift+Alt. The arrow keys without a modifier move the selection, as they do in every grid. On a row header, Ctrl/⌘+← and → don’t jump to the first or last cell of the row. To move along the row from a row header, use → or End.
Related articles
Related guides
Configuration options
Core methods
Plugin methods
Hooks
Plugins