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

# Dialog

> Dialogs present focused content or decisions that temporarily interrupt the current flow until the user responds or dismisses them.

![BEEQ Dialog component overview](https://mintcdn.com/beeq/nN2FF5Iq6pY7AHlL/components/images/dialog/dialog-overview-light.svg?fit=max\&auto=format\&n=nN2FF5Iq6pY7AHlL\&q=85\&s=5c3ed0ae8ac27e33a7822d212e23a7c4)

Dialog component overview

Dialogs keep people in context while they respond to important information, confirm an action, or complete a short focused task. Use them sparingly, only when the interruption is justified.

> [!NOTE]
>
> Keep dialog content concise and purposeful. Always provide a clear way to dismiss the dialog, such as a close button, a cancel action, or both.

## When to use

> [card]
>
> Use dialogs when
>
> * The user must acknowledge or confirm something before continuing
> * A short task or decision should stay in the current page context
> * The content is important enough to temporarily interrupt the flow

> [card]
>
> Do not use dialogs when
>
> * The content can live inline without blocking the current task
> * The interaction is long, complex, or better suited to a full page
> * The interruption would add friction without adding clarity

> [!TIP]
>
> Choose [`bq-drawer`](https://www.beeq.design/components/drawer) instead of `bq-dialog` when users need a larger side panel with richer or longer content while keeping the page visible, and [`bq-tooltip`](https://www.beeq.design/components/tooltip) when the content is a short, non-essential hint that needs no response.

## Patterns

## Standard dialog

Use the default dialog to present important information, gather input, or confirm actions in a temporary overlay.

## Confirmation dialog

Disable the close button, backdrop dismissal, and `Esc` handling when an irreversible action requires an explicit choice.

## Two actions

Use two buttons when the dialog needs a clear primary decision alongside a secondary escape path such as cancel or dismiss.

## Three actions

Use three buttons only when users genuinely need a primary, secondary, and tertiary choice within the same decision flow.

## Anatomy

![Dialog anatomy](https://mintcdn.com/beeq/nN2FF5Iq6pY7AHlL/components/images/dialog/dialog-anatomy-light.svg?fit=max\&auto=format\&n=nN2FF5Iq6pY7AHlL\&q=85\&s=f8bf1043162a2852d23233c1d5449bbe)

Dialog anatomy

A dialog is composed of a container, a header with icon and title, a close control, a body area, and optional footer actions.

| Part | Element | Description |
| - | - | - |
| **1** | Container | The outer dialog surface that groups all content and actions |
| **2** | Header: Icon | A contextual icon that helps communicate the nature of the dialog at a glance |
| **3** | Header: Title | The primary heading that explains the purpose of the dialog |
| **4** | Close | The dismiss control shown in the header when the close button is enabled |
| **5** | Body (description) | The main content area for supporting text, guidance, or short task content |
| **6** | Footer: CTA buttons | The action area for the dialog's primary and secondary decisions |

## Design guidelines

Use dialogs only when the interruption is worth the attention shift and the next step is clear.

![Keep the title action-oriented](https://www.beeq.design/components/images/dialog/dialog-title-guidance-light.svg)
![Keep the title action-oriented](https://www.beeq.design/components/images/dialog/dialog-title-guidance-dark.svg)

## Keep the title action-oriented

Write titles that tell people what decision or task the dialog is about, not only that something happened.

![Limit the number of actions](https://www.beeq.design/components/images/dialog/dialog-actions-guidance-light.svg)
![Limit the number of actions](https://www.beeq.design/components/images/dialog/dialog-actions-guidance-dark.svg)

## Limit the number of actions

Keep the footer focused. One primary action and one secondary action is usually enough for quick decisions.

**1. Choose the right level of interruption**

Use a dialog only when people must pause to confirm, review, or complete a short task before continuing.

**2. Write clear actions**

Make button labels describe the outcome, especially in destructive or irreversible flows.

**3. Use confirm dialogs carefully**

Reserve locked-down confirmation dialogs for actions that carry real risk, such as deletion or deactivation.

> [!NOTE]
>
> If the content grows beyond a short decision or focused task, move the interaction to an inline flow or a dedicated page instead of expanding the dialog.

## Usage

### Default

Use the `default` dialog when you want to overlay content for focused user engagement.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-button>Open dialog</bq-button>

<bq-dialog>
  <h5 slot="title">
    <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
    Title
  </h5>

  <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

  <div class="dialog-footer" slot="footer">
    <bq-button appearance="link">Button</bq-button>
    <bq-button variant="ghost">Button</bq-button>
    <bq-button variant="standard">Button</bq-button>
  </div>
</bq-dialog>

<script>
  const openDialogBtn = document.querySelector("bq-button");
  const dialogElem = document.querySelector("bq-dialog");

  openDialogBtn.addEventListener("bqClick", () => {
    dialogElem.open = true;
  });
</script>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useRef } from "react";
import { BqButton, BqDialog, BqIcon } from "@beeq/react";

export function DefaultDialog() {
  const dialogRef = useRef(null);

  return (
    <>
      <BqButton onBqClick={() => dialogRef.current?.show()}>Open dialog</BqButton>

      <BqDialog ref={dialogRef}>
        <h5 slot="title">
          <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
          Title
        </h5>

        <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

        <div className="dialog-footer" slot="footer">
          <BqButton appearance="link">Button</BqButton>
          <BqButton variant="ghost">Button</BqButton>
          <BqButton variant="standard">Button</BqButton>
        </div>
      </BqDialog>
    </>
  );
}
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqDialog, BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqButton, BqDialog, BqIcon],
  template: `
    <bq-button (bqClick)="dialog.show()">Open dialog</bq-button>

    <bq-dialog #dialog>
      <h5 slot="title">
        <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
        Title
      </h5>

      <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

      <div class="dialog-footer" slot="footer">
        <bq-button appearance="link">Button</bq-button>
        <bq-button variant="ghost">Button</bq-button>
        <bq-button variant="standard">Button</bq-button>
      </div>
    </bq-dialog>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { ref } from "vue";
import { BqButton, BqDialog, BqIcon } from "@beeq/vue";

const dialogRef = ref(null);
</script>

<template>
  <BqButton @bqClick="dialogRef?.show()">Open dialog</BqButton>

  <BqDialog ref="dialogRef">
    <h5 slot="title">
      <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
      Title
    </h5>

    <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

    <div class="dialog-footer" slot="footer">
      <BqButton appearance="link">Button</BqButton>
      <BqButton variant="ghost">Button</BqButton>
      <BqButton variant="standard">Button</BqButton>
    </div>
  </BqDialog>
</template>
```

> [!TIP]
>
> The dialog closes via its built-in close button (✕) or by clicking the backdrop. To control visibility programmatically, call the `show()`, `hide()`, and `cancel()` methods, or use the `open` attribute for static snapshots.

## Options

**Allowed `size` values:** `small`, `medium` (default), `large`. Any other value logs a warning and falls back to `large`.

**Allowed `footer-appearance` values:** `standard` (default), `highlight`. Any other value logs a warning and falls back to `standard`.

**Allowed `border` values:** `none`, `xs2`, `xs`, `s`, `m` (default), `l`, `full`.

### Highlight footer

Use `footer-appearance="highlight"` when emphasis on the footer is important.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-button>Open dialog</bq-button>

<bq-dialog footer-appearance="highlight">
  <h5 slot="title">
    <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
    Title
  </h5>

  <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

  <div class="dialog-footer" slot="footer">
    <bq-button appearance="link">Button</bq-button>
    <bq-button variant="ghost">Button</bq-button>
    <bq-button variant="standard">Button</bq-button>
  </div>
</bq-dialog>

<script>
  const openDialogBtn = document.querySelector("bq-button");
  const dialogElem = document.querySelector("bq-dialog");

  openDialogBtn.addEventListener("bqClick", () => {
    dialogElem.open = true;
  });
</script>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useRef } from "react";
import { BqButton, BqDialog, BqIcon } from "@beeq/react";

export function HighlightFooterDialog() {
  const dialogRef = useRef(null);

  return (
    <>
      <BqButton onBqClick={() => dialogRef.current?.show()}>Open dialog</BqButton>

      <BqDialog ref={dialogRef} footerAppearance="highlight">
        <h5 slot="title">
          <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
          Title
        </h5>

        <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

        <div className="dialog-footer" slot="footer">
          <BqButton appearance="link">Button</BqButton>
          <BqButton variant="ghost">Button</BqButton>
          <BqButton variant="standard">Button</BqButton>
        </div>
      </BqDialog>
    </>
  );
}
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqDialog, BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqButton, BqDialog, BqIcon],
  template: `
    <bq-button (bqClick)="dialog.show()">Open dialog</bq-button>

    <bq-dialog #dialog footer-appearance="highlight">
      <h5 slot="title">
        <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
        Title
      </h5>

      <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

      <div class="dialog-footer" slot="footer">
        <bq-button appearance="link">Button</bq-button>
        <bq-button variant="ghost">Button</bq-button>
        <bq-button variant="standard">Button</bq-button>
      </div>
    </bq-dialog>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { ref } from "vue";
import { BqButton, BqDialog, BqIcon } from "@beeq/vue";

const dialogRef = ref(null);
</script>

<template>
  <BqButton @bqClick="dialogRef?.show()">Open dialog</BqButton>

  <BqDialog ref="dialogRef" footerAppearance="highlight">
    <h5 slot="title">
      <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
      Title
    </h5>

    <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

    <div class="dialog-footer" slot="footer">
      <BqButton appearance="link">Button</BqButton>
      <BqButton variant="ghost">Button</BqButton>
      <BqButton variant="standard">Button</BqButton>
    </div>
  </BqDialog>
</template>
```

### No footer

This kind of dialog omits the footer section for situations where a minimal and distraction-free interface is preferred.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-button>Open dialog</bq-button>

<bq-dialog>
  <h5 slot="title">
    <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
    Title
  </h5>

  <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>
</bq-dialog>

<script>
  const openDialogBtn = document.querySelector("bq-button");
  const dialogElem = document.querySelector("bq-dialog");

  openDialogBtn.addEventListener("bqClick", () => {
    dialogElem.open = true;
  });
</script>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useRef } from "react";
import { BqButton, BqDialog, BqIcon } from "@beeq/react";

export function NoFooterDialog() {
  const dialogRef = useRef(null);

  return (
    <>
      <BqButton onBqClick={() => dialogRef.current?.show()}>Open dialog</BqButton>

      <BqDialog ref={dialogRef}>
        <h5 slot="title">
          <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
          Title
        </h5>

        <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>
      </BqDialog>
    </>
  );
}
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqDialog, BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqButton, BqDialog, BqIcon],
  template: `
    <bq-button (bqClick)="dialog.show()">Open dialog</bq-button>

    <bq-dialog #dialog>
      <h5 slot="title">
        <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
        Title
      </h5>

      <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>
    </bq-dialog>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { ref } from "vue";
import { BqButton, BqDialog, BqIcon } from "@beeq/vue";

const dialogRef = ref(null);
</script>

<template>
  <BqButton @bqClick="dialogRef?.show()">Open dialog</BqButton>

  <BqDialog ref="dialogRef">
    <h5 slot="title">
      <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
      Title
    </h5>

    <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>
  </BqDialog>
</template>
```

### No backdrop

Use `disable-backdrop` when you want to allow users to focus on the dialog content without an overlay.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-button>Open dialog</bq-button>

<bq-dialog disable-backdrop>
  <h5 slot="title">
    <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
    Title
  </h5>

  <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

  <div class="dialog-footer" slot="footer">
    <bq-button appearance="link">Button</bq-button>
    <bq-button variant="ghost">Button</bq-button>
    <bq-button variant="standard">Button</bq-button>
  </div>
</bq-dialog>

<script>
  const openDialogBtn = document.querySelector("bq-button");
  const dialogElem = document.querySelector("bq-dialog");

  openDialogBtn.addEventListener("bqClick", () => {
    dialogElem.open = true;
  });
</script>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useRef } from "react";
import { BqButton, BqDialog, BqIcon } from "@beeq/react";

