TreeView API - React Magma

TreeView provides a hierarchical list of items that can be collapsed or expanded to hide or reveal their contents.

Basic Usage

import React from 'react';
import { TreeView, TreeItem, Heading } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <Heading level={3} id="ah-textbook">
        Gardner's Art through the ages
      </Heading>
      <TreeView ariaLabelledBy={'ah-textbook'}>
        <TreeItem
          label={<>I. INTRODUCTION: WHAT IS ART HISTORY?</>}
          itemId="I-intro"
        >
          <TreeItem
            label={<>Art History in the 21st Century</>}
            itemId="I-21st-century"
          >
            <TreeItem
              label={<>The Questions Art Historians Ask</>}
              itemId="I-questions"
            />
            <TreeItem
              label={<>The Words Art Historians Use</>}
              itemId="I-words"
            >
              <TreeItem label={<>Vocabulary</>} itemId="I-vocab" />
            </TreeItem>
            <TreeItem
              label={<>Art History and Other Disciplines</>}
              itemId="I-other"
            />
          </TreeItem>
          <TreeItem
            label={<>Different Ways of Seeing</>}
            itemId="I-different-ways"
          />
        </TreeItem>
        <TreeItem label={<>1. ART IN THE STONE AGE</>} itemId="1-stone-age">
          <TreeItem label={<>Paleolithic Art</>} itemId="1-paleolithic">
            <TreeItem label={<>Africa</>} itemId="1-africa" />
            <TreeItem label={<>Europe</>} itemId="1-europe" />
          </TreeItem>
          <TreeItem label={<>Neolithic Art</>} itemId="1-neolithic">
            <TreeItem
              label={<>Anatolia and Mesopotamia</>}
              itemId="1-anatolia"
            />
            <TreeItem
              label={<>Europe</>}
              itemId="1-neolithic-europe"
              isDisabled
            />
          </TreeItem>
        </TreeItem>
        <TreeItem
          label={<>2. ANCIENT MESOPOTAMIA AND PERSIA</>}
          itemId="2-ancient"
        >
          <TreeItem label={<>Mesopotamia</>} itemId="2-mesopotamia">
            <TreeItem label={<>Sumer</>} itemId="2-sumer" />
            <TreeItem label={<>Akkad</>} itemId="2-akkad" />
            <TreeItem label={<>Third Dynasty of Ur</>} itemId="2-ur" />
            <TreeItem label={<>Babylon</>} itemId="2-babylon" />
            <TreeItem label={<>Elam</>} itemId="2-elam" />
            <TreeItem label={<>Assyria</>} itemId="2-assyria" />
            <TreeItem label={<>Neo-Babylonia</>} itemId="2-neo" />
          </TreeItem>
          <TreeItem label={<>Persia</>} itemId="2-persia">
            <TreeItem label={<>Achaemenid Empire</>} itemId="2-achaemenid" />
            <TreeItem label={<>Sasanian Empire</>} itemId="2-sasanian" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </>
  );
}

Selectable

TreeViews can have TreeViewSelectable.single for single select (default), TreeViewSelectable.multi for multi select with checkboxes, or TreeViewSelectable.off for no selection.

import React from 'react';
import {
  TreeView,
  TreeItem,
  TreeViewSelectable,
  Tag,
  Heading,
  IndeterminateCheckboxStatus,
  TagSize,
  TagColor,
} from 'react-magma-dom';

