Custom Modals

You can register custom modal dialogs and control them with the standard element APIs (openElement, closeElement, disableElements). Modals render through the CustomModal component and the ModalContainer host.

UI API

UI.addCustomModal(options)

Register a custom modal dialog.

/**
 * @method UI.addCustomModal
 * @param {object} options
 * @param {string} options.dataElement               Unique name of the custom modal.
 * @param {boolean} [options.disableBackdropClick=false] Disable closing on outside click.
 * @param {boolean} [options.disableEscapeKeyDown=false] Disable closing on Escape.
 * @param {UI.renderCustomModal} options.render      Function rendering modal contents (optional).
 * @param {object} options.header                    { title, className, style, children }
 * @param {object} options.body                      { title, className, style, children }
 * @param {object} options.footer                    { title, className, style, children }
 */
UI.addCustomModal({
  dataElement: 'myModal',
  disableBackdropClick: false,
  disableEscapeKeyDown: false,
  header: { title: 'My Modal' },
  body:   { children: [/* … */] },
  footer: { children: [/* … */] },
});

Registering a modal with the same dataElement as an existing one replaces it. Internally calls store.addCustomModal(customModal), appending to the customModals list in the viewer store.

Controlling a modal

Once registered, the modal is controlled like any other element using its dataElement:

UI.openElement('myModal');      // show
UI.closeElement('myModal');     // hide
UI.disableElements(['myModal']); // remove entirely
UI.isElementOpen('myModal');    // => boolean

Structure

A modal is divided into three optional sections — header, body, footer — each accepting { title, className, style, children }. You can also supply a render function (UI.renderCustomModal) that returns an HTMLElement for full custom content.

Section field	Purpose
title	Section title text.
className	Custom class(es) applied to the section.
style	Inline style object.
children	Array of child descriptors / elements.

Examples

A confirmation modal

UI.addCustomModal({
  dataElement: 'confirmModal',
  disableBackdropClick: true,
  header: { title: 'Please confirm' },
  body:   { title: 'Are you sure you want to continue?' },
  footer: {
    children: [
      { type: 'actionButton', label: 'Cancel', onClick: () => UI.closeElement('confirmModal') },
      { type: 'actionButton', label: 'OK',     onClick: () => { /* … */ UI.closeElement('confirmModal'); } },
    ],
  },
});

UI.openElement('confirmModal');

A modal with a custom render function

UI.addCustomModal({
  dataElement: 'customRenderModal',
  render: () => {
    const el = document.createElement('div');
    el.innerHTML = '<h3>Custom</h3><p>Rendered by a function.</p>';
    return el;
  },
});
UI.openElement('customRenderModal');

Internal plumbing

• The viewer store holds a customModals[] list; addCustomModal appends/replaces by dataElement.
• The CustomModal component (lazy-loaded via LazyLoadComponents) renders each registered modal.
• ModalContainer hosts the modal stack and handles backdrop-click / Escape-key dismissal (subject to the disableBackdropClick / disableEscapeKeyDown flags).
• Visibility is driven by the same activeElements / disabledElements maps as built-in dialogs.

Related

• Show / Hide Elements — open/close/disable APIs.
• Components — the CustomModal / ModalContainer components.
• API Reference