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 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.

1
const hotSettings = {
2
  nestedRows: true,
3
};

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:

1
<script setup lang="ts">
2
import { ref } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
registerAllModules();
8

9
interface MusicRow {
10
  category?: string;
11
  artist?: string | null;
12
  title?: string | null;
13
  label?: string | null;
14
  __children?: MusicRow[];
15
}
16

17
const sourceDataObject: MusicRow[] = [
18
  {
19
    category: 'Best Rock Performance',
20
    artist: null,
21
    title: null,
22
    label: null,
23
    __children: [
24
      {
25
        category: 'Major label releases',
26
        artist: null,
27
        title: null,
28
        label: null,
29
        __children: [
30
          {
31
            title: "Don't Wanna Fight",
32
            artist: 'Alabama Shakes',
33
            label: 'ATO Records',
34
          },
35
          {
36
            title: 'What Kind Of Man',
37
            artist: 'Florence & The Machine',
38
            label: 'Republic',
39
          },
40
          {
41
            title: 'Something From Nothing',
42
            artist: 'Foo Fighters',
43
            label: 'RCA Records',
44
          },
45
        ],
46
      },
47
      {
48
        category: 'Independent releases',
49
        artist: null,
50
        title: null,
51
        label: null,
52
        __children: [
53
          {
54
            title: 'Moaning Lisa Smile',
55
            artist: 'Wolf Alice',
56
            label: 'RCA Records/Dirty Hit',
57
          },
58
          {
59
            title: "Ex's & Oh's",
60
            artist: 'Elle King',
61
            label: 'RCA Records',
62
          },
63
        ],
64
      },
65
    ],
66
  },
67
  {
68
    category: 'Best Metal Performance',
69
    __children: [
70
      {
71
        title: 'Cirice',
72
        artist: 'Ghost',
73
        label: 'Loma Vista Recordings',
74
      },
75
      {
76
        title: 'Identity',
77
        artist: 'August Burns Red',
78
        label: 'Fearless Records',
79
      },
80
      {
81
        title: '512',
82
        artist: 'Lamb Of God',
83
        label: 'Epic Records',
84
      },
85
      {
86
        title: 'Thank You',
87
        artist: 'Sevendust',
88
        label: '7Bros Records',
89
      },
90
      {
91
        title: 'Custer',
92
        artist: 'Slipknot',
93
        label: 'Roadrunner Records',
94
      },
95
    ],
96
  },
97
  {
98
    category: 'Best Rock Song',
99
    __children: [
100
      {
101
        title: "Don't Wanna Fight",
102
        artist: 'Alabama Shakes',
103
        label: 'ATO Records',
104
      },
105
      {
106
        title: "Ex's & Oh's",
107
        artist: 'Elle King',
108
        label: 'RCA Records',
109
      },
110
      {
111
        title: 'Hold Back The River',
112
        artist: 'James Bay',
113
        label: 'Republic',
114
      },
115
      {
116
        title: 'Lydia',
117
        artist: 'Highly Suspect',
118
        label: '300 Entertainment',
119
      },
120
      {
121
        title: 'What Kind Of Man',
122
        artist: 'Florence & The Machine',
123
        label: 'Republic',
124
      },
125
    ],
126
  },
127
  {
128
    category: 'Best Rock Album',
129
    __children: [
130
      {
131
        title: 'Drones',
132
        artist: 'Muse',
133
        label: 'Warner Bros. Records',
134
      },
135
      {
136
        title: 'Chaos And The Calm',
137
        artist: 'James Bay',
138
        label: 'Republic',
139
      },
140
      {
141
        title: 'Kintsugi',
142
        artist: 'Death Cab For Cutie',
143
        label: 'Atlantic',
144
      },
145
      {
146
        title: 'Mister Asylum',
147
        artist: 'Highly Suspect',
148
        label: '300 Entertainment',
149
      },
150
      {
151
        title: '.5: The Gray Chapter',
152
        artist: 'Slipknot',
153
        label: 'Roadrunner Records',
154
      },
155
    ],
156
  },
157
];
158

159
const hotSettings = ref<GridSettings>({
160
  data: sourceDataObject,
161
  preventOverflow: 'horizontal',
162
  rowHeaders: true,
163
  colHeaders: ['Category', 'Artist', 'Title', 'Album', 'Label'],
164
  nestedRows: true,
165
  contextMenu: true,
166
  bindRowsWithHeaders: true,
167
  autoWrapRow: true,
168
  autoWrapCol: true,
169
  height: 'auto',
170
  licenseKey: 'non-commercial-and-evaluation',
171
  afterInit() {
172
    this.getPlugin('nestedRows').collapseParent(8);
173
  },
174
});
175
</script>
176

177
<template>
178
  <div id="example1">
179
    <HotTable :settings="hotSettings" />
180
  </div>
181
</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:

1
// flat array -- three independent top-level rows
2
const flatData = [
3
  { category: 'Best Rock Performance', artist: null },
4
  { category: null, artist: 'Twenty One Pilots' },
5
  { category: null, artist: 'Coldplay' },
6
];
7

