Alert dialog - Cognite Docs

In progress | Storybook link coming soon

When to use

Alert dialogs are considered high-emphasis communication as these messages are more noticeable and disruptive. They should be used sparingly and only when user input is urgent or requires immediate action.

Critical decisions: Confirming delete actions, submitting sensitive info.
Important messages: System errors, security warnings that require user attention or input to dismiss.

When to use something else

Non-blocking messages: Use a Sonner, Banner, or Alert (depending on context) if you need to show messages or alerts that don’t require immediate action.
In-line validation: Use an Input’s inline validation to provide contextual and immediate feedback to the user.
Focused tasks: Short forms, template selection, and quick settings adjustments. Use a Dialog.
Secondary content: Image zoom-ins, detailed information, video playback. Use a Dialog.

Alert dialog vs Dialog

A Dialog is a flexible, interactive modal used for routine tasks like editing forms, viewing detailed information, or completing multi-step workflows. An Alert dialog is an interruptive, high-priority modal specifically designed for critical or destructive decisions (such as deleting data), halting user workflow until an explicit choice is made.

Feature / behavior	Dialog	Alert dialog
Primary purpose	Standard workflows, forms, settings, and detail views	Destructive actions, system warnings, and data loss prevention
ARIA role	`role="dialog"`	`role="alertdialog"`
Dismiss on overlay click	Yes (dismissible by clicking outside)	No (requires explicit button interaction)
Dismiss on Escape key	Yes (closes immediately)	Configurable; typically disabled for critical actions
Initial focus target	First interactive element or dialog container	Safest element (typically the Cancel button)
Top-right close icon (X)	Standard; recommended	Intentionally omitted to prevent accidental triggers
Required actions	Flexible (Save, Submit, custom, or none)	Mandatory explicit pair (`AlertDialogCancel` and `AlertDialogAction`)
Screen reader behavior	Announces dialog title and context	Interrupts speech queue to immediately announce alert and urgent message
Interaction flow	Asynchronous (user can exit at any point)	Synchronous checkpoint (must resolve before proceeding)

Behavior

Alert dialogs should be used to confirm a destructive action or a warning or issue that requires immediate action.
Alert dialogs should not disappear or close until the user has confirmed the action or dismissed the dialog.
Alert dialogs should not be used to confirm an action that the user can resolve in a separate context.

Often used with

Primary and secondary Button in the footer; optional Separator when body scrolls; copy kept short—defer forms to Dialog when possible.

Accessibility

Focus trap and placement: Move initial focus to the least destructive action (e.g., “Cancel”) upon open. Trap keyboard focus inside the overlay until dismissed.
Semantics: Apply role="alertdialog" and link the container to title/description nodes using aria-labelledby and aria-describedby.
Keyboard dismissal: Allow the Escape key to close non-critical dialogs, and ensure focus returns to the triggering element upon closure.

​When to use

​When to use something else

​Alert dialog vs Dialog

​Behavior