StatefulTree

Overview

The StatefulTree component is used to display a tree of items. Useful for defining a tree of categories or subcollections.

When to use:

  • To display a tree of items
  • Creating or assigning items to a specific category/sub-category
  • To organize items through structure hierarchy

Implementation

  • Category (1)
    • Category (1)
  • Category

Edit the code below to see your changes live!

function Example() {
  const nodes = [
    {
      id: '0',
      value: 0,
      label: 'Category',
      children: [
        {
          id: '5',
          value: 5,
          label: 'Category',
          children: [{ id: '9', value: 9, label: 'Category' }],
        },
      ],
    },
    {
      id: '1',
      value: 1,
      label: 'Category',
      children: [{ id: '6', value: 6, label: 'Category' }],
    },
    { id: '2', value: 2, label: 'Category' },
    {
      id: '3',
      value: 3,
      label: 'Category',
      children: [{ id: '7', value: 7, label: 'Category' }],
    },
    {
      id: '4',
      value: 4,
      label: 'Category',
      children: [{ id: '8', value: 8, label: 'Category' }],
    },
  ];

  return (
    <StatefulTree
      defaultExpanded={['0', '5', '1']}
      defaultSelected={['9', '3', '7']}
      disabledNodes={['1']}
      nodes={nodes}
      selectable="multi"
    />
  );
}

Props

Prop name
Type
Default
Description
defaultExpandedstring[]

An array of expanded node ids. Can also be used to reset expanded nodes.

defaultSelectedstring[]

An array of selected node ids. Can also be used to reset selected nodes.

disabledNodesstring[]

An array of disabled node ids. Nodes will not be abled to be selectedable but can still expand/collapse.

iconlessboolean

Hides/shows all icons on the tree.

idstring

Defines a HTML id attribute to the parent wrapper.

nodes *TreeNode[]

Nodes to render in the tree. See TreeNode for usage.

onExpandedChange(expandedNodes: string[]) => void

Function that will get called when a tree node is expanded/collapsed. Passes the ids of expanded nodes as an argument.

onNodeClick(event: React.MouseEvent<HTMLLIElement>, nodeId: string) => void

Function that will get called when a tree node is clicked.

onSelectionChange(selectedValues: T[]) => void

Function that will get called when a tree node is selected/deselecteds. Passes the values of selected nodes as an argument.

selectablemulti | radio

Determines the type of selectable tree to render.

Props ending with * are required

Do's and Don'ts

Do
Display collapsable side navigation if sub-categories exist.
Use an icon next to categories, regardless of heirarchy.
Use checkboxes when multiple items can be selected vs. radio buttons for either/or.
Selected sub-categories should always be shown numerically next to the parent catergories, both in collapsed or expanded states.
Don't
Make sure radio buttons and checkboxes are used correctly within BigDesign Guidelines. Checkboxes are additive, radio buttons are either/or.
Don’t use to display a list of items.