Skip to content

Show dialogs and notifications

Use api.modal when Phials must pause for a decision, text input, a choice, or acknowledgement. Use api.notify when work can continue and a short status message is enough.

Choose the interaction by the user’s next required action:

User need API
Approve or cancel one consequential action api.modal.confirm()
Enter a short text value api.modal.prompt()
Choose one of several explicit outcomes api.modal.choose()
Read required information before continuing api.modal.alert()
Notice brief non-blocking status api.notify.info(), success(), warning(), or error()

This hub covers the reusable interaction contracts:

  1. Confirm consequential actions immediately before destructive or difficult-to-reverse work.
  2. Ask for text or a choice, validate the result, and treat cancellation as normal.
  3. Show alerts and notifications according to whether acknowledgement is required.

Keep feedback proportional

Do not show a dialog merely because an action exists. Frequent, safe, immediately reversible actions should usually happen directly. Place a decision-point warning immediately before a genuinely consequential action and make its effect clear before the user chooses.

Do not show a success notification when the completed result is already unmistakable. Repeated activation, refresh, selection, and navigation messages create noise and can hide feedback that matters.

Dialogs and notifications are not logging systems. Keep user-facing text concise, specific to the outcome, and free of raw errors, credentials, file contents, or implementation details.

ModalAPI and NotifyAPI are available on the permission-gated PluginAPI; they require no manifest permission. For exact signatures, see ModalAPI and NotifyAPI.

This article includes AI-assisted content.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.