> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dialog

> A Modal interrupts the main workflow to capture user attention. It requires users to interact with it before they can return to the main screen.

## Dialog

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-dialog--docs)

### When to use

* Critical decisions: Confirming delete actions, submitting sensitive info.
* Focused tasks: Short forms, template selection and quick settings adjustments.
* Secondary content: Image zoom-ins, detailed information, video playback.

### When to use something else

* Non-blocking messages that don't require immediate action: use [Sonner](/aura-design-system/primitives/sonner), [Banner](/aura-design-system/primitives/banner-alert), or [Alert](/aura-design-system/primitives/alert) (context-dependent).
* Important messages requiring immediate attention or blocking confirmation: use [Alert dialog](/aura-design-system/primitives/alert-dialog).
* Comparative workflows: use a drawer or side panel if the user must compare information without losing surrounding context.
* Complex or multi-step flows: use a dedicated page or wizard if the input is too heavy for a modal.
* No need to interrupt flow: use inline patterns such as [Accordion](/aura-design-system/primitives/accordion) or [Collapsible](/aura-design-system/primitives/collapsible).

### Dos and don'ts

* Do ensure users can easily dismiss the Dialog. Always include a cancel Button and close icon Button.
* Do trap focus within the Dialog for accessibility. Users should not be able to interact with the background content.
* Do include top and bottom Separators only if the content within the Dialog is scrollable.
* Do maintain the default center placement for all Dialogs. Alternative placements should be avoided unless there is a specific, justified use case.
* Do use a transparent overlay background behind the Dialog.
* Don't interrupt the user unnecessarily - only use Dialogs when it's important to interrupt.
* Don't change the position of the primary call to action. It should always be positioned furthest right.
* Don't stack multiple Dialogs or nest them.
* Don't use a Dialog size that's larger than necessary. There should not be a ton of white space around form or text elements.

### Behavior

* Modal variant blocks interaction with the page behind it until dismissed; focus is trapped inside the dialog while open.
* Escape and an explicit dismiss control (cancel, close) should return focus to a sensible element (typically the trigger).
* Only one modal [Dialog](/aura-design-system/primitives/dialog) should stack at a time; do not nest modals.

### Often used with

* Footer [Button](/aura-design-system/primitives/button)s (primary right); [Separator](/aura-design-system/primitives/separator) for scrollable bodies; form fields ([Input](/aura-design-system/primitives/input), [Select](/aura-design-system/primitives/select), [Textarea](/aura-design-system/primitives/textarea), etc.); optional inner [Tabs](/aura-design-system/primitives/tabs) for rare complex modals.