umbraco-umbraco-element

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/extend-your-project/backoffice-extensions/foundation/umbraco-element
• Context API: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/context-api
• Controllers: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/umbraco-controller
• Localization: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/localization
• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

Workflow

1. Fetch docs - Use WebFetch on the URLs above
2. Ask questions - Using Lit? Need contexts? Need localization? Which base class?
3. Generate files - Create element using UmbElementMixin or UmbLitElement based on latest docs
4. 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.