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
Anatomy
| 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.Choose the right level of interruption
Use a dialog only when people must pause to confirm, review, or complete a short task before continuing.
Write clear actions
Make button labels describe the outcome, especially in destructive or irreversible flows.
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 thedefault dialog when you want to overlay content for focused user engagement.
Options
Highlight footer
Usefooter-appearance="highlight" when emphasis on the footer is important.
No footer
This kind of dialog omits the footer section for situations where a minimal and distraction-free interface is preferred.No backdrop
Usedisable-backdrop when you want to allow users to focus on the dialog content without an overlay.
Confirm dialog
Use this variant to confirm irreversible actions with clear messaging and focused choices.Best practices
DoMake the title and primary action work together so the outcome of the dialog is unmistakable.
Don’tDo not use vague titles or button labels that force people to infer the meaning of the decision.
DoUse concise content and keep the structure easy to scan with a clear title, short body copy, and focused actions.
Don’tDo not duplicate actions in the footer or offer too many equally weighted choices.
DoMatch the dialog size to the amount of content so the layout feels intentional and easy to scan.
Don’tDo not force long forms, dense tables, or multi-step workflows into a dialog that needs more room than the pattern is meant to provide.
DoKeep a reliable dismissal path available, especially in confirmation flows where people may need to back out safely.
Don’tDo 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"andaria-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 witharia-hidden="true". - Built-in focus management — the native
<dialog>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
titleslot 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-backdropcarefully — 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<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
Resources
Interactive playground
Explore dialog examples and states in Storybook
Source code
View the component source on GitHub