Axon 911 Frontend DocsAxon 911 Frontend Docs
Axon 911 Frontend Docs
    Loading navigation…
U
User
Switch to light mode
  1. Blocks
  2. Required Action Dialog
  3. Usage

Required Action Dialog

Usage

RequiredActionDialog is the pinnacle of the urgency ladder: the most interruptive surface the design system has. It asks the person to take a required action before they continue. Use it only when all three hold:
  • The condition is the highest severity (S5).
  • The person cannot safely continue until they act.
  • The notification's type declares that it requires action. Examples: an upgrade prompt, a severe system error, a forced logout.
Ordinary notifications never open a dialog. Only the pinnacle tier does, and only for an S5 notification whose type declares that it requires action, and only for a person the router counts as working (router PRD A8). A dialog opens on arrival for that person, waits during an interaction, and a wallboard never opens one. A dialog carries no status action: its actions are plain commands.
Behavior: Dismissible or Forced
behavior is RequiredActionDialogBehavior.Dismissible unless you set it.
  • Dismissible (the default). The dialog has a header close control (name it with the required closeLabel) and Escape closes it, as every dialog does. A backdrop press never does. Closing it does not complete the action: the block reports the close to the host through onOpenChange(false, details), with the reason close-press for the control and close-request for Escape. open stays the host's. The action is still required, so the host, or the router that raised the dialog, decides when it comes back, like an update the person postponed. The block has no timer and no snooze.
  • Forced (the rare exception). No close control, no Escape, no backdrop dismissal, and only the host closes it. Use it only for a condition the person cannot safely continue past, such as a forced logout, in a flow that owns that decision. Routed notification dialogs are Dismissible. Forced rejects closeLabel and onOpenChange in its types.
Dismissible is the right choice unless there is no safe way to continue. Never use Forced to make an ordinary notification harder to ignore. The host owns closing a forced dialog, so it must always give the person a way to complete the required action.
When not to use it
Everything else. A failure the person can ignore, a risk that needs attention, a recoverable problem, a confirmation and a routine result are lower rows of the urgency ladder:
  • A page-level message that stays until fixed: Banner with BannerType.Critical.
  • A transient result: a toast, with ToastSeverity.Error only for a failure that needs action.
  • A message the person can come back to: the notification inbox.
  • Asking before an action: ConfirmDialog.
Open state
open is required and the host owns it in both behaviors. There is no defaultOpen and no trigger. A close request is reported, never applied: the host sets open to false when the condition is resolved or the dialog is set aside, and focus returns to where it was before the dialog opened.
Actions
primaryAction is required in both behaviors. It takes initial focus and sits last, at the inline end. secondaryActions are optional and sit before it, in order. Each action is { label, onPress, intent? }.
  • Name the action ("Sign in again", "Update now"), never "OK" or "Continue".
  • There is no cancel action. If the person has a real second choice (contact support, see what changed), it is a secondary action that does something.
  • RequiredActionIntent.Destructive is for an action that is itself irreversible (discarding unsaved work to sign out). A severe condition is not a reason: a forced logout that only ends the session is the default intent.
Async actions
Return a promise from onPress:
  • The pressed Button shows its loading state (it is loading, not just disabled) and the other actions are disabled.
  • The dialog stays open until the host sets open to false.
  • A rejection ends the pending state and is not rethrown. Report the failure from the handler.
Error code
Pass errorCode (a DisplayValue) with errorCodeLabels to show a code the person can read to support, with a copy button. The labels are required with the code and rejected without it.
Rules
  • Never open another dialog over this one. The top layer stacks in opening order, so a second dialog would take focus and Escape. Put the next step in the dialog's own actions, or close it first.
  • Never put a Popover or a Menu in it, or beside its content. A popup that portals to body is inert behind a modal dialog and cannot be clicked. The block has no slot, so there is nothing to put one in.
  • Write the copy for the situation: what happened, then what the person must do. Which flows use the dialog, their triggers and their copy belong to the flows.
Styles
Load @prepared911/ui/styles.css once at the document root.
Previous
Confirm Dialog / Accessibility
Next
Required Action Dialog / API and Development
On this page
Behavior: Dismissible or Forced
When not to use it
Open state
Actions
Async actions
Error code
Rules
Styles