---

name: umbraco-backoffice description: Blueprints for Umbraco backoffice customisation - complete working examples showing how extension types combine version: 1.0.0 location: managed allowed-tools: Read, Write, Edit, WebFetch

Umbraco Backoffice Blueprints

What This Skill Does

Backoffice customisations are combinations of extension types working together:

• A "custom admin area" = Section + Menu + Dashboard
• A "data management tool" = Section + Menu + Workspace
• A "hierarchical browser" = Section + Menu + Tree + Workspace

This skill provides complete working blueprints. The source code is in ./examples/ - copy and adapt for your needs.

For details on individual extension types, invoke the referenced sub-skills.

TIP: If the Umbraco CMS source code is available in your workspace, use it as a reference and for inspiration. The backoffice client code in src/Umbraco.Web.UI.Client/src/packages/ shows production implementations of all extension types - study how the core team structures sections, workspaces, trees, and other patterns.

---

Backoffice Extension Map

This diagram shows where ALL extension types appear in the Umbraco backoffice UI:

Copy┌─────────────────────────────────────────────────────────────────────────────────┐
│ HEADER BAR                                                                       │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           ┌───────────────────┐ │
│ │ Content │ │  Media  │ │Settings │ │ Section │  ...      │    Header Apps    │ │
│ │         │ │         │ │         │ │  ****   │           │ (umbraco-header-  │ │
│ │         │ │         │ │         │ │         │           │     apps)         │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘           └───────────────────┘ │
│      ^                        ^                                    ^            │
│      │                        │                                    │            │
│  (umbraco-sections)      Your Section                    User menu, search,     │
│                                                          notifications          │
├─────────────────────────────────────────────────────────────────────────────────┤
│ SIDEBAR                    │  MAIN CONTENT AREA                                 │
│ ┌────────────────────────┐ │ ┌─────────────────────────────────────────────────┐│
│ │ SectionSidebarApp      │ │ │ Dashboard (umbraco-dashboard)                   ││
│ │ (part of sections)     │ │ │ Shows when nothing selected in tree             ││
│ │                        │ │ │ ┌─────────────────────────────────────────────┐ ││
│ │ ┌────────────────────┐ │ │ │ │ Your welcome content, stats, quick actions │ ││
│ │ │ Menu               │ │ │ │ └─────────────────────────────────────────────┘ ││
│ │ │ (umbraco-menu)     │ │ │ └─────────────────────────────────────────────────┘│
│ │ │                    │ │ │                                                    │
│ │ │ ┌────────────────┐ │ │ │ ┌─────────────────────────────────────────────────┐│
│ │ │ │ MenuItem       │ │ │ │ │ Workspace (umbraco-workspace)                   ││
│ │ │ │ (umbraco-menu- │ │ │ │ │ Shows when entity selected                      ││
│ │ │ │     items)     │ │ │ │ │ ┌─────────────────────────────────────────────┐ ││
│ │ │ │                │ │ │ │ │ │ WorkspaceView tabs (Content, Settings...)  │ ││
│ │ │ │ kind: "tree"───┼─┼─┼─┼─┤ │ ┌─────────┐ ┌─────────┐ ┌─────────┐       │ ││
│ │ │ └────────────────┘ │ │ │ │ │ │ View 1  │ │ View 2  │ │ View 3  │       │ ││
│ │ │                    │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘       │ ││
│ │ │ ┌────────────────┐ │ │ │ │ └─────────────────────────────────────────────┘ ││
│ │ │ │ Tree           │ │ │ │ │                                                 ││
│ │ │ │ (umbraco-tree) │ │ │ │ │ WorkspaceActions (Save, Delete...)             ││
│ │ │ │                │ │ │ │ │ (umbraco-entity-actions)                        ││
│ │ │ │ ├─ Folder      │ │ │ │ └─────────────────────────────────────────────────┘│
│ │ │ │ │  └─ Item ────┼─┼─┼─┼──> entityType links to Workspace                  │
│ │ │ │ └─ Item        │ │ │ │                                                    │
│ │ │ │   (umbraco-    │ │ │ │ ┌─────────────────────────────────────────────────┐│
│ │ │ │    tree-item)  │ │ │ │ │ Collection (umbraco-collection)                 ││
│ │ │ └────────────────┘ │ │ │ │ List/grid view of items                         ││
│ │ └────────────────────┘ │ │ │ ┌─────────────────────────────────────────────┐ ││
│ └────────────────────────┘ │ │ │ CollectionView (umbraco-collection-view)    │ ││
│                            │ │ │ CollectionAction (umbraco-collection-action)│ ││
│                            │ │ └─────────────────────────────────────────────┘ ││
│                            │ └─────────────────────────────────────────────────┘│
├────────────────────────────┴────────────────────────────────────────────────────┤
│ MODALS & OVERLAYS (umbraco-modals)                                              │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Pickers, confirmations, custom dialogs - appear above main content          │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ PROPERTY EDITORS (in Document/Media workspaces)                                 │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ PropertyEditorUI (umbraco-property-editor-ui)  - The visual editor          │ │
│ │ PropertyEditorSchema (umbraco-property-editor-schema) - Data validation     │ │
│ │ PropertyAction (umbraco-property-action) - Buttons on property              │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ RICH TEXT EDITOR (Tiptap)                                                       │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ TiptapExtension (umbraco-tiptap-extension) - Core editor behavior           │ │
│ │ TiptapToolbarExtension (umbraco-tiptap-toolbar-extension) - Toolbar buttons │ │
│ │ TiptapStatusbarExtension (umbraco-tiptap-statusbar-extension) - Status bar  │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ GLOBAL FEATURES                                                                 │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ SearchProvider (umbraco-search-provider) - Global search results            │ │
│ │ SearchResultItem (umbraco-search-result-item) - Custom result rendering     │ │
│ │ HealthCheck (umbraco-health-check) - Settings > Health Check                │ │
│ │ Theme (umbraco-theme) - Custom backoffice themes                            │ │
│ │ Icons (umbraco-icons) - Custom icon sets                                    │ │
│ │ AuthProvider (umbraco-auth-provider) - External login buttons               │ │
│ │ MfaLoginProvider (umbraco-mfa-login-provider) - 2FA methods                 │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘

---

Available Examples

Each example has a detailed README.md with full documentation. See the examples/ folder.

Quick Reference

• Need a new section? Start with Blueprint
• Need tree navigation? See tree-example
• Need specific extension type? Check TimeDashboard for examples
• Need full-stack with API? Study notes-wiki

---

All Available Sub-Skills

UI Extension Skills

Invoke these skills for detailed documentation on each extension type:

Action Skills

Property Editor Skills

Rich Text Editor Skills

Search & Global Features

Authentication Skills

User & Package Skills

Advanced Configuration

Foundation Concepts

Essential patterns used across all extensions:

CRITICAL: When calling custom C# API endpoints from the backoffice, NEVER use raw fetch(). This will result in 401 Unauthorized errors. Always use a generated OpenAPI client configured with Umbraco's auth context. See the umbraco-openapi-client skill.

Build & Structure

---

Using the Examples

1. Browse the examples/ folder and read the README.md for each example
2. Copy the example closest to your needs into your project
3. Rename aliases from the example namespace to your own (e.g., Blueprint.* to MyApp.*)
4. Update the entityType values to match your domain
5. Customise the UI components for your use case
6. Register with Umbraco via umbraco-package.json
7. Add project reference to the main Umbraco instance - use skill umbraco-add-extension-reference