export function NoBackdropDialog() {
  const dialogRef = useRef(null);

  return (
    <>
      <BqButton onBqClick={() => dialogRef.current?.show()}>Open dialog</BqButton>

      <BqDialog ref={dialogRef} disableBackdrop>
        <h5 slot="title">
          <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
          Title
        </h5>

        <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

        <div className="dialog-footer" slot="footer">
          <BqButton appearance="link">Button</BqButton>
          <BqButton variant="ghost">Button</BqButton>
          <BqButton variant="standard">Button</BqButton>
        </div>
      </BqDialog>
    </>
  );
}
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqDialog, BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqButton, BqDialog, BqIcon],
  template: `
    <bq-button (bqClick)="dialog.show()">Open dialog</bq-button>

    <bq-dialog #dialog disable-backdrop>
      <h5 slot="title">
        <bq-icon name="info" size="30" color="text--accent" role="img" title="Info"></bq-icon>
        Title
      </h5>

      <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

      <div class="dialog-footer" slot="footer">
        <bq-button appearance="link">Button</bq-button>
        <bq-button variant="ghost">Button</bq-button>
        <bq-button variant="standard">Button</bq-button>
      </div>
    </bq-dialog>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { ref } from "vue";
import { BqButton, BqDialog, BqIcon } from "@beeq/vue";

const dialogRef = ref(null);
</script>

<template>
  <BqButton @bqClick="dialogRef?.show()">Open dialog</BqButton>

  <BqDialog ref="dialogRef" disableBackdrop>
    <h5 slot="title">
      <BqIcon name="info" size="30" color="text--accent" role="img" title="Info" />
      Title
    </h5>

    <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>

    <div class="dialog-footer" slot="footer">
      <BqButton appearance="link">Button</BqButton>
      <BqButton variant="ghost">Button</BqButton>
      <BqButton variant="standard">Button</BqButton>
    </div>
  </BqDialog>
</template>
```

