umbraco-property-editor-ui

Umbraco Property Editor UI

What is it?

A Property Editor UI is the visual component that users interact with in the Umbraco backoffice to input and manage content data. It's one half of a property editor - the UI (client-side TypeScript) pairs with a Schema (server-side C#) that defines data storage.

Documentation

Always fetch the latest docs before implementing:

• Main docs: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/property-editors
• Tutorial: https://docs.umbraco.com/umbraco-cms/extend-your-project/tutorials/creating-a-property-editor
• Configuration: https://docs.umbraco.com/umbraco-cms/extend-your-project/tutorials/creating-a-property-editor/adding-configuration-to-a-property-editor
• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• Extension Registry: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

Reference Example

The Umbraco source includes a working example:

Location: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/property-editor/

This example demonstrates a complete property editor UI implementation with configuration. Study this for production patterns.

Related Foundation Skills

• Umbraco Element: When implementing the UI element with UmbElementMixin

  • Reference skill: umbraco-umbraco-element

• State Management: When implementing reactive value updates

  • Reference skill: umbraco-state-management

• Localization: When adding multi-language support to labels

  • Reference skill: umbraco-localization

Workflow

1. Fetch docs - Use WebFetch on the URLs above
2. Ask questions - What data type? What UI components needed? Configuration options?
3. Generate files - Create manifest + element based on latest docs
4. Explain - Show what was created and how to test

Minimal Examples

Manifest (umbraco-package.json)

WARNING: The propertyEditorSchemaAlias below uses Umbraco.Plain.String, a built-in schema. If you use a custom alias like MyPackage.CustomSchema, you MUST have a corresponding C# DataEditor on the server or you'll get a 404 error when creating a Data Type.

{
  "name": "My Property Editor",
  "extensions": [
    {
      "type": "propertyEditorUi",
      "alias": "My.PropertyEditorUi.Custom",
      "name": "My Custom Editor",
      "element": "/App_Plugins/MyEditor/editor.js",
      "elementName": "my-editor-ui",
      "meta": {
        "label": "My Custom Editor",
        "icon": "icon-edit",
        "group": "common",
        "propertyEditorSchemaAlias": "Umbraco.Plain.String"
      }
    }
  ]
}

Element Implementation (editor.ts)

import { LitElement, html, css, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { UmbChangeEvent } from '@umbraco-cms/backoffice/event';
import type { UmbPropertyEditorUiElement } from '@umbraco-cms/backoffice/property-editor';

@customElement('my-editor-ui')
export default class MyEditorElement extends UmbElementMixin(LitElement) implements UmbPropertyEditorUiElement {
  @property({ type: String })
  public value = '';

  #onChange(e: Event) {
    const input = e.target as HTMLInputElement;
    this.value = input.value;
    this.dispatchEvent(new UmbChangeEvent());
  }

  render() {
    return html`
      <uui-input
        .value=${this.value || ''}
        @change=${this.#onChange}
      ></uui-input>
    `;
  }

  static styles = css`
    :host {
      display: block;
    }
  `;
}

declare global {
  interface HTMLElementTagNameMap {
    'my-editor-ui': MyEditorElement;
  }
}

With Configuration

import type { UmbPropertyEditorConfigCollection } from '@umbraco-cms/backoffice/property-editor';

@customElement('my-editor-ui')
export default class MyEditorElement extends UmbElementMixin(LitElement) implements UmbPropertyEditorUiElement {
  @property({ type: String })
  public value = '';

  @state()
  private _maxChars?: number;

  @state()
  private _placeholder?: string;

  @property({ attribute: false })
  public set config(config: UmbPropertyEditorConfigCollection) {
    this._maxChars = config.getValueByAlias('maxChars');
    this._placeholder = config.getValueByAlias('placeholder');
  }

  render() {
    return html`
      <uui-input
        .value=${this.value || ''}
        .placeholder=${this._placeholder || ''}
        .maxlength=${this._maxChars}
        @change=${this.#onChange}
      ></uui-input>
    `;
  }
}

Configuration in Manifest

{
  "type": "propertyEditorUi",
  "alias": "My.PropertyEditorUi.Custom",
  "name": "My Custom Editor",
  "element": "/App_Plugins/MyEditor/editor.js",
  "elementName": "my-editor-ui",
  "meta": {
    "label": "My Custom Editor",
    "propertyEditorSchemaAlias": "Umbraco.Plain.String",
    "settings": {
      "properties": [
        {
          "alias": "maxChars",
          "label": "Maximum Characters",
          "propertyEditorUiAlias": "Umb.PropertyEditorUi.Integer"
        },
        {
          "alias": "placeholder",
          "label": "Placeholder Text",
          "propertyEditorUiAlias": "Umb.PropertyEditorUi.TextBox"
        }
      ],
      "defaultData": [
        { "alias": "maxChars", "value": 100 }
      ]
    }
  }
}

Built-in Schema Aliases (Safe Defaults)

The propertyEditorSchemaAlias in your manifest must reference a schema that exists on the server:

Part	Location	Language
Property Editor UI	Client	TypeScript
Property Editor Schema	Server	C#

• Built-in schemas (listed below) are always available - use these for simple storage needs
• Custom schemas require a C# DataEditor class - only needed for custom validation/conversion

These built-in schemas are always available:

Schema Alias	Stores	Use Case
Umbraco.Plain.String	string	Simple text values
Umbraco.Integer	int	Numbers, ratings, counts
Umbraco.Decimal	decimal	Prices, percentages
Umbraco.Plain.Json	object	Complex JSON data
Umbraco.DateTime	DateTime	Dates and times
Umbraco.TrueFalse	bool	Toggles, checkboxes
Umbraco.TextBox	string	Textbox with validation
Umbraco.TextArea	string	Multi-line text

Troubleshooting

See TROUBLESHOOTING.md for common issues including:

• 404 errors when creating Data Types
• Values not persisting with Umbraco.Plain.Json

See UUI-GOTCHAS.md for UUI component issues (combobox, input, etc.).

---

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