Open a plugin modal

Use api.ui.openModal() when trusted plugin code needs a workflow that cannot be represented by a structured campaign. The configurator owns dialog behavior; the plugin renders the modal body.

Open from an outlet action

api.ui.mount('page-header:actions', (container) => {
  const button = document.createElement('button')
  button.type = 'button'
  button.textContent = 'Get help'

  let closeModal: (() => void) | undefined

  const openHelp = () => {
    closeModal?.()
    closeModal = api.ui.openModal({
      id: 'customer-shopping-help',
      title: 'Shopping help',
      description: 'Choose how you want to start.',
      size: 'medium',
      closeLabel: 'Close shopping help',
      render(modalContainer, context) {
        const chooseVehicle = document.createElement('button')
        chooseVehicle.type = 'button'
        chooseVehicle.textContent = 'Choose my vehicle'

        const startSearch = () => {
          api.commands.openSearchByVehicle()
          context.close('api')
        }

        chooseVehicle.addEventListener('click', startSearch)
        modalContainer.appendChild(chooseVehicle)

        return () => {
          chooseVehicle.removeEventListener('click', startSearch)
          chooseVehicle.remove()
        }
      },
    })
  }

  button.addEventListener('click', openHelp)
  container.appendChild(button)

  return () => {
    closeModal?.()
    button.removeEventListener('click', openHelp)
    button.remove()
  }
})

Modal options

Field	Purpose
id	Stable identifier used by diagnostics and events.
title	Visible dialog title.
description	Optional supporting text.
size	small, medium, large, or fullscreen.
closeLabel	Accessible label for the close control.
closeOnBackdrop	Whether a backdrop click closes the modal.
closeOnEscape	Whether Escape closes the modal.
render	Callback that renders the body and optionally returns cleanup.

Only one plugin modal is active at a time. Opening another replaces the current plugin modal.

Use marketing campaigns for event-triggered promotional prompts with structured creative and frequency rules.