### Confirm dialog

Use this variant to confirm irreversible actions with clear messaging and focused choices.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-button variant="ghost">Deactivate account</bq-button>

<bq-dialog
  disable-close-esc-keydown
  disable-close-click-outside
  hide-close-button
>
  <h5 slot="title">
    <bq-icon name="info" size="30" color="icon--danger" role="img" title="Danger"></bq-icon>
    Deactivate account
  </h5>

  <p>Are you sure you want to deactivate your account? All of your data will be permanently removed.</p>
  <span class="dialog-caption">This action cannot be undone</span>

  <div class="dialog-footer" slot="footer">
    <bq-button appearance="secondary">Cancel</bq-button>
    <bq-button variant="danger">Yes, deactivate</bq-button>
  </div>
</bq-dialog>

<script>
  const deactivateBtn = document.querySelector('bq-button[variant="ghost"]');
  const cancelBtn = document.querySelector('bq-button[appearance="secondary"]');
  const confirmBtn = document.querySelector('bq-button[variant="danger"]');
  const dialogElem = document.querySelector("bq-dialog");

  deactivateBtn.addEventListener("bqClick", () => {
    dialogElem.open = true;
  });

  cancelBtn.addEventListener("bqClick", () => {
    dialogElem.open = false;
  });

  confirmBtn.addEventListener("bqClick", () => {
    dialogElem.open = false;
  });
