Plugin modals API

api.ui.openModal(options) opens a trusted plugin workflow and returns a function that closes it.

type PluginModalOptions = {
  id?: string
  title: string
  description?: string
  size?: 'small' | 'medium' | 'large' | 'fullscreen'
  closeLabel?: string
  closeOnBackdrop?: boolean
  closeOnEscape?: boolean
  render: PluginModalRenderCallback
}

Defaults

Field	Default
id	A generated plugin modal ID
size	medium
closeLabel	Default localized close label
closeOnBackdrop	true
closeOnEscape	true

Render context

type PluginModalRenderContext = {
  id: string
  pluginId: string
  close: (reason?: PluginModalCloseReason) => void
}

The render callback receives an HTMLElement body container and the context. It can return cleanup for listeners, observers, timers, and rendered content.

Close reasons

type PluginModalCloseReason =
  | 'api'
  | 'close-button'
  | 'backdrop'
  | 'escape'
  | 'native'
  | 'plugin-dispose'
  | 'replaced'
  | 'render-error'

Only one plugin modal is active at a time. Opening another closes the current plugin modal with the replaced reason. Unregistering its owner closes it with plugin-dispose.

Events and diagnostics

modal:opened contains id, pluginId, title, and size. modal:closed adds the close reason. The active public snapshot contains id, pluginId, title, size, and openedAt.

See Open a plugin modal for a complete example.