Tree view

Examples

Check out the Usage section for details about how to design a tree view properly, and the different configuration options we provide.

Basic example

A basic tree view is a TreeView component that wraps one or more TreeNode components. Each tree node can also contain its own nested TreeNode components.

<TreeView>
  <TreeNode
    id="1"
    label="Fruit">
    <TreeNode
      id="2"
      label="Banana"
    />
    <TreeNode
      id="3"
      label="Apple"
    />
  </TreeNode>
  <TreeNode
    id="4"
    label="Vegetables (coming soon!)"
  />
</TreeView>

Nodes prop example

You can use the nodes property to pass the nodes for the tree view as an array of objects. See the tree node properties table for more information about the values that can be passed to this property.

const foods = [
  {
    id: 'fruit',
    label: { id: 'foods.Fruit', defaultMessage: 'Fruit' },
    nodes: [
      {
        id: 'banana',
        label: { id: 'foods.Banana', defaultMessage: 'Banana' },
      },
      {
        id: 'apple',
        label: { id: 'foods.Apple', defaultMessage: 'Apple' },
      },
    ],
  },
  {
    id: 'vegetables',
    label: { id: 'foods.Vegetables', defaultMessage: 'Vegetables (coming soon!)' },
  },
];

<TreeView nodes={foods} />;

Render nodes example

If you want to override something about your nodes when using the nodes props, you can do it with the renderNodes property.

The props object of renderNodes contains the following:

nodeId - the id assigned to the tree node
nodes - the nodes object passed to the tree node

The nodes object contains nested tree nodes, so you need to iterate recursively to render the entire tree.

For example, if you want to apply some styles to each node you can create a custom component that takes the list of nodes and renders them as tree nodes recursively while applying the style to each one.

const foods = [ ... ]

const TomatoNodes = ({ nodes }) => {
  return (
    <>
      {nodes.map(({ id, label, nodes: childNodes }) => (
        <TreeNode
          id={id}
          label={label}
          style={{
            backgroundColor: 'tomato',
            color: 'blue',
            border: '1px solid yellow',
          }}>
          {childNodes && <TomatoNodes nodes={childNodes} />}
        </TreeNode>
      ))}
    </>
  );
};

<TreeView
  nodes={foods}
  renderNodes={TomatoNodes}
/>

Filter example

If you want to include a filter field in your tree view, add the showFilter prop. The field uses a default filtering function, and if you want to override it, use the filterCallback prop.

The filterCallback function takes two arguments:

the translated label of the tree element
the filtering query that the user entered in the filter field

The function needs to return an array of indices that show ranges where the label matches the query, for example [{ start: 2, end: 4 }, { start: 7, end: 9 }].

If the query does not match, the function needs to return null.

The example below matches items only if the label starts with the query (case sensitive).

const foods = [ ... ]

const filterFunction (value, query) => {
    if (value.startsWith(query)) {
      return [{ start: 0, end: query.length }];
    }

    return null;
  }

<TreeView
  showFilter
  nodes={foods}
  filterCallback={filterFunction}
/>

Filter with props example

The filter field is a standard Jutro text input. You can pass additional props using the filterProps property.

const foods = [ ... ]

const filterFunction (value, query) => { ... }

<TreeView
  showFilter
  filterCallback={filterFunction}
  filterProps={{
    placeholder: 'Item starts with...',
  }}
/>

Usage

Coming soon.

Code

<TreeView>
  <TreeNode
    id="1"
    label="Fruit">
    <TreeNode
      id="2"
      label="Banana"
    />
    <TreeNode
      id="3"
      label="Apple"
    />
  </TreeNode>
  <TreeNode
    id="4"
    label="Vegetables (coming soon!)"
  />
</TreeView>

Import statement

import { TreeView, TreeNode, TreeNodeHeader } from '@jutro/components';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

Tree view properties

