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
<HotTable 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:

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3

4
// register Handsontable's modules
5
registerAllModules();
6

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

149
const ExampleComponent = () => {
150
  return (
151
    <HotTable
152
      data={sourceDataObject}
153
      preventOverflow="horizontal"
154
      rowHeaders={true}
155
      colHeaders={['Category', 'Artist', 'Title', 'Album', 'Label']}
156
      nestedRows={true}
157
      contextMenu={true}
158
      bindRowsWithHeaders={true}
159
      autoWrapRow={true}
160
      autoWrapCol={true}
161
      height="auto"
162
      licenseKey="non-commercial-and-evaluation"
163
      afterInit={function () {
164
        this.getPlugin('nestedRows').collapsingUI.collapseChildren(8);
165
      }}
166
    />
167
  );
168
};
169

170
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import type Handsontable from 'handsontable/base';
4

5
// register Handsontable's modules
6
registerAllModules();
7

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

150
const ExampleComponent = () => {
151
  return (
152
    <HotTable
153
      data={sourceDataObject}
154
      preventOverflow="horizontal"
155
      rowHeaders={true}
156
      colHeaders={['Category', 'Artist', 'Title', 'Album', 'Label']}
157
      nestedRows={true}
158
      contextMenu={true}
159
      bindRowsWithHeaders={true}
160
      autoWrapRow={true}
161
      autoWrapCol={true}
162
      height="auto"
163
      licenseKey="non-commercial-and-evaluation"
164
      afterInit={function (this: Handsontable) {
165
        this.getPlugin('nestedRows').collapsingUI.collapseChildren(8);
166
      }}
167
    />
168
  );
169
};
170

171
export default ExampleComponent;

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.

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.