A dialog interrupts the current task to request a decision or present a short, focused interaction. Use one when the interruption helps people understand a consequence or complete a necessary step. Keep routine information and recoverable feedback in the page when possible. A common action with a reliable undo path usually needs less interruption than an uncommon, irreversible operation; choose confirmation according to the consequence.

Choose the presentation

These components have different content, sizing, and dismissal APIs. Popover keeps content associated with its trigger. Review its focus and dismissal behavior separately from Dialog's modal contract. Choose the component that supports the task before specifying its appearance. A longer workflow may be easier to understand as a dedicated page.

Describe one decision

Give the dialog a title that identifies the decision. Add a description when it explains information the title and actions cannot convey. For a consequential action, describe the affected content and whether the result can be undone.

For example, use “Delete saved filter?” with “This removes the filter from your account. Your records will remain.” Offer “Cancel” and “Delete filter.” The application must implement the stated outcome; the destructive role only identifies the action's intent.

Label actions with their outcome. Provide a clear way to cancel when cancellation is meaningful. Avoid adding multiple unrelated decisions to one dialog.

Follow the interaction sequence

1. Open the dialog from an identifiable action or application event.
2. Move attention into the dialog while preserving the previous context.
3. Let the person choose an action or an available dismissal path.
4. Close the dialog and communicate the result in the relevant part of the interface.

In this confirmation sequence, Cancel is the first focusable element. After Delete filter starts the operation, focus returns to the previous context and application-owned feedback communicates progress. Closure alone does not mean the filter was deleted.

Avoid using another modal as the ordinary next step. A sequence of stacked dialogs makes it harder to understand which task is active and what cancellation will do.

Use the supported action contract

Liquidify Dialog accepts actions with stable IDs, labels, optional roles, and callbacks. An enabled action runs its callback, then requests closure as soon as that callback returns. If the callback is asynchronous, returning its promise is enough to trigger that closure request; Dialog does not wait for the operation to finish. A thrown synchronous error interrupts this sequence; handle failures in the application rather than using an exception to control dismissal.

For a confirmation, handle the selected operation in application code and show its progress or outcome in the appropriate context. For an editor that must remain open during validation or a failed save, choose a composition whose documented behavior supports that flow.

Control presentation through open and onOpenChange when the application owns it. The application must accept the requested state change for a controlled dialog to close. Keeping open true does not prevent an action callback from running again; disable the relevant actions while work is pending and handle duplicate requests in the application.

States and recovery

Keep confirmation and execution separate. After a person confirms an asynchronous operation, the dialog can close while the application displays progress beside the affected item. Prevent duplicate work there, preserve the item until its outcome is known, and show a retry action if the operation fails. Do not report success when the callback merely starts a request.

Cancellation before confirmation should leave the underlying data unchanged. Dismissing a dialog after work has started does not cancel that work automatically. If cancellation is supported, the application must define whether it stops the request, reverses a completed change, or only dismisses the presentation. See Loading and Notifications for subsequent feedback.

Dismissal and focus

The installed Dialog uses a modal overlay that moves focus to the first focusable element, or the panel when none is available. It cycles Tab and Shift+Tab within the panel and makes background content inert while open. On close, it attempts to restore the element that held focus before opening. This is normally the trigger when opened from the keyboard. If that element is removed by the operation, the application needs to provide an appropriate next focus destination, such as the remaining list or the page reached after ending use.

Escape and a scrim interaction request dismissal by default. These paths request an open-state change; they do not invoke an action merely because it has the cancel role. Put cleanup shared by all dismissal paths in the application's open-state handling. Setting dismissible to false disables those paths; enabled action buttons still provide their action and closure behavior. Always leave a usable way to finish or cancel the interaction.

Dialog exposes role="dialog" and aria-modal="true", and connects its title and body through accessible naming and description attributes. Keep the title specific and the description concise. These attributes do not establish accessibility compliance: review the actual announcements, focus sequence, and dismissal paths with a keyboard and a screen reader in the application.

For a destructive confirmation without controls in its body, put an enabled safe action such as “Cancel” first when it should receive initial focus. A focusable control earlier in the body receives focus before the actions. Review the complete content order; the action role does not reorder the buttons or select a safer initial focus target automatically.

Content and layout

Keep essential information visible without requiring people to inspect the background. Leave room for translated labels, enlarged text, and validation messages where the chosen composition supports them.

Use the component's supported size and surface options. Dialog renders two actions in a row and one or three or more actions in a stack, preserving their declaration order. Review that order in each composition rather than assuming automatic platform-specific placement. Avoid placing another glass container around the dialog simply to increase its visual emphasis.

API and examples

Read the Dialog API and examples for the installed configuration. Its generated accessibility copy still includes generic advice against containing focus; for this modal component, follow the verified focus sequence above. Compare Alert, Sheet, and Popover before choosing a different presentation.

Further reading

• Apple: Modality
• Apple: Alerts
• Apple: Sheets
• Apple: Popovers