children: Type
React.ReactNode[]
Description
React nodes to be rendered in a tree view. This is usually tree node components wrapped by the tree view component. Either nodes or children is required.
nodes: Type
TreeNodeData[]
Description
React nodes to be rendered in a tree view. This is usually an array of objects with the same properties as tree node components. Either nodes or children is required.
className: Type
string
Description
CSS class name for this component.
defaultEndIcon: Type
string | Icon
Description
Default icon to be rendered on the last node of the tree. The value is an Icon component or an icon name. For example, CheckIcon or 'gw-check'.
defaultExpandIcon: Type
string | Icon
Description
Default icon to be rendered when a tree node can be expanded. The value is an Icon component or an icon name. For example, CheckIcon or 'gw-check'.
defaultIcon: Type
string | Icon
Description
Default icon component. The value is an Icon component or an icon name. For example, CheckIcon or 'gw-check'.
defaultParentIcon: Type
string | Icon
Description
Default icon to be rendered when node is a parent. The value is an Icon component or an icon name. For example, CheckIcon or 'gw-check'.
defaultRenderChildren: Type
JSXElementConstructor<{ nodeId: string, expanded: boolean, isEndNode: boolean }>
Description
Default children render function.
defaultRenderHeader: Type
JSXElementConstructor<{ nodeId: string, expanded: boolean, isEndNode: boolean }>
Description
Default header render function or component.
filterCallback: Type
(value: string, query: string) => Array<{ start: number, end: number }> | undefined;
Description
Custom comparison function, which takes translated label value as first argument and filtering query as second. It must return null if value is not matched to query, otherwise it returns an array of matching parts indices.
filterProps: Type
object
Description
Properties passed to filter input.
hideCollapseAll: Type
boolean
Description
If set to true, the 'Collapse/Expand all' button will be hidden.
onClick: Type
function (React.MouseEvent<HTMLElement>)
Description
On click event handler.
renderCollapseAll: Type
JSXElementConstructor<{ nodeId: string, expanded: boolean, isEndNode: boolean; }>
Description
Function or component used to render a custom 'Collapse/Expand all' button.
renderFilter: Type
(onChange: TreeViewFilterProps['onChange']) => ReactNode
Description
Custom function for rendering the filter component.
renderNodes: Type
JSXElementConstructor<{ nodeId: string, expanded: boolean, isEndNode: boolean }>
Description
The nodes render function. This is only used when using nodes config.
showFilter: Type
boolean
Description
If set to true, a filter input will be visible.
defaultRenderExpandIcondeprecated: Type
JSXElementConstructor<{ nodeId: string, expanded: boolean, isEndNode: boolean }>
Description
Default expand icon render function or component. Deprecated: since 10.9.0, please use defaultExpandIcon prop instead.
defaultRenderIcondeprecated: Type
JSXElementConstructor<{ nodeId: string, expanded: boolean, isEndNode: boolean }>
Description
Default icon render function or component. Deprecated: since 10.9.0, please use defaultIcon prop instead.

Tree node properties

idrequired: Type
string
Description
Unique identifier for the component.
labelrequired: Type
IntlMessageShape
Description
Text label for the node.
className: Type
string
Description
CSS class name for this component.
disabled: Type
boolean
Description
If set to true, the node is disabled.
expandIcon: Type
JSXElementConstructor<{ 'data-nodeid': string, expanded: boolean, isEndNode: boolean }>
Description
Render function for the expand icon header render function or component.
hideIcon: Type
boolean
Description
If set to true, the icon will be hidden.
icon: Type
string | Icon
Description
An Icon component to render on the component. The value must be an Icon component or the icon's name. For example, CheckIcon or 'gw-check'.
nodeHeaderClassName: Type
string
Description
CSS class name for the node header.
onClick: Type
(args: { id: string, hasNodes: boolean, expanded?: boolean | undefined }) => void
Description
The tree node's handler for click events.
renderChildren: Type
JSXElementConstructor<{ nodeId: string, children: ReactNode, expanded: boolean }>
Description
The tree node's render function or component. Used only when using nodes config.
renderHeader: Type
JSXElementConstructor<TreeNodeHeader>
Description
The tree node's header render function or component. .
renderExpandIcondeprecated: Type
JSXElementConstructor<{ icon?: string | Icon, nodeId: string }>;
Description
The node's expand icon render function or component. Deprecated since 10.9.0, please use the icon prop instead.
renderIcondeprecated: Type
JSXElementConstructor<{ icon?: string | Icon, nodeId: string }>;
Description
The node's header icon render function or component. Will be passed to the renderHeader property. Deprecated since 10.9.0, please use the icon prop instead.

