> ## 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. export const CodeLivePreview = ({code, children, height, removePadding = false, mode = 'shadow'}) => { const previewRef = useRef(null); const BEEQ_ESM_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js'; const BEEQ_CSS_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.css'; const BEEQ_ICONS_URL = 'https://esm.sh/@beeq/core/dist/beeq/svg'; const ensureParentBeeqRuntime = () => { if (document.querySelector('script[data-beeq-parent-runtime]')) return; const script = document.createElement('script'); script.type = 'module'; script.src = BEEQ_ESM_URL; script.dataset.beeqParentRuntime = BEEQ_ICONS_URL; document.head.appendChild(script); }; const executeSnippetScripts = (root, runtimeWindow, previewRootArg, skipAttr) => { root.querySelectorAll('script').forEach(oldScript => { if (skipAttr && oldScript.hasAttribute(skipAttr)) return; if (oldScript.src) { const newScript = runtimeWindow.document.createElement('script'); newScript.src = oldScript.src; oldScript.replaceWith(newScript); return; } runtimeWindow.Function('previewRoot', oldScript.textContent || '')(previewRootArg); oldScript.remove(); }); }; const syncIframeMode = iframeDoc => { const root = document.documentElement; const explicitMode = root.getAttribute('bq-mode'); const isDark = root.classList.contains('dark'); const resolvedMode = explicitMode || (isDark ? 'dark' : 'light'); iframeDoc.documentElement.setAttribute('bq-mode', resolvedMode); iframeDoc.body.setAttribute('bq-mode', resolvedMode); }; useEffect(() => { if (mode === 'shadow') ensureParentBeeqRuntime(); }, [mode]); useEffect(() => { const container = previewRef.current; if (!container) return; if (removePadding) container.style.padding = '0'; container.innerHTML = ''; if (mode === 'iframe') { const iframe = document.createElement('iframe'); iframe.className = 'preview-iframe'; iframe.style.width = '100%'; iframe.style.border = '0'; iframe.style.display = 'block'; iframe.style.minHeight = height ?? '0px'; iframe.setAttribute('title', 'Live code preview'); iframe.setAttribute('loading', 'lazy'); iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin'); container.appendChild(iframe); const iframeDoc = iframe.contentDocument; const iframeWin = iframe.contentWindow; if (!iframeDoc || !iframeWin) return; iframeDoc.open(); iframeDoc.write(['', '', '', ' ', ' ', ' ', ` `, ` `, '', '', code, '', ''].join('\n')); iframeDoc.close(); syncIframeMode(iframeDoc); const modeObserver = new MutationObserver(() => syncIframeMode(iframeDoc)); modeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'bq-mode'] }); executeSnippetScripts(iframeDoc, iframeWin, iframeDoc, 'data-beeq-iframe-runtime'); return () => modeObserver.disconnect(); } const shadowRoot = container.shadowRoot ?? container.attachShadow({ mode: 'open' }); if (!shadowRoot.adoptedStyleSheets.length) { const fixSheet = new CSSStyleSheet(); fixSheet.replaceSync(` bq-dropdown::part(panel), bq-panel::part(panel), bq-select::part(panel), bq-date-picker::part(panel) { z-index: 9999; } bq-tooltip::part(panel) { position: absolute; } `); shadowRoot.adoptedStyleSheets = [fixSheet]; } shadowRoot.innerHTML = [``, code].join(''); executeSnippetScripts(shadowRoot, window, shadowRoot); return undefined; }, [code, mode, height]); return
{}
{} {children &&
{children}
}
; }; export const CardTile = ({title, href, imageLightSrc, imageDarkSrc, children, enableImgZoom}) => { if (!href) { return
{imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; } return {imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; }; BEEQ Dialog component overview BEEQ 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. 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 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 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 ## Patterns Use the default dialog to present important information, gather input, or confirm actions in a temporary overlay. Disable the close button, backdrop dismissal, and `Esc` handling when an irreversible action requires an explicit choice. Use two buttons when the dialog needs a clear primary decision alongside a secondary escape path such as cancel or dismiss. Use three buttons only when users genuinely need a primary, secondary, and tertiary choice within the same decision flow. ## Anatomy Dialog anatomy 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. Write titles that tell people what decision or task the dialog is about, not only that something happened. Keep the footer focused. One primary action and one secondary action is usually enough for quick decisions. Use a dialog only when people must pause to confirm, review, or complete a short task before continuing. Make button labels describe the outcome, especially in destructive or irreversible flows. Reserve locked-down confirmation dialogs for actions that carry real risk, such as deletion or deactivation. 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. h5 { display: flex; font-weight: 700; align-items: center; gap: var(--bq-spacing-s); } .dialog-footer { display: flex; gap: var(--bq-spacing-xs); } Open dialog
Title

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.

Button Button Button
`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Open dialog
Title

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.

Button Button Button
``` ```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 ( <> dialogRef.current?.show()}>Open dialog
Title

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.

Button Button Button
); } ``` ```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: ` Open dialog
Title

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.

Button Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` 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 ### Highlight footer Use `footer-appearance="highlight"` when emphasis on the footer is important. h5 { display: flex; font-weight: 700; align-items: center; gap: var(--bq-spacing-s); } .dialog-footer { display: flex; gap: var(--bq-spacing-xs); } Open dialog
Title

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.

Button Button Button
`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Open dialog
Title

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.

Button Button Button
``` ```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 ( <> dialogRef.current?.show()}>Open dialog
Title

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.

Button Button Button
); } ``` ```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: ` Open dialog
Title

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.

Button Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### No footer This kind of dialog omits the footer section for situations where a minimal and distraction-free interface is preferred. h5 { display: flex; font-weight: 700; align-items: center; gap: var(--bq-spacing-s); } Open dialog
Title

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.

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

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.

 ``` ```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 ( <> dialogRef.current?.show()}>Open dialog
Title

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.

 ); } ``` ```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: ` Open dialog
