# Tree data

Trees display parent-child data, such as folders or organizations, with indentation and expansion controls. Unlike grouping equal values, the parent relationship already exists in the data.

Canonical: https://grid.syidax.com/docs/features/tree-data/

<a id="understand"></a>

## How it works and when to use it

Use getDataPath returning a path array, or ID and parent-ID fields. Paths take precedence when both are configured, so choose one rule for each view.

Using this feature in a product requires the Pro package and a valid license. Matching setting names do not enable Pro features in Community.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. Show an organization with path arrays

Put the path from the root to the current item in each row's path array.

```javascript
grid.rowData = [
  { id: 'eng', name: 'Engineering', path: ['Company', 'Engineering'] },
  { id: 'web', name: 'Web', path: ['Company', 'Engineering', 'Web'] },
];
grid.getRowId = row => row.id;
grid.columnDefs = [{ field: 'name', headerName: 'Organization' }];
grid.getDataPath = row => row.path;
```

Verify the result: Web appears beneath Engineering. Changing path labels is different from changing stable row IDs.

<a id="example-2"></a>

## Example 2. Connect through parent IDs

For flat server lists, specify relationship fields instead of converting data into path arrays.

```javascript
grid.getDataPath = undefined;
grid.rowData = [
  { id: 'root', parentId: null, name: 'Head office' },
  { id: 'sales', parentId: 'root', name: 'Sales' },
];
grid.treeIdField = 'id';
grid.treeParentField = 'parentId';
grid.treeLabelField = 'name';
```

Verify the result: id and parentId relationships build the tree. Validate duplicate IDs, cycles, and missing parents before supplying data.

<a id="example-3"></a>

## Example 3. Start with a summary

After applying initial data, collapse all branches and expand only the paths you need.

```javascript
await grid.collapseAllTreeNodes();
// For the path-based example:
await grid.setTreeNodeExpanded(['Company', 'Engineering'], true);
```

Verify the result: Leaf nodes have no children to expand. Confirm that the path exists before calling.

<a id="pitfalls"></a>

## Combining features and troubleshooting

Do not reconstruct server parent IDs from tree display order or indentation. Preserve the source relationships separately.

When switching to a non-tree view, clear getDataPath and relationship fields together so previous hierarchy settings do not remain.

<a id="related-api"></a>

## APIs used by this feature

- [getDataPath](https://grid.syidax.com/docs/options/getDataPath.md) — Builds a tree from a path array from root to the current node. Takes precedence over ID-based tree settings.
- [treeIdField](https://grid.syidax.com/docs/options/treeIdField.md) — Node ID field in a parent-ID tree. Configure together with treeParentField.
- [treeParentField](https://grid.syidax.com/docs/options/treeParentField.md) — Parent node ID field in a parent-ID tree.
- [treeLabelField](https://grid.syidax.com/docs/options/treeLabelField.md) — Display label field in a parent-ID tree. Defaults to the ID when omitted.
- [setTreeNodeExpanded](https://grid.syidax.com/docs/methods/setTreeNodeExpanded.md) — Expands or collapses a tree node by path. Leaf nodes and missing paths cannot be expanded.
- [expandAllTreeNodes](https://grid.syidax.com/docs/methods/expandAllTreeNodes.md) — Expands all expandable nodes in the current tree.
- [collapseAllTreeNodes](https://grid.syidax.com/docs/methods/collapseAllTreeNodes.md) — Collapses all branch nodes in the current tree.
- [reparentRows](https://grid.syidax.com/docs/methods/reparentRows.md) — Reparents tree rows and reports applied/rejected results. Check cycle, permission, and row-model restrictions.
- [treeNodeToggled](https://grid.syidax.com/docs/events/treeNodeToggled.md) — Emitted when tree expansion changes. Inspect the path and expanded state.
- [treeReparented](https://grid.syidax.com/docs/events/treeReparented.md) — Reports tree reparenting results. Connect to parent-relationship saving on your app server.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/tree-data) — The guide describes which interactions are available to try.