Tree node header properties

idrequired: Type
string
Description
Unique identifier for the component.
labelrequired: Type
string
Description
The header's translated label.
nodeIdrequired: Type
string
Description
The id for the current node.
hideIcon: Type
boolean
Description
If set to true, the icon will be hidden.
icon: Type
string | Icon
Description
An Icon component to render on the component. The value must be an Icon component or the icon's name. For example, CheckIcon or 'gw-check'.
labelMatches: Type
Array<{ start: number, end: number }>
Description
Array of indices to highlight.
renderIcondeprecated: Type
JSXElementConstructor<{ icon?: string | Icon, nodeId: string }>;
Description
The node's header icon render function or component. Will be passed to the renderHeader property. Deprecated since 10.9.0, please use the icon prop instead.

Hooks

No hooks are available for tree view.

Translation keys

There are six translation key associated to the tree view component:

Key	Used for
jutro-components.TreeView.filterLabel	`aria-label` value for the tree view filter.
jutro-components.TreeView.filterPlaceholder	Placeholder text for the tree view filter.
jutro-components.TreeView.collapseAll	Text label for the Collapse all button.
jutro-components.TreeView.expandAll	Text label for the Expand all button.
jutro-components.TreeView.noMatchesFound	Text displayed when filter finds no matches.
jutro-components.TreeView.clearFilter	`aria-label` value for the Clear filter button.

Escape hatches

For more information, see our documentation about escape hatches.

Examples​

Basic example​

Nodes prop example​

Render nodes example​

Filter example​

Filter with props example​

Usage​

Code​

Import statement​

Component contract​

Properties​

Tree view properties​

children​

nodes​

className​

defaultEndIcon​

defaultExpandIcon​

defaultIcon​

defaultParentIcon​

defaultRenderChildren​

defaultRenderHeader​

filterCallback​

filterProps​

hideCollapseAll​

onClick​

renderCollapseAll​

renderFilter​

renderNodes​

showFilter​

defaultRenderExpandIcondeprecated​

defaultRenderIcondeprecated​

Tree node properties​

idrequired​

labelrequired​

className​

disabled​

expandIcon​

hideIcon​

icon​

nodeHeaderClassName​

onClick​

renderChildren​

renderHeader​

renderExpandIcondeprecated​

renderIcondeprecated​

Tree node header properties​

idrequired​

labelrequired​

nodeIdrequired​

hideIcon​

icon​

labelMatches​

renderIcondeprecated​

Hooks​

Translation keys​

Escape hatches​

Changelog​

10.9.0​

icon property types extended​

Deprecations​

Examples

Basic example

Nodes prop example

Render nodes example

Filter example

Filter with props example

Usage

Code

Import statement

Component contract

Properties

Tree view properties

`children`

`nodes`

`className`

`defaultEndIcon`

`defaultExpandIcon`

`defaultIcon`

`defaultParentIcon`

`defaultRenderChildren`

`defaultRenderHeader`

`filterCallback`

`filterProps`

`hideCollapseAll`

`onClick`

`renderCollapseAll`

`renderFilter`

`renderNodes`

`showFilter`

`defaultRenderExpandIcon`deprecated

`defaultRenderIcon`deprecated

Tree node properties

`id`required

`label`required

`className`

`disabled`

`expandIcon`

`hideIcon`

`icon`

`nodeHeaderClassName`

`onClick`

`renderChildren`

`renderHeader`

`renderExpandIcon`deprecated

`renderIcon`deprecated

Tree node header properties

`id`required

`label`required

`nodeId`required

`hideIcon`

`icon`

`labelMatches`

`renderIcon`deprecated

Hooks

Translation keys

Escape hatches

Changelog

10.9.0

icon property types extended

Deprecations