> ## 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.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Dialog

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

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

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--default" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--default&viewMode=story&globals=theme:light" title="Dialog default story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* 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](/cdf/aura/primitives/sonner), [Banner](/cdf/aura/primitives/banner), or [Alert](/cdf/aura/primitives/alert) (context-dependent).
* Important messages requiring immediate attention or blocking confirmation: use [Alert dialog](/cdf/aura/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 Dialog.
* No need to interrupt flow: use inline patterns such as [Accordion](/cdf/aura/primitives/accordion) or [Collapsible](/cdf/aura/primitives/collapsible).

## 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](/cdf/aura/primitives/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)                  |

## 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

* Dialog 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 Dialog should stack at a time; do not nest Dialogs.

## Often used with

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

## Accessibility

### Labeling and semantic markup

* **Keep DialogTitle rendered:** If your design omits a visual header, wrap `<DialogTitle>` in an accessibility class (e.g., `className="sr-only"`) rather than removing the element.
* **Provide or explicitly suppress DialogDescription:** If your dialog lacks body text, pass `aria-describedby={undefined}` to `<DialogContent>` to prevent browser console warnings and avoid broken ARIA references.
* **Label icon-only triggers:** If `<DialogTrigger>` wraps an icon-only button, ensure the button carries an explicit `aria-label` or accessible name.

### Focus and flow management

* **Override destructive initial focus:** By default, focus moves to the first focusable element inside the content. For dangerous actions, override initial focus to target the safest action (e.g., "Cancel") by calling `e.preventDefault()` inside `onOpenAutoFocus` and focusing the designated element.
* **Handle deleted triggers on close:** If closing the dialog deletes the original trigger element (e.g., deleting a table row item), focus will drop to `<body>`. Use `onCloseAutoFocus` to direct focus to a logical fallback, like the table container or next list item.
* **Form error focus:** If the dialog contains a form that fails validation, explicitly shift focus to the first invalid field or an error summary banner so screen reader users are notified instantly.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### With form

Use a Dialog with a form when you need a short, focused data-entry flow—such as creating a record or editing settings—without navigating away from the current page.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--with-form" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--with-form&viewMode=story&globals=theme:light" title="Dialog with form story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### No close button

Omit the close button on a Dialog only when dismissal must go through explicit actions—for example, a required choice or a multi-step flow where cancel is provided in the footer.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--no-close-button" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--no-close-button&viewMode=story&globals=theme:light" title="Dialog no close button story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Controlled

Use a controlled Dialog when open and closed state must follow application logic—for example, opening from multiple triggers or closing after an async action completes.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--controlled" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--controlled&viewMode=story&globals=theme:light" title="Dialog controlled story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Scrolling content

Use a Dialog with scrolling content when the body exceeds the viewport, adding Separators at the top and bottom of the scroll region so the header and footer stay fixed.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--scrolling-content" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--scrolling-content&viewMode=story&globals=theme:light" title="Dialog scrolling content story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Non modal

Use a non-modal Dialog when the user should interact with both the dialog and the page behind it—for example, a reference panel or inline assistant that does not block the main workflow.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--non-modal" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--non-modal&viewMode=story&globals=theme:light" title="Dialog non modal story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Nested

Avoid nesting Dialogs in production; this example exists to document stacking behavior when a secondary prompt must appear over an already-open Dialog.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--nested" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--nested&viewMode=story&globals=theme:light" title="Dialog nested story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Title only

Use a title-only Dialog for simple confirmations or alerts where a short heading is enough and no description paragraph is needed.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--title-only" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--title-only&viewMode=story&globals=theme:light" title="Dialog title only story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Long header

Use the long-header Dialog pattern when the title or description may wrap to multiple lines, ensuring the header layout stays readable without crowding the close control.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--long-header" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--long-header&viewMode=story&globals=theme:light" title="Dialog long header story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With back button

Add a back button to the Dialog header when the flow has a previous step—for example, moving from a list view to a detail form inside the same modal.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--with-back-button" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--with-back-button&viewMode=story&globals=theme:light" title="Dialog with back button story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Confirmation

Use a confirmation Dialog when the user must acknowledge an action before it proceeds—for example, saving changes or applying a bulk update.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--confirmation" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--confirmation&viewMode=story&globals=theme:light" title="Dialog confirmation story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Async action

Use an async-action Dialog when the primary button triggers a server request, disabling actions and showing progress until the operation finishes or fails.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-dialog--async-action" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-dialog--async-action&viewMode=story&globals=theme:light" title="Dialog async action story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>