Title

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.

 `, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### No backdrop Use `disable-backdrop` when you want to allow users to focus on the dialog content without an overlay. :host { position: relative !important; z-index: 12 !important; } h5 { display: flex; font-weight: 700; align-items: center; gap: var(--bq-spacing-s); } .dialog-footer { display: flex; gap: var(--bq-spacing-xs); } Open dialog
Title

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.

Button Button Button
`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Open dialog
Title

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.

Button Button Button
``` ```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 ( <> dialogRef.current?.show()}>Open dialog
Title

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.

Button Button Button
); } ``` ```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: ` Open dialog
Title

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.

Button Button Button
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Confirm dialog Use this variant to confirm irreversible actions with clear messaging and focused choices. h5 { display: flex; font-weight: 700; align-items: center; gap: var(--bq-spacing-s); } .dialog-caption { color: var(--bq-text--secondary); font-size: var(--bq-font-size--s); } .dialog-footer { display: flex; gap: var(--bq-spacing-xs); } Deactivate account
Deactivate account

Are you sure you want to deactivate your account? All of your data will be permanently removed.

This action cannot be undone
Cancel Yes, deactivate
`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Deactivate account
Deactivate account

Are you sure you want to deactivate your account? All of your data will be permanently removed.

This action cannot be undone
Cancel Yes, deactivate
``` ```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 ( <> dialogRef.current?.show()}> Deactivate account
Deactivate account

Are you sure you want to deactivate your account? All of your data will be permanently removed.

This action cannot be undone
dialogRef.current?.cancel()}> Cancel dialogRef.current?.hide()}> Yes, deactivate
); } ``` ```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: ` Deactivate account
Deactivate account

Are you sure you want to deactivate your account? All of your data will be permanently removed.

This action cannot be undone
Cancel Yes, deactivate
`, }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Make the title and primary action work together so the outcome of the dialog is unmistakable. Don't Do not use vague titles or button labels that force people to infer the meaning of the decision. Do Use concise content and keep the structure easy to scan with a clear title, short body copy, and focused actions. Don't Do not duplicate actions in the footer or offer too many equally weighted choices. Do Match the dialog size to the amount of content so the layout feels intentional and easy to scan. 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. Do Keep a reliable dismissal path available, especially in confirmation flows where people may need to back out safely. Don't Do not disable the close button, backdrop dismissal, and Esc 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 `` 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 `` element automatically traps keyboard focus within the dialog while it is open 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 should clearly describe the decision, task, or message. * **Include an explicit dismissal path** — if you hide the close button or disable outside dismissal, provide a clear cancel or close action in the footer. * **Preserve keyboard expectations** — keep Esc 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** — removing the backdrop changes the modal emphasis, so make sure the surrounding page does not compete visually with the dialog content. ## 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"` | ### Events | Event | Description | Type | | -------------- | ---------------------------------------------- | ------------------- | | `bqAfterClose` | Fired after the dialog finishes closing | `CustomEvent` | | `bqAfterOpen` | Fired after the dialog finishes opening | `CustomEvent` | | `bqCancel` | Fired when the dialog is canceled or dismissed | `CustomEvent` | | `bqClose` | Fired when the dialog is about to close | `CustomEvent` | | `bqOpen` | Fired when the dialog is about to open | `CustomEvent` | ### Methods | Method | Description | Returns | | ---------- | ------------------------------- | --------------- | | `cancel()` | Dismisses or cancels the dialog | `Promise` | | `hide()` | Closes the dialog | `Promise` | | `show()` | Opens the dialog | `Promise` | ### 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 `
` 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 `` 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 | 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--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` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Explore dialog examples and states in Storybook View the component source on GitHub