export function Example() {
  const [selectedItems, setSelectedItems] = React.useState(null);
  const [indeterminateItems, setIndeterminateItems] = React.useState(null);

  function onSelection(items) {
    const selected = items
      .filter(i => i.checkedStatus === IndeterminateCheckboxStatus.checked)
      .map((i, key) => (
        <Tag key={key} size={TagSize.small} color={TagColor.primary}>
          {i.itemId}
        </Tag>
      ));

    const indeterminate = items
      .filter(
        i => i.checkedStatus === IndeterminateCheckboxStatus.indeterminate
      )
      .map((i, key) => (
        <Tag key={key} size={TagSize.small} color={TagColor.default}>
          {i.itemId}
        </Tag>
      ));

    setSelectedItems(selected);
    setIndeterminateItems(indeterminate);
  }

  return (
    <>
      <Heading level={3} id="animals-off">
        TreeViewSelectable.off
      </Heading>
      <TreeView
        ariaLabelledBy="animals-off"
        selectable={TreeViewSelectable.off}
      >
        <TreeItem label="Mammals" itemId="selectable-Mammals">
          <TreeItem label="Dogs" itemId="selectable-Dogs">
            <TreeItem
              label="German Shepherd"
              itemId="selectable-German Shepherd"
            />
            <TreeItem
              label="Labrador Retriever"
              itemId="selectable-Labrador Retriever"
            />
            <TreeItem
              label="American Bully"
              itemId="selectable-American Bully"
            />
          </TreeItem>
          <TreeItem label="Cats" itemId="selectable-Cats">
            <TreeItem label="Siamese" itemId="selectable-Siamese" />
            <TreeItem label="Persian" itemId="selectable-Persian" />
            <TreeItem label="Bengal" itemId="selectable-Bengal" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Reptiles" itemId="selectable-Reptiles">
          <TreeItem label="Snakes" itemId="selectable-Snakes">
            <TreeItem label="Python" itemId="selectable-Python" />
            <TreeItem
              label="Boa Constrictor"
              itemId="selectable-Boa Constrictor"
            />
            <TreeItem label="Corn Snake" itemId="selectable-Corn Snake" />
          </TreeItem>
          <TreeItem label="Lizards" itemId="selectable-Lizards">
            <TreeItem label="Geckos" itemId="selectable-Geckos" />
            <TreeItem label="Iguanas" itemId="selectable-Iguanas" />
            <TreeItem label="Chameleons" itemId="selectable-Chameleons" />
          </TreeItem>
        </TreeItem>
      </TreeView>
      <Heading level={3} id="animals-multi">
        TreeViewSelectable.multi
      </Heading>
      <TreeView
        ariaLabelledBy="animals-multi"
        selectable={TreeViewSelectable.multi}
        onSelectedItemChange={onSelection}
      >
        <TreeItem label="Birds" itemId="selectable-Birds">
          <TreeItem label="Parrots" itemId="selectable-Parrots">
            <TreeItem label="African Grey" itemId="selectable-African Grey" />
            <TreeItem label="Cockatiel" itemId="selectable-Cockatiel" />
            <TreeItem label="Budgerigar" itemId="selectable-Budgerigar" />
          </TreeItem>
          <TreeItem label="Birds of Prey" itemId="selectable-Birds of Prey">
            <TreeItem label="Eagles" itemId="selectable-Eagles" />
            <TreeItem label="Hawks" itemId="selectable-Hawks" />
            <TreeItem label="Falcons" itemId="selectable-Falcons" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Aquatic Animals" itemId="selectable-Aquatic Animals">
          <TreeItem label="Fish" itemId="selectable-Fish">
            <TreeItem label="Goldfish" itemId="selectable-Goldfish" />
            <TreeItem label="Betta Fish" itemId="selectable-Betta Fish" />
            <TreeItem label="Guppies" itemId="selectable-Guppies" />
          </TreeItem>
          <TreeItem label="Marine Mammals" itemId="selectable-Marine Mammals">
            <TreeItem label="Dolphins" itemId="selectable-Dolphins" />
            <TreeItem label="Whales" itemId="selectable-Whales" />
            <TreeItem label="Seals" itemId="selectable-Seals" />
          </TreeItem>
        </TreeItem>
      </TreeView>
      <br />
      <>
        <p>Selected: {selectedItems}</p>
        <p> Indeterminate: {indeterminateItems}</p>
      </>
    </>
  );
}

Icons

If one TreeItem uses the icon prop, all other TreeItems should also have an icon. If one is not passed, default icons will be used: FolderIcon for branches and ArticleIcon for leafs.

import React from 'react';
import { TreeView, TreeItem, magma } from 'react-magma-dom';
import { FavoriteIcon } from 'react-magma-icons';

export function Example() {
  return (
    <>
      <TreeView ariaLabel="icon-example">
        <TreeItem
          label={<>I have an icon</>}
          icon={
            <FavoriteIcon
              style={{ color: magma.colors.primary500 }}
              aria-hidden={true}
            />
          }
          itemId="1"
        />
        <TreeItem label={<>I am a Branch without icon</>} itemId="2">
          <TreeItem label={<>I am a Leaf without an icon</>} itemId="3" />
          <TreeItem
            label={<>I have an icon</>}
            icon={
              <FavoriteIcon
                style={{ color: magma.colors.primary500 }}
                aria-hidden={true}
              />
            }
            itemId="4"
          />
        </TreeItem>
      </TreeView>
    </>
  );
}

Initial Expanded Items

To have a TreeItem expanded initially, pass an array of TreeItem itemIds to the TreeView.

