Tree Item Customization

Learn how to customize the Tree Item component.

Anatomy

Each Tree Item component is shaped by a series of composable slots. Hover over them in the demo below to see each slot.

Content

Use the content slot to customize the content of the Tree Item or replace it with a custom component.

Slot props

The slotProps prop lets you pass props to the content component. The demo below shows how to pass an sx handler to the content of the Tree Item:

Slot

The demo below shows how to replace the content slot with a custom component.

Label

Use the label slot to customize the Tree Item label or replace it with a custom component.

Slot props

The slotProps prop lets you pass props to the label component. The demo below shows how to pass an id attribute to the Tree Item label:

Slot

The demo below shows how to replace the label slot with a custom component.

Checkbox

The checkbox is present on the items when checkboxSelection is enabled on the Tree View.

Slot props

You can pass props to the checkbox slot using the slotProps on the Tree Item 2 component.

Slot

The demo below shows how to replace the checkbox slot with a custom component.

Basics

Change nested item's indentation

Use the itemChildrenIndentation prop to change the indentation of the nested items. By default, a nested item is indented by 12px from its parent item.

Apply the nested item's indentation at the item level

By default, the indentation of nested items is applied by the groupTransition slot of its parent (i.e.: the DOM element that wraps all the children of a given item). This approach is not compatible with upcoming features like the reordering of items using drag & drop.

To apply the indentation at the item level (i.e.: have each item responsible for setting its own indentation using the padding-left CSS property on its content slot), you can use the indentationAtItemLevel experimental feature. It will become the default behavior in the next major version of the Tree View component.

Hooks

useTreeItem2

The useTreeItem2 hook lets you manage and customize individual Tree Items. You can use it to get the properties needed for all slots, the status of any given Item, or to tap into the interactive API of the Tree View.

Slot properties

The useTreeItem2 hook gives you granular control over an Item's layout by providing resolvers to get the appropriate props for each slot. This makes it possible to build a fully custom layout for your Tree Items.

The demo below shows how to get the props needed for each slot, and how to pass them correctly.

You can pass additional props to a slot—or override existing slots—by passing an object argument to the slot's props resolver, as shown below:

<CustomTreeItemContent
  {...getContentProps({
    className: 'overridingClassName',
    newProp: 'I am passing this to the content slot'
  })}
>

Item status

The useTreeItem2 hook also returns a status object that holds boolean values for each possible state of a Tree Item.

const {
  status: { expanded, expandable, focused, selected, disabled, editable, editing },
} = useTreeItem2(props);

You can use these statuses to apply custom styling to the item or conditionally render subcomponents.

Imperative API

The publicAPI object provides a number of methods to programmatically interact with the Tree View. You can use the useTreeItem2 hook to access the publicAPI object from within a Tree Item.

See the Imperative API section on each feature page to learn more about the public API methods available on the Tree View.

useTreeItem2Utils

The useTreeItem2Utils hook provides a set of interaction methods for implementing custom behaviors for the Tree View. It also returns the status of the Item.

const { interactions, status } = useTreeItem2Utils({
  itemId: props.itemId,
  children: props.children,
});

To override the Tree Item's default interactions, set event.defaultMuiPrevented to true in the event handlers and then implement your own behavior.

Selection

You can select an Item in a Tree View by clicking its content slot. The demo below shows how to handle selection when the user clicks on an icon.

Checkbox selection

By default, checkbox selection is skipped if an Item is disabled or if disableSelection is true on the Tree View. You can create a custom handler for the onChange event on the checkbox slot to bypass these conditions. The demo below shows how to implement custom checkbox selection behavior.

Visit the Rich Tree View or Simple Tree View docs, respectively, for more details on the selection API.

Expansion

By default, a Tree Item is expanded when the user clicks on its contents. You can change the expansion trigger using the expansionTrigger prop on the iconContainer. For more details, see Expansion—Limit expansion to icon container.

Use the handleExpansion interaction method for deeper customization of the Item's expansion behavior.

The demo below shows how to introduce a new element that expands and collapses the Item.

Label editing

The useTreeItem2Utils hook provides the following interaction methods relevant to label editing behavior:

const {
  interactions: {
    toggleItemEditing,
    handleCancelItemLabelEditing,
    handleSaveItemLabel,
  },
} = useTreeItem2Utils({
  itemId: props.itemId,
  children: props.children,
});

See Editing—enable editing using only icons for more details on customizing this behavior.

API

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

• <RichTreeView />
• <SimpleTreeView />
• <TreeItem />
• <TreeItem2 />