There are two parts to creating a custom modal:

• First, you need to create a modal element which you need to register in the extension registry.

• Second, you need to create and export a modal token.

Create a modal token

A modal token is a string that identifies a modal. This is the modal extension alias. It is used to open a modal and is also to set default options for the modal. It should also have a unique alias to avoid conflicts with other modals.

A modal token is a generic type that takes two type arguments. The first is the type of the data that is passed to the modal when it is opened. The second is the type of the value that is returned when the modal is closed.

Create a modal element

A modal element is a web component that is used to render the modal. It should implement the UmbModalExtensionElement interface. The modal context is injected into the element when the modal is opened in the modalContext property. The modal context is used to close the modal, update the value and submit the modal.

Additionally, the modal element can see its data parameters through the modalContext property. In this example, the modal data is of type MyModalData and the modal value is of type MyModalValue. The modal context is of type UmbModalContext<MyModalData, MyModalValue>. We are using the data to render a headline and the value to update the value and submit the modal.

Register in the extension registry

The modal element needs to be registered in the extension registry. This is done by defining the modal in the manifest file. The element property should point to the file that contains the modal element.

Open the modal

To open the modal, you need to consume the UmbModalManagerContext and then use the modal manager context to open a modal. This example shows how to consume the Modal Manager Context:

You can register modals with a route, making it possible to link directly to that specific modal. This also means the user can navigate back and forth in the browser history.

A modal can be registered via the UmbModalRouteRegistrationController. The registration accepts a modal token (or extension alias).

The registration holds an instance of its UmbModalHandler when the modal is active. The modal registration accepts 4 different callbacks:

• onSetup - called when the modal is opened

• onSubmit - called when the modal is submitted

• onReject - called when the modal is rejected

• observeRouteBuilder - called when the modal route changes. Use the given route builder to build a route to open the modal

Additional features of the route Registration:

• Adds unique parts to the path.

• A modal registered in a dashboard can be setup in few steps

• A modal registered in a property editor needs to become specific for the property and the variant of that property.

• Builds some data for the setup.

• Rejects a modal by returning false in setup.

• Uses a parameter as part of the setup to determine the data going to the modal.

Modal registration for UI as part of a Property Editor

When configuring a routed modal from a Property Editor, it's important to be aware of some facts. Those facts are that the Property Editor shares the same URL path as other Property Editors. This means we need to ensure the registration is unique so it doesn't collide with other Property Editors. To do so we will make use of the Property Alias and the Variant ID.

Generate the URL to a Modal Route Registration

The Modal registration has an option to retrieve a URL Builder. This is a function that can be used to generate a URL to a modal:

The modalLink from above could look like this: /umbraco/backoffice/my/location/modal/Our.Modal.SomethingPicker/my-input-alias

Notice the Property Editor registration will add the property alias and variant ID to the URL, so it becomes:

/umbraco/backoffice/my/location/modal/Our.Modal.SomethingPicker/my-property-alias/en-us/my-input-alias

This example shows how to open a confirm dialog. The UMB_CONFIRM_MODAL is a token that represents the confirm dialog. The open method takes the token and an object with the data for the confirm dialog. The onSubmit method returns a promise that resolves when the user confirms the dialog and rejects when the user cancels the dialog.

The confirm modal itself is built-in and does not need to be registered in the extension registry.

The modal token describes the options that you can pass to the modal. The confirm modal token has the following properties:

• headline - The headline of the modal.

• content - The content of the modal, which can be a TemplateResult or a string.

• color - (Optional) The color of the modal. This can be positive or danger.

• confirmLabel - (Optional) The label of the confirm button.

Basic Usage

import { html, LitElement, customElement } from "@umbraco-cms/backoffice/external/lit";
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { UMB_MODAL_MANAGER_CONTEXT, UMB_CONFIRM_MODAL } from '@umbraco-cms/backoffice/modal';

@customElement('my-element')
export class MyElement extends UmbElementMixin(LitElement) {
    #modalManagerContext?: typeof UMB_MODAL_MANAGER_CONTEXT.TYPE;

    constructor() {
        super();
        this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (instance) => {
            this.#modalManagerContext = instance;
        });
    }

    #onRequestDisable() {
        const modalContext = this.#modalManagerContext?.open(
            this, UMB_CONFIRM_MODAL,
            {
                data: {
                    headline: `${this.localize.term("actions_disable")}`,
                    content: `${this.localize.term(
                        "defaultdialogs_confirmdisable"
                    )}`,
                    color: "danger",
                    confirmLabel: "Disable",
                }
            }
        );
        modalContext
            ?.onSubmit()
            .then(() => {
                console.log("User has approved");
            })
            .catch(() => {
                console.log("User has rejected");
            });
    }

    render() {
        return html`<uui-button
                            look="primary"
                            color="danger"
                            @click=${this.#onRequestDisable}
                            label=${this.localize.term("actions_disable")}></uui-button>`;
    }
}

Modal Types

The Dialog modal appears in the middle of the screen. and the Sidebar Modal slide in from the right.

Modal Token

For type safety, we recommend that you use Modal Tokens. The Modal Token binds the Modal Type with a Modal Data Type and a Modal Result Type.

This can also come with defaults, for example, settings for the modal type and size.

This is an example of a Modal Token declaration:

import { UmbModalToken } from "@umbraco-cms/backoffice/modal";

export type OurSomethingPickerModalData = {
    // We do not have any data to parse for this example
};

export type OurSomethingPickerModalValue = {
    key: string;
};

export const MY_SOMETHING_PICKER_MODAL = new UmbModalToken<
    OurSomethingPickerModalData,
    OurSomethingPickerModalValue
>("Our.Modal.SomethingPicker", {
    modal: {
        type: "sidebar",
        size: "small",
    },
});

Make a custom Modal Element

To create your own modal, read the Implementing a Custom Modal article before proceeding with this article.

Basic Usage

Consume the UMB_MODAL_MANAGER_CONTEXT and then use the modal manager context to open a modal. This example shows how to consume the Modal Manager Context:

import { LitElement } from "@umbraco-cms/backoffice/external/lit";
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import {
    UMB_MODAL_MANAGER_CONTEXT,
} from "@umbraco-cms/backoffice/modal";

export class MyElement extends UmbElementMixin(LitElement) {
    #modalManagerContext?: typeof UMB_MODAL_MANAGER_CONTEXT.TYPE;

    constructor() {
        super();
        this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (instance) => {
            this.#modalManagerContext = instance;
            // modalManagerContext is now ready to be used.
        });
    }
}

Open a modal

A modal can be opened in two ways. Either you register the modal with a route or at runtime open the modal. The initial option allows users to deep-link to the modal, a potential preference in certain cases; otherwise, consider the latter.

Directly open a Modal

In this case, we use the Modal Token from above, this takes a key as its data. And if submitted then it returns the new key.

const modalContext = this.#modalManagerContext?.open(this, MY_SOMETHING_PICKER_MODAL, {
    value: {
        key: this.selectedKey,
    },
});

modalContext
    ?.onSubmit()
    .then((value) => {
        this.selectedKey = value.key;
    })
    .catch(() => undefined);

See the implementing a Confirm Dialog for a more concrete example.

Modal Route Registration

You can register modals with a route, making it possible to link directly to that specific modal. This also means the user can navigate back and forth in the browser history. This makes it an ideal solution for modals containing an editorial experience.

For a more concrete example, check out the Implementing a Confirm Dialog article.