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 hot = new Handsontable(container, {
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
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
// Register all Handsontable's modules.
4
registerAllModules();
5
const sourceDataObject = [
6
    {
7
        category: 'Best Rock Performance',
8
        artist: null,
9
        title: null,
10
        label: null,
11
        __children: [
12
            {
13
                category: 'Major label releases',
14
                artist: null,
15
                title: null,
16
                label: null,
17
                __children: [
18
                    {
19
                        title: "Don't Wanna Fight",
20
                        artist: 'Alabama Shakes',
21
                        label: 'ATO Records',
22
                    },
23
                    {
24
                        title: 'What Kind Of Man',
25
                        artist: 'Florence & The Machine',
26
                        label: 'Republic',
27
                    },
28
                    {
29
                        title: 'Something From Nothing',
30
                        artist: 'Foo Fighters',
31
                        label: 'RCA Records',
32
                    },
33
                ],
34
            },
35
            {
36
                category: 'Independent releases',
37
                artist: null,
38
                title: null,
39
                label: null,
40
                __children: [
41
                    {
42
                        title: 'Moaning Lisa Smile',
43
                        artist: 'Wolf Alice',
44
                        label: 'RCA Records/Dirty Hit',
45
                    },
46
                    {
47
                        title: "Ex's & Oh's",
48
                        artist: 'Elle King',
49
                        label: 'RCA Records',
50
                    },
51
                ],
52
            },
53
        ],
54
    },
55
    {
56
        category: 'Best Metal Performance',
57
        __children: [
58
            {
59
                title: 'Cirice',
60
                artist: 'Ghost',
61
                label: 'Loma Vista Recordings',
62
            },
63
            {
64
                title: 'Identity',
65
                artist: 'August Burns Red',
66
                label: 'Fearless Records',
67
            },
68
            {
69
                title: '512',
70
                artist: 'Lamb Of God',
71
                label: 'Epic Records',
72
            },
73
            {
74
                title: 'Thank You',
75
                artist: 'Sevendust',
76
                label: '7Bros Records',
77
            },
78
            {
79
                title: 'Custer',
80
                artist: 'Slipknot',
81
                label: 'Roadrunner Records',
82
            },
83
        ],
84
    },
85
    {
86
        category: 'Best Rock Song',
87
        __children: [
88
            {
89
                title: "Don't Wanna Fight",
90
                artist: 'Alabama Shakes',
91
                label: 'ATO Records',
92
            },
93
            {
94
                title: "Ex's & Oh's",
95
                artist: 'Elle King',
96
                label: 'RCA Records',
97
            },
98
            {
99
                title: 'Hold Back The River',
100
                artist: 'James Bay',
101
                label: 'Republic',
102
            },
103
            {
104
                title: 'Lydia',
105
                artist: 'Highly Suspect',
106
                label: '300 Entertainment',
107
            },
108
            {
109
                title: 'What Kind Of Man',
110
                artist: 'Florence & The Machine',
111
                label: 'Republic',
112
            },
113
        ],
114
    },
115
    {
116
        category: 'Best Rock Album',
117
        __children: [
118
            {
119
                title: 'Drones',
120
                artist: 'Muse',
121
                label: 'Warner Bros. Records',
122
            },
123
            {
124
                title: 'Chaos And The Calm',
125
                artist: 'James Bay',
126
                label: 'Republic',
127
            },
128
            {
129
                title: 'Kintsugi',
130
                artist: 'Death Cab For Cutie',
131
                label: 'Atlantic',
132
            },
133
            {
134
                title: 'Mister Asylum',
135
                artist: 'Highly Suspect',
136
                label: '300 Entertainment',
137
            },
138
            {
139
                title: '.5: The Gray Chapter',
140
                artist: 'Slipknot',
141
                label: 'Roadrunner Records',
142
            },
143
        ],
144
    },
145
];
146
const container = document.querySelector('#example1');
147
new Handsontable(container, {
148
    data: sourceDataObject,
149
    preventOverflow: 'horizontal',
150
    rowHeaders: true,
151
    colHeaders: ['Category', 'Artist', 'Title', 'Album', 'Label'],
152
    nestedRows: true,
153
    contextMenu: true,
154
    bindRowsWithHeaders: true,
155
    autoWrapRow: true,
156
    autoWrapCol: true,
157
    height: 'auto',
158
    licenseKey: 'non-commercial-and-evaluation',
159
    // Collapse "Best Metal Performance" on load to demonstrate expand/collapse controls.
160
    afterInit() {
161
        this.getPlugin('nestedRows').collapsingUI.collapseChildren(8);
162
    },
163
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
// Register all Handsontable's modules.
5
registerAllModules();
6

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

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

157
const container = document.querySelector('#example1')!;
158

159
new Handsontable(container, {
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
  // Collapse "Best Metal Performance" on load to demonstrate expand/collapse controls.
172
  afterInit() {
173
    this.getPlugin('nestedRows').collapsingUI.collapseChildren(8);
174
  },
175
});

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.