8
// nested rows -- two nominees grouped under one category
9
const nestedData = [
10
  {
11
    category: 'Best Rock Performance',
12
    artist: null,
13
    __children: [
14
      { category: null, artist: 'Twenty One Pilots' },
15
      { category: null, artist: 'Coldplay' },
16
    ],
17
  },
18
];

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.

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:

1
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.

1
<script setup lang="ts">
2
import { ref, useTemplateRef } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
registerAllModules();
8

9
type TaskRow = {
10
  task: string;
11
  owner: string;
12
  status: string;
13
  __children?: TaskRow[];
14
};
15

16
const projectPlan: TaskRow[] = [
17
  {
18
    task: 'Marketing',
19
    owner: 'Dana',
20
    status: 'In progress',
21
    __children: [
22
      {
23
        task: 'Website refresh',
24
        owner: 'Ivy',
25
        status: 'In progress',
26
        __children: [
27
          { task: 'Copywriting', owner: 'Leo', status: 'Done' },
28
          { task: 'Visual design', owner: 'Mia', status: 'In review' },
29
        ],
30
      },
31
      { task: 'Ad campaign', owner: 'Nico', status: 'Planned' },
32
    ],
33
  },
34
  {
35
    task: 'Engineering',
36
    owner: 'Sam',
37
    status: 'In progress',
38
    __children: [
39
      {
40
        task: 'API v2',
41
        owner: 'Ravi',
42
        status: 'In progress',
43
        __children: [{ task: 'Auth endpoints', owner: 'Tess', status: 'Done' }],
44
      },
45
      { task: 'Bug triage', owner: 'Kai', status: 'Planned' },
46
    ],
47
  },
48
];
49

50
const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');
51
const output = ref('Click a button to call a method.');
52

53
// A plain const, so a status change beside the grid never triggers `updateSettings()`.
54
const hotSettings: GridSettings = {
55
  data: projectPlan,
56
  columns: [{ data: 'task' }, { data: 'owner' }, { data: 'status' }],
57
  colHeaders: ['Task', 'Owner', 'Status'],
58
  rowHeaders: true,
59
  nestedRows: true,
60
  contextMenu: true,
61
  height: 'auto',
62
  licenseKey: 'non-commercial-and-evaluation',
63
};
64

65
const getPlugin = () => hotRef.value?.hotInstance?.getPlugin('nestedRows');
66
const countRows = () => hotRef.value?.hotInstance?.countRows();
67

68
const collapseAll = () => {
69
  getPlugin()?.collapseAll();
70
  output.value = `collapseAll() -> ${countRows()} rows are visible now`;
71
};
72

73
const expandAll = () => {
74
  getPlugin()?.expandAll();
75
  output.value = `expandAll() -> ${countRows()} rows are visible now`;
76
};
77

78
// `toggleParent` takes a visual row index and returns `true` when the state changed.
79
const toggleFirst = () => {
80
  const plugin = getPlugin();
81
  const changed = plugin?.toggleParent(0);
82

83
  output.value = `toggleParent(0) -> ${changed}, collapsed: ${plugin?.isParentCollapsed(0)}`;
84
};
85

86
// `getCollapsedParents` returns physical row indexes, because a parent collapsed inside another
87
// collapsed parent has no visual index at all.
88
const readState = () => {
89
  const plugin = getPlugin();
90

91
  output.value =
92
    `getCollapsedParents() -> [${plugin?.getCollapsedParents()}]\n` +
93
    `getRowLevel(0) -> ${plugin?.getRowLevel(0)}\n` +
94
    `countChildren(0) -> ${plugin?.countChildren(0)}`;
95
};
96
</script>
97

98
<template>
99
  <div id="example2">
100
    <div class="example-controls-container">
101
      <div class="controls">
102
        <button class="button button--primary" @click="collapseAll">collapseAll()</button>
103
        <button class="button button--primary" @click="expandAll">expandAll()</button>
104
        <button class="button button--primary" @click="toggleFirst">toggleParent(0)</button>
105
        <button class="button button--primary" @click="readState">Read the state</button>
106
      </div>
107
      <output class="console">{{ output }}</output>
108
    </div>
109
    <HotTable ref="hotRef" :settings="hotSettings" />
110
  </div>
111
</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(), and countChildren().
Methods that address a row the collapse itself hid take or return a physical row index. That covers getCollapsedParents() and expandToRow().

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.

1
<script setup lang="ts">
2
import { ref, useTemplateRef } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
registerAllModules();
8

9
type TaskRow = {
10
  task: string;
11
  owner: string;
12
  status: string;
13
  __children?: TaskRow[];
14
};
15

