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/customizing/property-editors

• Tutorial: https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor

• Configuration: https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor/adding-configuration-to-a-property-editor

• Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation

• Extension Registry: https://docs.umbraco.com/umbraco-cms/customizing/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

• Fetch docs - Use WebFetch on the URLs above

• Ask questions - What data type? What UI components needed? Configuration options?

• Generate files - Create manifest + element based on latest docs

• 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.