Modal dialogs

Describes basic methods for using modals dialogs within an extension.

The AEM instance (host instance) provides an API for showing modal dialogs with custom UI defined by an extension. These modals can be triggered by a click on the button or other events. Modal API is defined in the modal namespace.

Content of the modal is rendered in an iframe with source defined by extension. Before showing modal you should create a page which renders Modal UI. This UI should use Adobe Spectrum UI library to provide consistent experience to the user.

An example of opening and closing a modal

In order to display modal dialog extension must call showUrl method in modal namespace.

Copy
import { register } from "@adobe/uix-guest";

const guestConnection = await register({
    id: "my.company.extension-with-modal",
    {
        //...
    }
});

guestConnection.host.modal.showUrl({
    title: "Extension Modal",
    url: "/index.html#/modal", // absolute or relative path
})
Copied to your clipboard
import { register } from "@adobe/uix-guest";

const guestConnection = await register({
    id: "my.company.extension-with-modal",
    {
        //...
    }
});

guestConnection.host.modal.showUrl({
    title: "Extension Modal",
    url: "/index.html#/modal", // absolute or relative path
})

Modal may be closed by close method

Copy
import { attach } from "@adobe/uix-guest";

const guestConnection = await attach({
    id: "my.company.extension-with-modal"
});

guestConnection.host.modal.close();
Copied to your clipboard
import { attach } from "@adobe/uix-guest";

const guestConnection = await attach({
    id: "my.company.extension-with-modal"
});

guestConnection.host.modal.close();

API Reference

Modal API Request Object

The modal.showUrl and modalInstance.set methods accept a ModalRequest object.

Modal API

The modal API is available to all extensions at the host.modal property.

modal.showUrl(request: ModalRequest): Promise<ModalInstanceApi>

Any guest's GuestServer may call modal.showUrl to open a modal dialog. The provided ModalRequest object must have a url of the page to be displayed inside the modal. Typically this is another page or route in the calling extension app.

If another modal is displaying and it belongs to a different extension, it rejects.

modal.close(): Promise<void>

Close the current modal. If the current modal doesn't belong to the calling extension, it rejects.

Modal Instance API

This API is returned to the GuestServer and also shared with the modal that loads inside the frame. A GuestServer loaded in a modal must call set instead of showUrl.

modal.set(request: ModalRequest): Promise<void>

Modify the currently displaying modal. GuestUI frames running inside the modal may call this method to change their dimensions, or to change other parameters.

modal.close(): Promise<void>

Close the modal.

Resizing

When height and/or width are set to "auto", the modal will attempt to resize whenever the displayed page changes size. This is to make the content of the iframe behave, as much as possible, like they're part of the content flow of the host application.

• ⚠️ Resizes are detected every 100ms.
• ⚠️ Height is limited to between 20% and 75% of page height, and width is similarly limited.
• ⚠️ If the page sets certain kinds of relative dimensions on its body elements, such as 99vh or 101vmin, it can cause slow expansion or contraction of the displayed frame. Those measurements change as the outer document resizes the inner document, which triggers a loop. Remedy this by using other units to define the outside of your app.

Last updated 12/5/2023

Was this helpful?

Yes

No