</script>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useRef } from "react";
import { BqButton, BqDialog, BqIcon } from "@beeq/react";

export function ConfirmDialog() {
  const dialogRef = useRef(null);

  return (
    <>
      <BqButton variant="ghost" onBqClick={() => dialogRef.current?.show()}>
        Deactivate account
      </BqButton>

      <BqDialog
        ref={dialogRef}
        disableCloseClickOutside
        disableCloseEscKeydown
        hideCloseButton
      >
        <h5 slot="title">
          <BqIcon name="info" size="30" color="icon--danger" role="img" title="Danger" />
          Deactivate account
        </h5>

        <p>Are you sure you want to deactivate your account? All of your data will be permanently removed.</p>
        <span className="dialog-caption">This action cannot be undone</span>

        <div className="dialog-footer" slot="footer">
          <BqButton appearance="secondary" onBqClick={() => dialogRef.current?.cancel()}>
            Cancel
          </BqButton>
          <BqButton variant="danger" onBqClick={() => dialogRef.current?.hide()}>
            Yes, deactivate
          </BqButton>
        </div>
      </BqDialog>
    </>
  );
}
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqDialog, BqIcon } from "@beeq/angular/standalone";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [BqButton, BqDialog, BqIcon],
  template: `
    <bq-button variant="ghost" (bqClick)="dialog.show()">Deactivate account</bq-button>

    <bq-dialog
      #dialog
      disable-close-click-outside
      disable-close-esc-keydown
      hide-close-button
    >
      <h5 slot="title">
        <bq-icon name="info" size="30" color="icon--danger" role="img" title="Danger"></bq-icon>
        Deactivate account
      </h5>

      <p>Are you sure you want to deactivate your account? All of your data will be permanently removed.</p>
      <span class="dialog-caption">This action cannot be undone</span>

      <div class="dialog-footer" slot="footer">
        <bq-button appearance="secondary" (bqClick)="dialog.cancel()">Cancel</bq-button>
        <bq-button variant="danger" (bqClick)="dialog.hide()">Yes, deactivate</bq-button>
      </div>
    </bq-dialog>
  `,
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { ref } from "vue";
import { BqButton, BqDialog, BqIcon } from "@beeq/vue";

