Umbraco Element

What is it?

An Umbraco Element is a Web Component enhancement that simplifies integration with the Umbraco Backoffice through the UmbElementMixin. It provides methods to consume/provide contexts, observe states, handle localization, and host controllers. UmbElementMixin can be applied to any Web Component-compatible base class, while UmbLitElement is a convenience wrapper combining the mixin with Lit.

Documentation

Always fetch the latest docs before implementing:

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

• Context API: https://docs.umbraco.com/umbraco-cms/customizing/foundation/context-api

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

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

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

Workflow

• Fetch docs - Use WebFetch on the URLs above

• Ask questions - Using Lit? Need contexts? Need localization? Which base class?

• Generate files - Create element using UmbElementMixin or UmbLitElement based on latest docs

• Explain - Show what was created and how to use it

Minimal Examples

Using UmbLitElement (Recommended for Lit)

import { html, customElement } from '@umbraco-cms/backoffice/external/lit'; import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-element') export class MyElement extends UmbLitElement {

constructor() { super(); // Access built-in features this.consumeContext(MY_CONTEXT, (context) => { console.log('Context consumed:', context); }); }

render() { return html <div> <h3>${this.localize.term('myKey')}</h3> <p>My custom element</p> </div> ; } }

export default MyElement;

Using UmbElementMixin with HTMLElement

import { customElement } from '@umbraco-cms/backoffice/external/lit'; import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';

@customElement('my-element') export class MyElement extends UmbElementMixin(HTMLElement) {

constructor() { super(); this.consumeContext(MY_CONTEXT, (context) => { // Use context }); }

connectedCallback() { this.innerHTML = <div> <h3>My Element</h3> </div> ; } }

export default MyElement;

Using UmbElementMixin with UI Library Component

import { customElement } from '@umbraco-cms/backoffice/external/lit'; import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api'; import { UUIButtonElement } from '@umbraco-cms/backoffice/external/uui';

@customElement('my-custom-button') export class MyCustomButton extends UmbElementMixin(UUIButtonElement) {

constructor() { super(); // Now has access to Umbraco contexts and controllers } }

export default MyCustomButton;

Consuming Context

import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element'; import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

export class MyElement extends UmbLitElement {

#notificationContext?: typeof UMB_NOTIFICATION_CONTEXT.TYPE;

constructor() { super();

this.consumeContext(UMB_NOTIFICATION_CONTEXT, (context) => {
  this.#notificationContext = context;
});

}

showNotification() { this.#notificationContext?.peek('positive', { data: { headline: 'Success!', message: 'Operation completed' } }); } }

Using Observable State

import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element'; import { UMB_CURRENT_USER_CONTEXT } from '@umbraco-cms/backoffice/current-user';

export class MyElement extends UmbLitElement {

@state() private _userName?: string;

constructor() { super();

this.consumeContext(UMB_CURRENT_USER_CONTEXT, (context) => {
  this.observe(
    context.currentUser,
    (user) => {
      this._userName = user?.name;
    },
    '_userName'
  );
});

} }

Key Features

• consumeContext() - Subscribe to and consume contexts from parent elements

• provideContext() - Provide contexts to child elements

• observe() - Watch observable state and trigger reactive updates

• localize - Built-in localization controller for translations

• hostController() - Host and manage controllers within the element

UmbLitElement vs UmbElementMixin

Feature UmbLitElement UmbElementMixin

Base Pre-configured with Lit Apply to any base class

Usage extends UmbLitElement

extends UmbElementMixin(BaseClass)

Best for Lit-based components Custom base classes or UI library components

Features Same features Same features

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