import React from 'react';
import { TreeView, TreeItem, TreeViewSelectable } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <TreeView
        ariaLabel="single-select-treeview"
        selectable={TreeViewSelectable.single}
        initialExpandedItems={['initExpanded-Cats']}
      >
        <TreeItem label="Mammals" itemId="initExpanded-Mammals">
          <TreeItem label="Dogs" itemId="initExpanded-Dogs">
            <TreeItem
              label="German Shepherd"
              itemId="German initExpanded-Shepherd"
            />
            <TreeItem
              label="Labrador Retriever"
              itemId="Labrador initExpanded-Retriever"
            />
            <TreeItem
              label="American Bully"
              itemId="American initExpanded-Bully"
            />
          </TreeItem>
          <TreeItem label="Cats" itemId="initExpanded-Cats">
            <TreeItem label="Siamese" itemId="initExpanded-Siamese" />
            <TreeItem label="Persian" itemId="initExpanded-Persian" />
            <TreeItem label="Bengal" itemId="initExpanded-Bengal" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Birds" itemId="initExpanded-Birds">
          <TreeItem label="Parrots" itemId="initExpanded-Parrots">
            <TreeItem label="African Grey" itemId="African initExpanded-Grey" />
            <TreeItem label="Cockatiel" itemId="initExpanded-Cockatiel" />
            <TreeItem label="Budgerigar" itemId="initExpanded-Budgerigar" />
          </TreeItem>
          <TreeItem label="Birds of Prey" itemId="Birds of initExpanded-Prey">
            <TreeItem label="Eagles" itemId="initExpanded-Eagles" />
            <TreeItem label="Hawks" itemId="initExpanded-Hawks" />
            <TreeItem label="Falcons" itemId="initExpanded-Falcons" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </>
  );
}

Preselected Items

To have a TreeItem selected initially, pass an array of {itemId: 'itemId', checkedStatus: 'checked'} objects to the TreeView.

import React from 'react';
import { TreeView, TreeItem, TreeViewSelectable } from 'react-magma-dom';

export function Example() {
  return (
    <TreeView
      ariaLabel="preselected-treeview"
      selectable={TreeViewSelectable.multi}
      preselectedItems={[
        { itemId: 'presel-Birds', checkedStatus: 'checked' },
        { itemId: 'presel-Amphibians', checkedStatus: 'checked' },
      ]}
    >
      <TreeItem label="Mammals" itemId="presel-Mammals">
        <TreeItem label="Dogs" itemId="presel-Dogs">
          <TreeItem label="German Shepherd" itemId="presel-German Shepherd" />
          <TreeItem
            label="Labrador Retriever"
            itemId="presel-Labrador Retriever"
          />
          <TreeItem label="American Bully" itemId="presel-American Bully" />
        </TreeItem>
        <TreeItem label="Cats" itemId="presel-Cats">
          <TreeItem label="Siamese" itemId="presel-Siamese" />
          <TreeItem label="Persian" itemId="presel-Persian" />
          <TreeItem label="Bengal" itemId="presel-Bengal" />
        </TreeItem>
      </TreeItem>
      <TreeItem label="Birds" itemId="presel-Birds">
        <TreeItem label="Parrots" itemId="presel-Parrots">
          <TreeItem label="African Grey" itemId="presel-African Grey" />
          <TreeItem label="Cockatiel" itemId="presel-Cockatiel" />
          <TreeItem label="Budgerigar" itemId="presel-Budgerigar" />
        </TreeItem>
        <TreeItem label="Birds of Prey" itemId="presel-Birds of Prey">
          <TreeItem label="Eagles" itemId="presel-Eagles" />
          <TreeItem label="Hawks" itemId="presel-Hawks" />
          <TreeItem label="Falcons" itemId="presel-Falcons" />
        </TreeItem>
      </TreeItem>
      <TreeItem label="Amphibians" itemId="presel-Amphibians" />
    </TreeView>
  );
}

Aria Labels

If there is visible text that labels an element, use ariaLabelledBy.

If there is no visible name for the element you can reference, use ariaLabel to provide the user with a recognizable accessible name.

It's required to use either ariaLabel OR ariaLabelledBy.

