Terminal
Terminal/Skill
Guides building tree items, which control how entities appear in Umbraco backoffice sidebars and navigation trees.
By Umbraco
Works with
npx skills add umbraco/umbraco-cms-backoffice-skills --skill umbraco-tree-itemTree Items define how entities are rendered in tree structures throughout the Umbraco backoffice. They control the visual representation and behavior of items in sidebars and navigation trees. Tree items are associated with entity types and can be customized to display additional information, icons, or custom rendering for specific entity types.
Always fetch the latest docs before implementing:
Most tree items use kind: 'default' and don't need a custom context. Only create a custom context for:
If you just need standard tree items, use kind: 'default' without a custom context.
Tree: Tree items work within tree structures
umbraco-treeRepository Pattern: When loading tree data
umbraco-repository-patternContext API: When accessing tree context
umbraco-context-apiexport const manifests: Array<UmbExtensionManifest> = [
{
type: 'treeItem',
kind: 'default',
alias: 'My.TreeItem',
name: 'My Tree Item',
forEntityTypes: ['my-entity-type'],
},
];
import { MY_ENTITY_TYPE, MY_ROOT_ENTITY_TYPE } from '../entity.js';
export const manifests: Array<UmbExtensionManifest> = [
{
type: 'treeItem',
kind: 'default',
alias: 'My.TreeItem.Custom',
name: 'My Custom Tree Item',
forEntityTypes: [MY_ENTITY_TYPE, MY_ROOT_ENTITY_TYPE],
api: () => import('./my-tree-item.context.js'),
},
];
import { UmbDefaultTreeItemContext } from '@umbraco-cms/backoffice/tree';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import type { UmbTreeItemModel, UmbTreeRootModel } from '@umbraco-cms/backoffice/tree';
export class MyTreeItemContext extends UmbDefaultTreeItemContext<
UmbTreeItemModel,
UmbTreeRootModel
> {
constructor(host: UmbControllerHost) {
super(host);
}
// Override to customize icon
override async getIcon() {
const item = this.getTreeItem();
if (item?.hasChildren) {
return 'icon-folder';
}
return 'icon-document';
}
// Override to add custom labels/badges
override async getLabel() {
const item = this.getTreeItem();
return item?.name ?? 'Unknown';
}
}
export { MyTreeItemContext as api };
import { MY_ENTITY_TYPE, MY_ROOT_ENTITY_TYPE } from './entity.js';
import { MY_TREE_ALIAS, MY_TREE_REPOSITORY_ALIAS } from './constants.js';
export const manifests: Array<UmbExtensionManifest> = [
// Tree definition
{
type: 'tree',
kind: 'default',
alias: MY_TREE_ALIAS,
name: 'My Tree',
meta: {
repositoryAlias: MY_TREE_REPOSITORY_ALIAS,
},
},
// Tree item for the entities
{
type: 'treeItem',
kind: 'default',
alias: 'My.TreeItem',
name: 'My Tree Item',
forEntityTypes: [MY_ROOT_ENTITY_TYPE, MY_ENTITY_TYPE],
},
];
interface ManifestTreeItem extends ManifestElementAndApi<UmbControllerHostElement, UmbTreeItemContext> {
type: 'treeItem';
forEntityTypes: Array<string>; // Entity types this tree item renders
}
Built-in entity types that have tree items:
document - Content nodesdocument-root - Content rootmedia - Media itemsmedia-root - Media rootmember - Membersdata-type - Data typesdocument-type - Document typestemplate - TemplatesThe kind: 'default' uses the standard tree item rendering. Custom kinds can be created for specialized rendering.
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.