Skip to main content
BEEQ Dialog component overview

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

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

​
Design guidelines

Use dialogs only when the interruption is worth the attention shift and the next step is clear.
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.
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.
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

Use footer-appearance="highlight" when emphasis on the footer is important. This kind of dialog omits the footer section for situations where a minimal and distraction-free interface is preferred.

​
No backdrop

Use disable-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" 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 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

​
Events

​
Methods

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore dialog examples and states in Storybook

Source code

View the component source on GitHub