import React from 'react';
import { TreeView, TreeItem } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <TreeView ariaLabel="animals">
        <TreeItem label="Mammals" itemId="Mammals">
          <TreeItem label="Dogs" itemId="Dogs">
            <TreeItem label="German Shepherd" itemId="German Shepherd" />
            <TreeItem label="Labrador Retriever" itemId="Labrador Retriever" />
            <TreeItem label="American Bully" itemId="American Bully" />
          </TreeItem>
          <TreeItem label="Cats" itemId="Cats">
            <TreeItem label="Siamese" itemId="Siamese" />
            <TreeItem label="Persian" itemId="Persian" />
            <TreeItem label="Bengal" itemId="Bengal" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Birds" itemId="Birds">
          <TreeItem label="Parrots" itemId="Parrots">
            <TreeItem label="African Grey" itemId="African Grey" />
            <TreeItem label="Cockatiel" itemId="Cockatiel" />
            <TreeItem label="Budgerigar" itemId="Budgerigar" />
          </TreeItem>
          <TreeItem label="Birds of Prey" itemId="Birds of Prey">
            <TreeItem label="Eagles" itemId="Eagles" />
            <TreeItem label="Hawks" itemId="Hawks" />
            <TreeItem label="Falcons" itemId="Falcons" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Reptiles" itemId="Reptiles" isDisabled>
          <TreeItem label="Snakes" itemId="Snakes">
            <TreeItem label="Python" itemId="Python" />
            <TreeItem label="Boa Constrictor" itemId="Boa Constrictor" />
            <TreeItem label="Corn Snake" itemId="Corn Snake" />
          </TreeItem>
          <TreeItem label="Lizards" itemId="Lizards">
            <TreeItem label="Geckos" itemId="Geckos" />
            <TreeItem label="Iguanas" itemId="Iguanas" />
            <TreeItem label="Chameleons" itemId="Chameleons" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Aquatic Animals" itemId="Aquatic Animals">
          <TreeItem label="Fish" itemId="Fish">
            <TreeItem label="Goldfish" itemId="Goldfish" />
            <TreeItem label="Betta Fish" itemId="Betta Fish" />
            <TreeItem label="Guppies" itemId="Guppies" />
          </TreeItem>
          <TreeItem label="Marine Mammals" itemId="Marine Mammals">
            <TreeItem label="Dolphins" itemId="Dolphins" />
            <TreeItem label="Whales" itemId="Whales" />
            <TreeItem label="Seals" itemId="Seals" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </>
  );
}

Check Children & Check Parents

In a multi-select tree view, the relationship between parents and children when you select an item is flexible depending on your needs. Using the props below, you can configure the component so that selecting an item has no cascading effect on any other item so they're truly independent, or the selection of a child or parent can automatically update surrounding items appropriately, including setting parents to an indeterminate state.

By default, the checkChildren and checkParents props are set to true.

import React from 'react';
import {
  TreeView,
  TreeItem,
  TreeViewSelectable,
  Toggle,
} from 'react-magma-dom';

export function Example() {
  const [checkChildren, setCheckChildren] = React.useState(false);
  const [checkParents, setCheckParents] = React.useState(false);

  const changeCheckChildren = () => setCheckChildren(prevVal => !prevVal);
  const changeCheckParents = () => setCheckParents(prevVal => !prevVal);

  return (
    <>
      <Toggle
        labelText="Check children when parent item is selected"
        onChange={changeCheckChildren}
        checked={checkChildren}
      />
      <Toggle
        labelText="Check parents when child item is selected"
        onChange={changeCheckParents}
        checked={checkParents}
      />
      <br />
      <TreeView
        checkParents={checkParents}
        checkChildren={checkChildren}
        ariaLabelledBy="animals-multi-checkparentschildren"
        selectable={TreeViewSelectable.multi}
      >
        <TreeItem label="Birds" itemId="selectable-birds">
          <TreeItem label="Parrots" itemId="selectable-parrots">
            <TreeItem label="African Grey" itemId="selectable-african Grey" />
            <TreeItem label="Cockatiel" itemId="selectable-cockatiel" />
            <TreeItem label="Budgerigar" itemId="selectable-budgerigar" />
          </TreeItem>
          <TreeItem label="Birds of Prey" itemId="selectable-birds of Prey">
            <TreeItem label="Eagles" itemId="selectable-eagles" />
            <TreeItem label="Hawks" itemId="selectable-hawks" />
            <TreeItem label="Falcons" itemId="selectable-falcons" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Aquatic Animals" itemId="selectable-aquatic Animals">
          <TreeItem label="Fish" itemId="selectable-fish">
            <TreeItem label="Goldfish" itemId="selectable-goldfish" />
            <TreeItem label="Betta Fish" itemId="selectable-betta Fish" />
            <TreeItem label="Guppies" itemId="selectable-guppies" />
          </TreeItem>
          <TreeItem label="Marine Mammals" itemId="selectable-marine Mammals">
            <TreeItem label="Dolphins" itemId="selectable-dolphins" />
            <TreeItem label="Whales" itemId="selectable-whales" />
            <TreeItem label="Seals" itemId="selectable-seals" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </>
  );
}

Update Selected Items From Outside

Use the apiRef prop to change items selection from outside. It exposes these functions: selectItem, selectAll, clearAll.

import React from 'react';
import {
  TreeView,
  TreeItem,
  Tag,
  IndeterminateCheckboxStatus,
  TreeViewSelectable,
  ButtonGroup,
  Button,
  ButtonColor,
  ButtonSize,
  ButtonVariant,
  TagSize,
  TagColor,
  TreeViewApi,
  TreeItemSelectedInterface,
  Heading,
} from 'react-magma-dom';

