Implement property editor UIs in Umbraco backoffice using official docs
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.
Always fetch the latest docs before implementing:
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.
Umbraco Element: When implementing the UI element with UmbElementMixin
umbraco-umbraco-elementState Management: When implementing reactive value updates
umbraco-state-managementLocalization: When adding multi-language support to labels
umbraco-localizationWARNING: The
propertyEditorSchemaAliasbelow usesUmbraco.Plain.String, a built-in schema. If you use a custom alias likeMyPackage.CustomSchema, you MUST have a corresponding C#DataEditoron 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"
}
}
]
}
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;
}
}
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>
`;
}
}
{
"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 }
]
}
}
}
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# |
DataEditor class - only needed for custom validation/conversionThese 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 |
See TROUBLESHOOTING.md for common issues including:
Umbraco.Plain.JsonSee UUI-GOTCHAS.md for UUI component issues (combobox, input, etc.).
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.