Umbraco Conditions

What is it?

Extension Conditions enable developers to declare requirements that must be met before an extension becomes available in the backoffice. They function as gatekeeping mechanisms controlling when and where extensions appear based on context like section, workspace, user permissions, or content type. Multiple conditions use AND logic—all must pass for the extension to display.

Documentation

Always fetch the latest docs before implementing:

Main docs: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-conditions
Extension Types: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types
Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation

Reference Example

The Umbraco source includes a working example:

Location: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/entity-content-type-condition/

This example demonstrates a custom condition that checks entity content type. Study this for patterns on creating custom conditions.

Workflow

Fetch docs - Use WebFetch on the URLs above
Ask questions - What restricts visibility? Section? Workspace? User? Content type?
Generate code - Add conditions to manifest based on latest docs
Explain - Show what was created and when extension appears

Minimal Examples

Section Condition

{
  "type": "dashboard",
  "alias": "My.Dashboard",
  "name": "My Dashboard",
  "conditions": [
    {
      "alias": "Umb.Condition.SectionAlias",
      "match": "Umb.Section.Content"
    }
  ]
}

Workspace Condition

{
  "type": "workspaceView",
  "alias": "My.WorkspaceView",
  "name": "My Workspace View",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceAlias",
      "match": "Umb.Workspace.Document"
    }
  ]
}

Multiple Conditions (AND Logic)

const manifest = {
  type: 'workspaceAction',
  alias: 'My.WorkspaceAction',
  name: 'My Action',
  conditions: [
    {
      alias: 'Umb.Condition.SectionAlias',
      match: 'Umb.Section.Content'
    },
    {
      alias: 'Umb.Condition.WorkspaceAlias',
      match: 'Umb.Workspace.Document'
    },
    {
      alias: 'Umb.Condition.WorkspaceContentTypeAlias',
      match: 'blogPost'
    }
  ]
};

User Permission Condition

{
  "type": "entityAction",
  "alias": "My.DeleteAction",
  "name": "Delete Document",
  "conditions": [
    {
      "alias": "Umb.Condition.UserPermission.Document",
      "match": "Umb.UserPermission.Document.Delete"
    }
  ]
}

Section User Permission

{
  "type": "dashboard",
  "alias": "My.AdminDashboard",
  "name": "Admin Dashboard",
  "conditions": [
    {
      "alias": "Umb.Condition.SectionUserPermission",
      "match": "Umb.Section.Settings"
    }
  ]
}

Workspace Entity Type

{
  "type": "workspaceView",
  "alias": "My.View",
  "name": "My View",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceEntityType",
      "match": "document"
    }
  ]
}

Content Type Condition

{
  "type": "workspaceView",
  "alias": "My.BlogView",
  "name": "Blog Post View",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceContentTypeAlias",
      "match": "blogPost"
    }
  ]
}

Workspace Has Collection

{
  "type": "workspaceAction",
  "alias": "My.CollectionAction",
  "name": "Collection Action",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceHasCollection",
      "match": true
    }
  ]
}

Custom Condition Implementation

import { UmbConditionBase } from '@umbraco-cms/backoffice/extension-api';
import { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class MyCustomCondition extends UmbConditionBase<MyConditionConfig> {
  constructor(host: UmbControllerHost, args: MyConditionConfig) {
    super(host, args);

    // Observe some context or state
    this.consumeContext(SOME_CONTEXT, (context) => {
      this.observe(context.someObservable, (value) => {
        // Update permitted state based on value
        this.permitted = value === this.args.expectedValue;
      });
    });
  }
}

interface MyConditionConfig {
  expectedValue: string;
}

Register Custom Condition

export const manifests = [
  {
    type: 'condition',
    name: 'My Custom Condition',
    alias: 'My.Condition.Custom',
    api: MyCustomCondition,
  },
];

Use Custom Condition

{
  "type": "dashboard",
  "alias": "My.Dashboard",
  "name": "My Dashboard",
  "conditions": [
    {
      "alias": "My.Condition.Custom",
      "expectedValue": "someValue"
    }
  ]
}

Built-in Conditions

Section Conditions:

Umb.Condition.SectionAlias - Match current section
Umb.Condition.SectionUserPermission - User has section access

Workspace Conditions:

Umb.Condition.WorkspaceAlias - Match current workspace
Umb.Condition.WorkspaceEntityType - Match entity type (document, media, etc.)
Umb.Condition.WorkspaceContentTypeAlias - Match content type alias
Umb.Condition.WorkspaceHasCollection - Workspace has collection

User Permission Conditions:

Umb.Condition.UserPermission.Document - Document permissions
Umb.Condition.CurrentUser.IsAdmin - User is admin
Umb.Condition.CurrentUser.GroupId - User in specific group

Key Concepts

Gatekeeping: Conditions control extension availability

AND Logic: All conditions must pass for extension to appear

Match Property: Value to compare against (alias, entity type, etc.)

Permitted State: Boolean indicating if condition passes

Custom Conditions: Implement UmbConditionBase and set this.permitted

Use Cases:

Show dashboard only in Content section
Display action only for specific content types
Restrict features to admin users
Show view only in document workspace
Enable actions based on permissions

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.

umbraco-conditions