function createControlledTags(
  items: TreeItemSelectedInterface[] = [],
  api: TreeViewApi
) {
  const selected =
    items &&
    items
      .filter(i => i.checkedStatus === IndeterminateCheckboxStatus.checked)
      .map((i, key) => (
        <Tag
          key={key}
          size={TagSize.small}
          color={TagColor.primary}
          onDelete={() =>
            api.selectItem({
              itemId: i.itemId,
              checkedStatus: IndeterminateCheckboxStatus.unchecked,
            })
          }
        >
          {i.itemId}
        </Tag>
      ));

  const indeterminate =
    items &&
    items
      .filter(
        i => i.checkedStatus === IndeterminateCheckboxStatus.indeterminate
      )
      .map((i, key) => (
        <Tag
          key={key}
          size={TagSize.small}
          color={TagColor.default}
          onDelete={() =>
            api.selectItem({
              itemId: i.itemId,
              checkedStatus: IndeterminateCheckboxStatus.unchecked,
            })
          }
        >
          {i.itemId}
        </Tag>
      ));

  return {
    selected: selected || [],
    indeterminate: indeterminate || [],
  };
}

export function Example() {
  const [selectedItems, setSelectedItems] = React.useState(null);

  const apiRef = React.useRef<TreeViewApi>(null);

  const { selected, indeterminate } = createControlledTags(
    selectedItems,
    apiRef.current
  );

  return (
    <>
      <Heading level={3} id="ah-textbook">
        Gardner's Art through the ages
      </Heading>
      <TreeView
        ariaLabelledBy={'ah-textbook'}
        selectable={TreeViewSelectable.multi}
        apiRef={apiRef}
        onSelectedItemChange={setSelectedItems}
      >
        <TreeItem
          label={<>I. INTRODUCTION: WHAT IS ART HISTORY?</>}
          itemId="I-intro"
        >
          <TreeItem
            label={<>Art History in the 21st Century</>}
            itemId="I-21st-century"
          >
            <TreeItem
              label={<>The Questions Art Historians Ask</>}
              itemId="I-questions"
            />
            <TreeItem
              label={<>The Words Art Historians Use</>}
              itemId="I-words"
            >
              <TreeItem label={<>Vocabulary</>} itemId="I-vocab" />
            </TreeItem>
            <TreeItem
              label={<>Art History and Other Disciplines</>}
              itemId="I-other"
            />
          </TreeItem>
          <TreeItem
            label={<>Different Ways of Seeing</>}
            itemId="I-different-ways"
          />
        </TreeItem>
        <TreeItem label={<>1. ART IN THE STONE AGE</>} itemId="1-stone-age">
          <TreeItem label={<>Paleolithic Art</>} itemId="1-paleolithic">
            <TreeItem label={<>Africa</>} itemId="1-africa" />
            <TreeItem label={<>Europe</>} itemId="1-europe" />
          </TreeItem>
          <TreeItem label={<>Neolithic Art</>} itemId="1-neolithic">
            <TreeItem
              label={<>Anatolia and Mesopotamia</>}
              itemId="1-anatolia"
            />
            <TreeItem
              label={<>Europe</>}
              itemId="1-neolithic-europe"
              isDisabled
            />
          </TreeItem>
        </TreeItem>
        <TreeItem
          label={<>2. ANCIENT MESOPOTAMIA AND PERSIA</>}
          itemId="2-ancient"
        >
          <TreeItem label={<>Mesopotamia</>} itemId="2-mesopotamia">
            <TreeItem label={<>Sumer</>} itemId="2-sumer" />
            <TreeItem label={<>Akkad</>} itemId="2-akkad" />
            <TreeItem label={<>Third Dynasty of Ur</>} itemId="2-ur" />
            <TreeItem label={<>Babylon</>} itemId="2-babylon" />
            <TreeItem label={<>Elam</>} itemId="2-elam" />
            <TreeItem label={<>Assyria</>} itemId="2-assyria" />
            <TreeItem label={<>Neo-Babylonia</>} itemId="2-neo" />
          </TreeItem>
          <TreeItem label={<>Persia</>} itemId="2-persia">
            <TreeItem label={<>Achaemenid Empire</>} itemId="2-achaemenid" />
            <TreeItem label={<>Sasanian Empire</>} itemId="2-sasanian" />
          </TreeItem>
        </TreeItem>
      </TreeView>
      <br />
      <>
        <p>Selected: {selected}</p>
        <p>Indeterminate: {indeterminate}</p>
      </>
      <ButtonGroup size={ButtonSize.small} variant={ButtonVariant.solid}>
        <Button
          onClick={() => apiRef.current.selectAll()}
          color={ButtonColor.secondary}
        >
          Select all
        </Button>
        <Button
          onClick={() => apiRef.current.clearAll()}
          color={ButtonColor.secondary}
        >
          Clear all
        </Button>
      </ButtonGroup>
    </>
  );
}