16
const projectPlan: TaskRow[] = [
17
  {
18
    task: 'Marketing',
19
    owner: 'Dana',
20
    status: 'In progress',
21
    __children: [
22
      {
23
        task: 'Website refresh',
24
        owner: 'Ivy',
25
        status: 'In progress',
26
        __children: [
27
          { task: 'Copywriting', owner: 'Leo', status: 'Done' },
28
          { task: 'Visual design', owner: 'Mia', status: 'In review' },
29
        ],
30
      },
31
      { task: 'Ad campaign', owner: 'Nico', status: 'Planned' },
32
    ],
33
  },
34
  {
35
    task: 'Engineering',
36
    owner: 'Sam',
37
    status: 'In progress',
38
    __children: [
39
      {
40
        task: 'API v2',
41
        owner: 'Ravi',
42
        status: 'In progress',
43
        __children: [{ task: 'Auth endpoints', owner: 'Tess', status: 'Done' }],
44
      },
45
      { task: 'Bug triage', owner: 'Kai', status: 'Planned' },
46
    ],
47
  },
48
];
49

50
// Physical row indexes follow the source data, depth first. Walk the tree once to map every task
51
// name to its physical row - that is the index `expandToRow` needs.
52
const physicalRowOf = new Map<string, number>();
53

54
let physicalRow = 0;
55

56
(function walk(rows: TaskRow[]) {
57
  rows.forEach((row) => {
58
    physicalRowOf.set(row.task, physicalRow);
59
    physicalRow += 1;
60
    walk(row.__children ?? []);
61
  });
62
})(projectPlan);
63

64
const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');
65
const output = ref('Everything starts collapsed. Pick a task to jump to.');
66

67
const hotSettings: GridSettings = {
68
  data: projectPlan,
69
  columns: [{ data: 'task' }, { data: 'owner' }, { data: 'status' }],
70
  colHeaders: ['Task', 'Owner', 'Status'],
71
  rowHeaders: true,
72
  nestedRows: true,
73
  height: 'auto',
74
  licenseKey: 'non-commercial-and-evaluation',
75
  afterInit() {
76
    this.getPlugin('nestedRows').collapseAll();
77
  },
78
};
79

80
// Reveals a task that is currently hidden inside collapsed parents, then selects it.
81
const revealTask = (taskName: string) => {
82
  const hot = hotRef.value?.hotInstance;
83

84
  if (!hot) {
85
    return;
86
  }
87

88
  const plugin = hot.getPlugin('nestedRows');
89
  const row = physicalRowOf.get(taskName)!;
90
  const wasHidden = hot.toVisualRow(row) === null;
91

92
  // `expandToRow` takes a PHYSICAL index, because a hidden row has no visual index yet.
93
  plugin.expandToRow(row);
94

95
  const visualRow = hot.toVisualRow(row)!;
96

97
  hot.selectCell(visualRow, 0);
98

99
  output.value =
100
    `"${taskName}" was ${wasHidden ? 'hidden' : 'already visible'}.\n` +
101
    `physical row ${row} -> visual row ${visualRow}, nesting level ${plugin.getRowLevel(visualRow)}`;
102
};
103

104
const collapseEverything = () => {
105
  const hot = hotRef.value?.hotInstance;
106

107
  hot?.getPlugin('nestedRows').collapseAll();
108
  output.value = `Collapsed again - ${hot?.countRows()} rows are visible.`;
109
};
110
</script>
111

112
<template>
113
  <div id="example3">
114
    <div class="example-controls-container">
115
      <div class="controls">
116
        <button class="button button--primary" @click="revealTask('Auth endpoints')">
117
          Find "Auth endpoints"
118
        </button>
119
        <button class="button button--primary" @click="revealTask('Visual design')">
120
          Find "Visual design"
121
        </button>
122
        <button class="button button--primary" @click="collapseEverything">
123
          Collapse everything
124
        </button>
125
      </div>
126
      <output class="console">{{ output }}</output>
127
    </div>
128
    <HotTable ref="hotRef" :settings="hotSettings" />
129
  </div>
130
</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:

1
const configurationOptions = {
2
  // Stop the user from collapsing anything.
3
  beforeRowCollapse() {
4
    return false;
5
  },
6
};

Save and restore the collapsed rows

The hooks carry physical indexes, which is what you want to store. To restore the state after replacing the data, collapse the deepest parents first: collapsing a parent hides its children, so a nested parent has to be collapsed while it is still visible.

1
const plugin = hot.getPlugin('nestedRows');
2
let saved = [];
3

4
hot.addHook('afterRowCollapse', (currentCollapsedRows, destinationCollapsedRows) => {
5
  saved = destinationCollapsedRows;
6
});
7

8
hot.addHook('afterRowExpand', (currentCollapsedRows, destinationCollapsedRows) => {
9
  saved = destinationCollapsedRows;
10
});
11

12
// Later, after replacing the whole data set:
13
hot.loadData(nextDataSet);
14

15
hot.batchExecution(() => {
16
  [...saved]
17
    .sort((a, b) => (plugin.getRowLevel(hot.toVisualRow(b)) ?? 0) - (plugin.getRowLevel(hot.toVisualRow(a)) ?? 0))
18
    .forEach((physicalRow) => {
19
      const visualRow = hot.toVisualRow(physicalRow);
20

21
      if (visualRow !== null) {
22
        plugin.collapseParent(visualRow);
23
      }
24
    });
25
}, true);

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
Column filter
Rows sorting
Manual row moving via moveRows() - use dragRows() 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.

Keyboard shortcuts

This header-focused shortcut works 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.