const dialogRef = ref(null);
</script>

<template>
  <BqButton variant="ghost" @bqClick="dialogRef?.show()">Deactivate account</BqButton>

  <BqDialog
    ref="dialogRef"
    disableCloseClickOutside
    disableCloseEscKeydown
    hideCloseButton
  >
    <h5 slot="title">
      <BqIcon name="info" size="30" color="icon--danger" role="img" title="Danger" />
      Deactivate account
    </h5>

    <p>Are you sure you want to deactivate your account? All of your data will be permanently removed.</p>
    <span class="dialog-caption">This action cannot be undone</span>

    <div class="dialog-footer" slot="footer">
      <BqButton appearance="secondary" @bqClick="dialogRef?.cancel()">Cancel</BqButton>
      <BqButton variant="danger" @bqClick="dialogRef?.hide()">Yes, deactivate</BqButton>
    </div>
  </BqDialog>
</template>
```

## Best practices

> [card]
>
> Do
>
> Make the title and primary action work together so the outcome of the dialog is unmistakable.

> [card]
>
> Don't
>
> Do not use vague titles or button labels that force people to infer the meaning of the decision.

> [card]
>
> Do
>
> Use concise content and keep the structure easy to scan with a clear title, short body copy, and focused actions.

> [card]
>
> Don't
>
> Do not duplicate actions in the footer or offer too many equally weighted choices.

> [card]
>
> Do
>
> Match the dialog size to the amount of content so the layout feels intentional and easy to scan.

> [card]
>
> Don't
>
> Do not force long forms, dense tables, or multi-step workflows into a dialog that needs more room than the pattern is meant to provide.

> [card]
>
> Do
>
> Keep a reliable dismissal path available, especially in confirmation flows where people may need to back out safely.

> [card]
>
> Don't
>
> Do not disable the close button, backdrop dismissal, and <kbd>Esc</kbd> handling together unless the action carries real risk and the remaining actions are explicit.

## Accessibility

* **Built-in dialog semantics** — the component applies `aria-labelledby="bq-dialog--title"` and `aria-modal="true"` to the native `<dialog>` element, so assistive technology can identify it as a modal surface.
* **Built-in close control labeling** — when the default close button is shown, it includes an accessible `label="Close"` and a decorative close icon marked with `aria-hidden="true"`.
* **Built-in focus management** — the native `<dialog>` element automatically traps keyboard focus within the dialog while it is open (unless `disable-backdrop` is set, see below) and restores it to the previously focused element when the dialog closes.
* **Provide a meaningful title** — the content you place in the `title` slot becomes the dialog's accessible label, so it must clearly describe the decision, task, or message.
* **Include an explicit dismissal path** — if you hide the close button or disable outside dismissal, you must provide a clear cancel or close action in the footer.
* **Preserve keyboard expectations** — you should keep <kbd>Esc</kbd> enabled for dismissible dialogs unless there is a strong product reason to require an explicit choice.
* **Use precise action labels** — button text should describe the result of the action, especially in confirmations and destructive flows.
* **Use `disable-backdrop` carefully** — with `disable-backdrop` the dialog opens as a non-modal `<dialog>`, so focus is not trapped and the surrounding page stays reachable. The surrounding page should not compete visually with the dialog content.

### Keyboard interaction

| Key | Context | Action |
| - | - | - |
| `Tab` | Dialog open with the backdrop (modal) | Moves focus to the next focusable element inside the dialog (native modal `<dialog>` behavior) |
| `Shift` + `Tab` | Dialog open with the backdrop (modal) | Moves focus to the previous focusable element inside the dialog (native modal `<dialog>` behavior) |
| `Escape` | Dialog open, `disable-close-esc-keydown` not set | Cancels the dialog and emits `bqCancel` |
| `Escape` | Dialog open, `disable-close-esc-keydown` set | Does nothing; the dialog stays open |
| `Enter` or `Space` | Focus on the close button or a native `<button>` in the footer | Activates the focused button |

With `disable-backdrop` the dialog is non-modal, so `Tab` is not confined to the dialog.

### Rules

| Rule | Strength | Verified by |
| - | - | - |
| Put a title in the `title` slot that describes the decision, task, or message; it becomes the accessible label | MUST | manual: inspect the title as the dialog accessible name |
| Provide a clear cancel or close action in the footer when you hide the close button or disable outside dismissal | MUST | manual: check a visible cancel or close action when dismissal is restricted |
| Keep `Esc` enabled for dismissible dialogs | SHOULD | manual: press Escape in each dismissible dialog |
| Use action labels that describe the result, especially in confirmations and destructive flows | SHOULD | manual: read action labels without the surrounding body copy |
| Do not let the page compete visually with the dialog when `disable-backdrop` is set; the dialog is then non-modal and focus is not trapped | SHOULD NOT | manual: inspect focus and page contrast with the backdrop disabled |

## API reference

### Properties

| Property | Attribute | Description | Type | Default |
| - | - | - | - | - |
| `border` | `border` | Border radius of the dialog component | `"none" \| "xs2" \| "xs" \| "s" \| "m" \| "l" \| "full"` | `"m"` |
| `disableBackdrop` | `disable-backdrop` | If `true`, the backdrop overlay won't be shown when the dialog opens | `boolean` | `false` |
| `disableCloseClickOutside` | `disable-close-click-outside` | If `true`, the dialog will not close when clicking on the backdrop overlay | `boolean` | `false` |
| `disableCloseEscKeydown` | `disable-close-esc-keydown` | If `true`, the dialog will not close when the `Esc` key is pressed | `boolean` | `false` |
| `footerAppearance` | `footer-appearance` | The appearance of the footer | `"standard" \| "highlight"` | `"standard"` |
| `hideCloseButton` | `hide-close-button` | If `true`, hides the close button | `boolean` | `false` |
| `open` | `open` | If `true`, the dialog is shown as open | `boolean` | `false` |
| `size` | `size` | The size of the dialog | `"small" \| "medium" \| "large"` | `"medium"` |

### Invalid combinations

| Combination | Strength | Result |
| - | - | - |
| `hide-close-button` with a `button-close` slot | SHOULD NOT | The slotted button still renders because the prop only hides the default close button |

### Events

| Event | Description | Type |
| - | - | - |
| `bqAfterClose` | Fired after the dialog finishes closing | `CustomEvent<void>` |
| `bqAfterOpen` | Fired after the dialog finishes opening | `CustomEvent<void>` |
| `bqCancel` | Fired when the dialog is canceled or dismissed | `CustomEvent<void>` |
| `bqClose` | Fired when the dialog is about to close | `CustomEvent<void>` |
| `bqOpen` | Fired when the dialog is about to open | `CustomEvent<void>` |

### Methods

| Method | Description | Returns |
| - | - | - |
| `cancel()` | Dismisses or cancels the dialog | `Promise<void>` |
| `hide()` | Closes the dialog | `Promise<void>` |
| `show()` | Opens the dialog | `Promise<void>` |

### Slots

| Slot | Description |
| - | - |
| `title` | The title content of the dialog |
| *(default)* | The body content of the dialog |
| `footer` | The footer content of the dialog |
| `button-close` | Replaces the default close button content |

### Shadow parts

| Part | Description |
| - | - |
| `body` | The `<main>` section that holds the dialog body content |
| `button-close` | The button that closes the dialog on click |
| `content` | The container that holds the dialog title and body content |
| `dialog` | The native `<dialog>` wrapper inside the shadow DOM |
| `footer` | The footer that holds action content |
| `header` | The header that holds the title and close button |
| `title` | The element that wraps the title slot |

### CSS custom properties

**CSS variables**

| Variable | Description | Default |
| - | - | - |
| `--bq-dialog--background` | Dialog background color | `var(--bq-ui--primary)` |
| `--bq-dialog--background-backdrop` | Dialog backdrop background color | `var(--bq-background--overlay)` |
| `--bq-dialog--footer-background` | Dialog footer background color (`highlight` footer appearance) | `var(--bq-ui--alt)` |
| `--bq-dialog--text-color` | Dialog text color | `var(--bq-text--primary)` |
| `--bq-dialog--box-shadow` | Dialog box shadow | `var(--bq-box-shadow--l)` |
| `--bq-dialog--border-color` | Dialog border color | `transparent` |
| `--bq-dialog--border-style` | Dialog border style | `none` |
| `--bq-dialog--border-width` | Dialog border width | `unset` |
| `--bq-dialog--border-radius` | Dialog border radius | `var(--bq-radius--m)` |
| `--bq-dialog--padding` | Dialog padding | `var(--bq-spacing-l)` |
| `--bq-dialog--content-footer-gap` | Gap between the content and footer | `var(--bq-spacing-l)` |
| `--bq-dialog--title-body-gap` | Gap between the title and body | `var(--bq-spacing-s)` |
| `--bq-dialog--width-small` | Small dialog width | `320px` |
| `--bq-dialog--width-medium` | Medium dialog width | `480px` |
| `--bq-dialog--width-large` | Large dialog width | `640px` |
| `--bq-dialog-z-index` | Z-index used when the dialog is open | `10` |

> [!TIP]
>
> Learn more about [styling with shadow parts](https://www.beeq.design/guides/styles.md#component-shadow-dom-parts) and [CSS custom properties](https://www.beeq.design/guides/styles.md#global-css-custom-properties).

## Resources

> [card] [Interactive playground](https://storybook.beeq.design/?path=/story/components-dialog--default)
>
> Explore dialog examples and states in Storybook

> [card] [Source code](https://github.com/Endava/BEEQ/tree/main/packages/beeq/src/components/dialog)
>
> View the component source on GitHub


## Related topics

- [Changelog](https://www.beeq.design/releases/changelog.md)
- [Shadows](https://www.beeq.design/foundations/shadows.md)
- [Drawer](https://www.beeq.design/components/drawer.md)
- [React](https://www.beeq.design/guides/frameworks/react.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.