Disabling TreeView

Styling for disabled item may not be visible if the user is passing a node to the label.

Use the isDisabled prop to disable all items inside TreeView.

import React from 'react';
import { TreeView, TreeItem, TreeViewSelectable } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <TreeView
        ariaLabelledBy="animals-multi-checkparentschildren"
        selectable={TreeViewSelectable.multi}
        initialExpandedItems={[
          'selectable-parrots 1',
          'selectable-birds of Prey 1',
        ]}
        isDisabled
      >
        <TreeItem label="Birds" itemId="selectable-birds 1">
          <TreeItem label="Parrots" itemId="selectable-parrots 1">
            <TreeItem label="African Grey" itemId="selectable-african Grey 1" />
            <TreeItem label="Cockatiel" itemId="selectable-cockatiel 1" />
            <TreeItem label="Budgerigar" itemId="selectable-budgerigar 1" />
          </TreeItem>
          <TreeItem label="Birds of Prey" itemId="selectable-birds of Prey 1">
            <TreeItem label="Eagles" itemId="selectable-eagles 1" />
            <TreeItem label="Hawks" itemId="selectable-hawks 1" />
            <TreeItem label="Falcons" itemId="selectable-falcons 1" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Aquatic Animals" itemId="selectable-aquatic Animals 1">
          <TreeItem label="Fish" itemId="selectable-fish 1">
            <TreeItem label="Goldfish" itemId="selectable-goldfish 1" />
            <TreeItem label="Betta Fish" itemId="selectable-betta Fish 1" />
            <TreeItem label="Guppies" itemId="selectable-guppies 1" />
          </TreeItem>
          <TreeItem label="Marine Mammals" itemId="selectable-marine Mammals 1">
            <TreeItem label="Dolphins" itemId="selectable-dolphins 1" />
            <TreeItem label="Whales" itemId="selectable-whales 1" />
            <TreeItem label="Seals" itemId="selectable-seals 1" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </>
  );
}

Disabling items

Pass the isDisabled prop to item inside preselectedItems prop to manage disabled state for the item.

import React from 'react';
import {
  TreeView,
  TreeItem,
  TreeViewSelectable,
  IndeterminateCheckboxStatus,
} from 'react-magma-dom';

export function Example() {
  return (
    <>
      <TreeView
        ariaLabelledBy="animals-multi-checkparentschildren"
        selectable={TreeViewSelectable.multi}
        initialExpandedItems={[
          'selectable-parrots 2',
          'selectable-birds of Prey 2',
        ]}
        preselectedItems={[
          {
            itemId: 'selectable-cockatiel 2',
            checkedStatus: IndeterminateCheckboxStatus.unchecked,
            isDisabled: true,
          },
          {
            itemId: 'selectable-budgerigar 2',
            checkedStatus: IndeterminateCheckboxStatus.checked,
            isDisabled: false,
          },
        ]}
      >
        <TreeItem label="Birds" itemId="selectable-birds 2">
          <TreeItem label="Parrots" itemId="selectable-parrots 2">
            <TreeItem label="African Grey" itemId="selectable-african Grey 2" />
            <TreeItem label="Cockatiel" itemId="selectable-cockatiel 2" />
            <TreeItem label="Budgerigar" itemId="selectable-budgerigar 2" />
          </TreeItem>
          <TreeItem label="Birds of Prey" itemId="selectable-birds of Prey 2">
            <TreeItem label="Eagles" itemId="selectable-eagles 2" isDisabled />
            <TreeItem label="Hawks" itemId="selectable-hawks 2" />
            <TreeItem label="Falcons" itemId="selectable-falcons 2" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Aquatic Animals" itemId="selectable-aquatic Animals 2">
          <TreeItem label="Fish" itemId="selectable-fish 2">
            <TreeItem label="Goldfish" itemId="selectable-goldfish 2" />
            <TreeItem label="Betta Fish" itemId="selectable-betta Fish 2" />
            <TreeItem label="Guppies" itemId="selectable-guppies 2" />
          </TreeItem>
          <TreeItem label="Marine Mammals" itemId="selectable-marine Mammals 2">
            <TreeItem label="Dolphins" itemId="selectable-dolphins 2" />
            <TreeItem label="Whales" itemId="selectable-whales 2" />
            <TreeItem label="Seals" itemId="selectable-seals 2" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </>
  );
}

Change Events

