Tree Models

Understanding Tree Item and Root models in Umbraco

Trees use two model types to represent data: Tree Item Model for individual nodes and Tree Root Model for the root node. Your Repository returns these models from its methods.

UmbTreeItemModel

The base interface for Tree Items. All Tree Items must include these properties:

interface UmbTreeItemModel {
  unique: string;        // Identifier for selection, navigation, and API calls
  entityType: string;    // Must match Workspace meta.entityType for navigation
  name: string;          // Display name shown in the tree
  hasChildren: boolean;  // Shows expand arrow when true
  isFolder: boolean;     // Visual styling hint
  icon?: string;         // Icon name (e.g., 'icon-document', 'icon-folder')
  parent?: {             // Parent reference for hierarchy and breadcrumbs
    unique: string;      // Parent's identifier
    entityType: string;  // Parent's entity type
  };
}

Extending the Model

Add custom properties by extending the base interface:

import type { UmbTreeItemModel } from '@umbraco-cms/backoffice/tree';

export interface MyTreeItemModel extends UmbTreeItemModel {
  // Add custom properties
  status: 'draft' | 'published';
  lastModified: string;
}

Your repository methods transform API responses into these models when returning data.

UmbTreeRootModel

The root model represents the top-level node of your Tree. It extends UmbTreeItemModel but typically has unique: null:

interface UmbTreeRootModel extends UmbTreeItemModel {
  unique: null;  // Root has no parent, so unique is null
}

Defining a Root Model

import type { UmbTreeRootModel } from '@umbraco-cms/backoffice/tree';

export interface MyTreeRootModel extends UmbTreeRootModel {
  // Root-specific properties if needed
}

// Example root data returned by repository
const rootData: MyTreeRootModel = {
  unique: null,
  entityType: 'my-tree-root',
  name: 'My Tree',
  hasChildren: true,
  isFolder: true,
  icon: 'icon-folder',
};

The root model is returned by requestTreeRoot() in your Tree Repository.

Entity Types

You typically define two entity types - one for the root and one for items:

// types.ts
export const MY_TREE_ROOT_ENTITY_TYPE = 'my-tree-root';
export const MY_TREE_ITEM_ENTITY_TYPE = 'my-tree-item';

export interface MyTreeRootModel extends UmbTreeRootModel {
  entityType: typeof MY_TREE_ROOT_ENTITY_TYPE;
}

export interface MyTreeItemModel extends UmbTreeItemModel {
  entityType: typeof MY_TREE_ITEM_ENTITY_TYPE;
}

The entityType values must match the values in your Workspace and Tree Item Manifests. See Trees & Workspaces for how these connect.

Related

• Tree Repository - Returns Tree models from its methods.

• Trees & Workspaces - How entityType connects to Workspaces.