Trees

A guide to creating a custom Tree in Umbraco

New to sidebar navigation? Read Menus and Menu Items first. For basic, static navigation you can use Menu Items alone. Trees are for data-driven hierarchical structures - use them when your Menu needs to display dynamic content from an API.

To create a working Tree in the Backoffice, you need to understand three things:

1. Populating Trees - How to populate a Tree with data.

2. Displaying Trees - How to display Trees and connect them to Menus to appear in the Section Sidebar or elsewhere.

3. Trees and Workspaces - How to navigate to Workspaces by clicking Menu Items.

Populating Trees

Trees get their data from a Repository. The Repository implements methods to return Tree Items and is referenced by the Tree Manifest via repositoryAlias.

Register the Repository

{
    type: 'repository',
    alias: 'My.Tree.Repository',
    name: 'My Tree Repository',
    api: () => import('./my-tree.repository.js'),
}

Repository Implementation

Create a Repository that implements the TreeRepository interface. The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the UI API Documentation

interface UmbTreeRepository {
    requestTreeRoot();
    requestTreeRootItems();
    requestTreeItemsOf();
    requestTreeItemAncestors();
}

For detailed implementation guidance, see:

• Tree Repository - Full repository implementation with static data example.

• Tree Models - UmbTreeItemModel and UmbTreeRootModel interfaces.

---

Displaying Trees

Tree Manifest

Register your tree with a Manifest. The repositoryAlias links to how the Tree gets its data:

{
    type: 'tree',
    kind: 'default',
    alias: 'My.Tree',
    name: 'My Tree',
    meta: {
        repositoryAlias: 'My.Tree.Repository',
    },
}

Tree Item Manifest

Tree-items define how individual items render. Use kind: 'default' for standard rendering:

{
    type: 'treeItem',
    kind: 'default',
    alias: 'My.TreeItem',
    forEntityTypes: ['my-tree-root', 'my-tree-item'],
}

Include both your root entity type and item entity type in forEntityTypes so the Tree Item renderer handles all nodes in your Tree.

Standalone Rendering

Trees can be rendered directly in custom components using the <umb-tree> element:

<umb-tree alias="My.Tree"></umb-tree>

Connecting to a Menu

Trees can also provide hierarchical data to Menu Items, which display the navigation you see in the Backoffice Section Sidebar. To register your Tree-based Menu Item use the kind: 'tree' in the Menu Item Manifest.

{
    type: 'menuItem',
    kind: 'tree',
    alias: 'My.MenuItem.Tree',
    name: 'My Tree Menu Item',
    weight: 100,
    meta: {
        label: 'My Tree',
        icon: 'icon-folder',
        entityType: 'my-tree-root',
        menus: ['My.Menu'] // The Menu alias where this item should appear,
        treeAlias: 'My.Tree',
        hideTreeRoot: true,  // Optional: show items at root level
    },
}

Examples of built-in Menus include:

• Content - Umb.Menu.Content

• Media - Umb.Menu.Media

• Advanced Settings - Umb.Menu.AdvancedSettings

See Menu Items (Tree kind) and Section Sidebar for the complete setup.

---

Trees and Workspaces

When users click a Tree Item, Umbraco navigates to a Workspace to edit that item. The entityType in your Tree Items must match the meta.entityType in your Workspace Manifest.

See Trees & Workspaces for setup details and troubleshooting.

---

Further Reading

• Umbraco UI Examples - Trees - Working examples in the Umbraco repository.

• Workspaces - Creating Workspace extensions.