The following events are available: onSelectedItemChange and onExpandedChange.

import React from 'react';
import { TreeView, TreeItem, TreeViewSelectable } from 'react-magma-dom';

export function Example() {
  const [currentTreeEvent, setCurrentTreeEvent] = React.useState<
    string | undefined
  >(undefined);
  const [expandedItems, setExpandedItems] = React.useState<string[]>([]);

  function handleSelectedItemChange(event) {
    setCurrentTreeEvent('Selected');
  }

  function handleExpandedChange(event: React.SyntheticEvent, expandedItems: string[]) {
    setCurrentTreeEvent('Expanded');
    setExpandedItems(expandedItems);
  }

  return (
    <>
      <p>
        <strong>{currentTreeEvent || 'No'} event was triggered</strong>
        <br />
        <br />
        <strong>Expanded Items: {expandedItems ? expandedItems.join(', ') : ' '}</strong>
      </p>

      <TreeView
        ariaLabel="course-topics-change-events"
        selectable={TreeViewSelectable.multi}
        onSelectedItemChange={handleSelectedItemChange}
        onExpandedChange={handleExpandedChange}
      >
        <TreeItem label={<>Arts and Design</>} itemId="arts-design">
          <TreeItem label={<>Animation</>} itemId="animation" />
          <TreeItem label={<>Graphic Arts</>} itemId="graphic" />
          <TreeItem label={<>Photography</>} itemId="photography" />
          <TreeItem label={<>Web Design</>} itemId="webdesign" />
        </TreeItem>
        <TreeItem label={<>Business</>} itemId="business">
          <TreeItem label={<>Accounting</>} itemId="accounting" />
          <TreeItem label={<>Finance</>} itemId="finance" />
        </TreeItem>
        <TreeItem label={<>Computer Science</>} itemId="compsci">
          <TreeItem label={<>Software Engineering</>} itemId="swe" />
          <TreeItem label={<>Information Technology</>} itemId="it" />
        </TreeItem>
      </TreeView>
    </>
  );
}

Inverse

import React from 'react';
import { TreeView, TreeItem, Card } from 'react-magma-dom';

export function Example() {
  return (
    <Card isInverse style={{ padding: '12px' }}>
      <TreeView ariaLabel="animals" isInverse>
        <TreeItem label="Mammals" itemId="inverse-Mammals">
          <TreeItem label="Dogs" itemId="inverse-Dogs">
            <TreeItem
              label="German Shepherd"
              itemId="inverse-German Shepherd"
            />
            <TreeItem
              label="Labrador Retriever"
              itemId="inverse-Labrador Retriever"
            />
            <TreeItem label="American Bully" itemId="inverse-American Bully" />
          </TreeItem>
          <TreeItem label="Cats" itemId="inverse-Cats">
            <TreeItem label="Siamese" itemId="inverse-Siamese" />
            <TreeItem label="Persian" itemId="inverse-Persian" />
            <TreeItem label="Bengal" itemId="inverse-Bengal" />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Birds" itemId="inverse-Birds">
          <TreeItem label="Parrots" itemId="inverse-Parrots">
            <TreeItem label="African Grey" itemId="inverse-African Grey" />
            <TreeItem label="Cockatiel" itemId="inverse-Cockatiel" />
            <TreeItem label="Budgerigar" itemId="inverse-Budgerigar" />
          </TreeItem>
          <TreeItem label="Birds of Prey" itemId="inverse-Birds of Prey">
            <TreeItem label="Eagles" itemId="inverse-Eagles" />
            <TreeItem label="Hawks" itemId="inverse-Hawks" />
            <TreeItem label="Falcons" itemId="inverse-Falcons" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </Card>
  );
}

Custom Styles

Use the labelStyle prop to customize the TreeItem labels.

import React from 'react';
import { TreeView, TreeItem, magma } from 'react-magma-dom';

