Rich Tree View - Items

Pass data to your Tree View.

Basic usage

Use the items prop to define items. This prop expects an array of objects.

Item identifier

Each item must have a unique identifier. This identifier is used internally to identify the item in the various models and to track the item across updates.

By default, RichTreeView looks for a property named id in the data set to get that identifier:

const ITEMS = [{ id: 'tree-view-community' }];

<RichTreeView items={ITEMS} />;

If the item's identifier is not called id, then you must use the getItemId prop to tell RichTreeView where it is located.

The following demo shows how to use getItemId to grab the unique identifier from a property named internalId:

const ITEMS = [{ internalId: 'tree-view-community' }];

function getItemId(item) {
  return item.internalId;
}

<RichTreeView items={ITEMS} getItemId={getItemId} />;

Item label

Each item must have a label which does not need to be unique.

By default, RichTreeView looks for a property named label in the data set to get that label:

const ITEMS = [{ label: '@mui/x-tree-view' }];

<RichTreeView items={ITEMS} />;

If the item's label is not called label, then you must use the getItemLabel prop to tell RichTreeView where it's located:

The following demo shows how to use getItemLabel to grab the unique identifier from a property named name:

const ITEMS = [{ name: '@mui/x-tree-view' }];

function getItemLabel(item) {
  return item.name;
}

<RichTreeView items={ITEMS} getItemLabel={getItemLabel} />;

Item children

Each item can contain children, which are rendered as nested nodes in the tree.

By default, RichTreeView looks for a property named children in the data set to get the children:

const ITEMS = [
  { children: [{ id: 'tree-view-community', label: '@mui/x-tree-view' }] },
];

<RichTreeView items={ITEMS} />;

If the item's children are not called children, then you must use the getItemChildren prop to tell RichTreeView where they're located:

The following demo shows how to use getItemChildren to grab the children from a property named nodes:

const ITEMS = [
  { nodes: [{ id: 'tree-view-community', label: '@mui/x-tree-view' }] },
];

function getItemChildren(item) {
  return item.nodes;
}

<RichTreeView items={ITEMS} getItemChildren={getItemChildren} />;

Disabled items

Use the isItemDisabled prop on RichTreeView to disable interaction and focus on a TreeItem:

function isItemDisabled(item) {
  return item.disabled ?? false;
}

<RichTreeView isItemDisabled={isItemDisabled} />;

Focus disabled items

Use the disabledItemsFocusable prop to control if disabled TreeItem components can be focused.

When this prop is set to false:

• Disabled items will not receive focus when navigating with keyboard arrow keys—they next non-disabled item is focused instead.
• Typing the first character of a disabled item's label will not move the focus to it.
• Mouse or keyboard interactions will not expand or collapse disabled items.
• Mouse or keyboard interactions will not select disabled items.
• Shift + arrow keys will skip disabled items, and the next non-disabled item will be selected instead.
• Programmatic focus will not focus disabled items.

When it's set to true:

• Disabled items will receive focus when navigating with keyboard arrow keys.
• Typing the first character of a disabled item's label will move focus to it.
• Mouse or keyboard interactions will not expand or collapse disabled items.
• Mouse or keyboard interactions will not select disabled items.
• Shift + arrow keys will not skip disabled items, but the disabled item will not be selected.
• Programmatic focus will focus disabled items.

Track item clicks

Use the onItemClick prop to track the clicked item:

Imperative API

To use the apiRef object, you need to initialize it using the useRichTreeViewApiRef() or useRichTreeViewProApiRef() hook as follows:

// Community package
const apiRef = useRichTreeViewApiRef();

return <RichTreeView apiRef={apiRef} items={ITEMS} />;

// Pro package
const apiRef = useRichTreeViewProApiRef();

return <RichTreeViewPro apiRef={apiRef} items={ITEMS} />;

When your component first renders, apiRef.current is undefined. After the initial render, apiRef holds methods to interact imperatively with RichTreeView.

Get an item by ID

Use the getItem() API method to get an item by its ID.

const item = apiRef.current.getItem(
  // The id of the item to retrieve
  itemId,
);

Get an item's DOM element by ID

Use the getItemDOMElement() API method to get an item's DOM element by its ID.

const itemElement = apiRef.current.getItemDOMElement(
  // The id of the item to get the DOM element of
  itemId,
);

Get the current item tree

Use the getItemTree() API method to get the current item tree.

const itemTree = apiRef.current.getItemTree();

Get an item's children by ID

Use the getItemOrderedChildrenIds() API method to get an item's children by its ID.

const childrenIds = apiRef.current.getItemOrderedChildrenIds(
  // The id of the item to retrieve the children from
  itemId,
);

Get an item's parent id

Use the getParentId() API method to get the ID of the item's parent.

publicAPI.getParentId(itemId);

Imperatively disable an item

Use the setIsItemDisabled() API method to imperatively toggle the item's disabled state.

publicAPI.setIsItemDisabled({
  // The id of the item to disable or enable
  itemId,
  // If `true` the item will be disabled
  // If `false` the item will be enabled
  // If not defined, the item's new disable status will be the opposite of its current one
  shouldBeDisabled: true,
});

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <RichTreeView />
• <TreeItem />