export function Example() {
  return (
    <>
      <TreeView ariaLabel="custom-label">
        <TreeItem
          label="Reptiles"
          itemId="custom-Reptiles"
          labelStyle={{ color: magma.colors.danger600 }}
        >
          <TreeItem
            label="Snakes"
            itemId="custom-Snakes"
            labelStyle={{ color: magma.colors.info700, fontWeight: '600' }}
            style={{ background: magma.colors.info100 }}
          >
            <TreeItem label="Python" itemId="custom-Python" />
            <TreeItem label="Boa Constrictor" itemId="custom-Boa Constrictor" />
            <TreeItem label="Corn Snake" itemId="custom-Corn Snake" />
          </TreeItem>
          <TreeItem label="Lizards" itemId="custom-Lizards">
            <TreeItem
              label="Geckos"
              itemId="custom-Geckos"
              labelStyle={{ fontStyle: 'italic' }}
            />
            <TreeItem
              label="Iguanas"
              itemId="custom-Iguanas"
              labelStyle={{ fontStyle: 'italic' }}
            />
            <TreeItem
              label="Chameleons"
              itemId="custom-Chameleons"
              labelStyle={{ fontStyle: 'italic' }}
            />
          </TreeItem>
        </TreeItem>
        <TreeItem label="Aquatic Animals" itemId="custom-Aquatic Animals">
          <TreeItem label="Fish" itemId="custom-Fish">
            <TreeItem label="Goldfish" itemId="custom-Goldfish" />
            <TreeItem label="Betta Fish" itemId="custom-Betta Fish" />
            <TreeItem label="Guppies" itemId="custom-Guppies" />
          </TreeItem>
          <TreeItem
            label="Marine Mammals"
            itemId="custom-Marine Mammals"
            labelStyle={{ color: magma.colors.success700, fontWeight: '600' }}
            style={{ background: magma.colors.success100 }}
          >
            <TreeItem label="Dolphins" itemId="custom-Dolphins" />
            <TreeItem label="Whales" itemId="custom-Whales" />
            <TreeItem label="Seals" itemId="custom-Seals" />
          </TreeItem>
        </TreeItem>
      </TreeView>
    </>
  );
}

TreeView Props

Any other props supplied will be provided to the wrapping ul element.

apiRef

Description

The ref object that allows TreeView manipulation. Actions available: selectItem({ itemId, checkedStatus }: Pick<TreeViewItemInterface, 'itemId' | 'checkedStatus'>): void - action that allows to change item selection, selectAll(): void - action that allows to select all items, clearAll(): void - action that allows to unselect all items.

Type

MutableRefObject

Default

ariaLabel

Description

Text for aria-label attribute for the tree. If there is no visible name for the element you can reference, use aria-label to provide the user with a recognizable accessible name. It's required to use either `ariaLabel` OR `ariaLabelledBy`.

Type

string

Default

ariaLabelledBy

Description

Text for aria-labelledby attribute for the tree. If there is visible text that labels an element, use aria-labelledby. It's required to use either `ariaLabel` OR `ariaLabelledBy`.

Type

string

Default

checkChildren

Description

Only affects if selectable mode is TreeViewSelectable.multi. Determines if the child checkboxes get selected when the user selects parent checkbox.

Type

boolean

Default

true

checkParents

Description

Only affects if selectable mode is TreeViewSelectable.multi. Determines if the parent checkbox will get selected when the user selects all its children checkboxes. When checkParents is enabled, the TreeView displays the indeterminate state of the parent checkboxes too.

Type

boolean

Default

true

children

Description

The content of the component

Type

| React.ReactNode

Default

initialExpandedItems

Description

Array list of itemIds of items that should be expanded by default. For all items expanded, provide an array with all the indexes

Type

Array

Default

[] (no items expanded)

isDisabled

Description

If true, every item is disabled

Type

boolean

Default

false

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

onExpandedChange

Description

Action that fires when an item is expanded or collapsed Return an array of itemIds of items that are expanded Example: ['item0', 'item1', 'item3']

Type

function

Default

onSelectedItemChange

Description

Action that fires when an item is selected Return an array of objects. Example: [ {itemId: 'item0', checkedStatus: IndeterminateCheckboxStatus.indeterminate}, {itemId: 'item0-child', checkedStatus: IndeterminateCheckboxStatus.checked} ]

Type

function

Default

preselectedItems

Description

Array list of itemIds of items that should be selected when the component renders * @default [] (no items selected)

Type

Array

Default

selectable

Description

How many items can be selected in the tree view: single, multi, off

Type

enum, one of:
TreeViewSelectable.multi
TreeViewSelectable.off
TreeViewSelectable.single

Default

TreeViewSelectable.single

TreeItem Props

Any other props supplied will be provided to the wrapping li element.

icon

Description

Icon for the tree item

Type

ReactElement

Default

index

Description

Index number private

Type

number

Default

isDisabled

Description

If true, element is disabled

Type

boolean

Default

false

itemId

Required

Description

Item id

Type

string

Default

label

Required

Description

Item name

Type

React.ReactNode

Default

labelStyle

Description

Style properties for the tree item label

Type

CSSProperties

Default

onClick

Description

Action that fires when the item is clicked

Type

function

Default

On this page

Design

Components

Patterns

TreeView

Basic Usage

Selectable

Icons

Initial Expanded Items

Preselected Items

Aria Labels

Check Children & Check Parents

Update Selected Items From Outside

Disabling TreeView

Disabling items

Change Events

Inverse

Custom Styles

TreeView Props

TreeItem Props