Skip to content

Dialog ​

A modal dialog that blocks page interaction, traps focus, and dismisses on Escape. Built on the native <dialog> element for correct top-layer stacking and browser-managed accessibility semantics: no extra JS focus trapping or z-index juggling required.

Opening and Closing ​

Use open as the controlled state and update it in response to open-change. Use default-open only to initialize an uncontrolled dialog. Always include a clearly labelled cancel or close action in the footer slot so keyboard and pointer users can dismiss without relying solely on Escape. Give footer buttons a semantic emphasis (see Button emphasis); keep exactly one primary action per dialog. In development, a footer with more than one emphasis="primary" button logs a warning.

html
<ore-button id="open-btn">Open dialog</ore-button>

<ore-dialog label="Confirm action" dismissible id="dialog">
  <p>Are you sure you want to delete this item? This action cannot be undone.</p>
  <div slot="footer">
    <ore-button emphasis="cancel" id="cancel-btn">Cancel</ore-button>
    <ore-button emphasis="destructive" id="confirm-btn">Delete</ore-button>
  </div>
</ore-dialog>

<script type="module">
  import '@vielzeug/refine/dialog';
  import '@vielzeug/refine/button';

  const dialog = document.getElementById('dialog');

  document.getElementById('open-btn').addEventListener('click', () => {
    dialog.setAttribute('open', '');
  });
  document.getElementById('cancel-btn').addEventListener('click', () => {
    dialog.removeAttribute('open');
  });
  document.getElementById('confirm-btn').addEventListener('click', () => {
    dialog.removeAttribute('open');
    // handle confirm...
  });
</script>

Sizes ​

Full width

Keep dialog content focused: if a dialog requires scrolling, it is usually a sign the content should live on its own page.

Dismissible ​

Add dismissible to show a close (×) button in the top-right corner of the header. The close button carries aria-label="Close dialog" so screen readers announce it correctly.

Full width

Backdrop ​

Control the backdrop appearance with the backdrop attribute.

Full width

Elevation ​

Control the panel drop shadow with the elevation attribute. Defaults to xl.

Full width

Padding ​

Control the internal padding of the header, body, and footer with the padding attribute. Defaults to lg (24 px).

Full width

Custom Header ​

Use the header slot to replace the default title + close-button layout entirely.

Full width

Persistent (No Backdrop Close) ​

Set persistent to prevent the dialog from closing when the user clicks outside the panel. Useful for forms where accidental dismissal would lose data. When using persistent, always include an accessible way to dismiss: either dismissible or a clearly labelled cancel button in the footer. A dialog with no dismissal mechanism traps keyboard users indefinitely. Do not nest dialogs; stack them in a queue instead.

Full width

Listening to Events ​

Do not open dialogs without user intent (e.g. on page load): this is disorienting for screen reader users. Do not use dialogs for non-blocking notifications; use ore-alert or a toast component instead.

javascript
const dialog = document.querySelector('ore-dialog');

dialog.addEventListener('open-change', (e) => {
  console.log(e.detail.open ? 'Dialog opened because:' : 'Dialog closed because:', e.detail.reason);
});

dialog.addEventListener('close-request', (e) => {
  if (e.detail.reason === 'outside-click') {
    // Optional: block accidental outside dismiss in a critical flow.
    e.preventDefault();
  }
});

API Reference ​

Attributes ​

AttributeTypeDefaultDescription
openbooleanN/AControlled visibility
default-openbooleanfalseInitial visibility when open is not provided
labelstring''Dialog title shown in the header; used as aria-label
size'sm' | 'md' | 'lg' | 'xl' | 'full''md'Panel width preset
dismissiblebooleanfalseShow a close (×) button in the header
persistentbooleanfalsePrevent backdrop-click from closing the dialog
rounded'none' | 'sm' | 'md' | 'lg' | ... | 'full'N/AOverride the panel border radius
backdrop'blur' | 'opaque' | 'transparent''opaque'Backdrop style: dimming veil + blur, dimming veil only (default), or no overlay
elevation'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl''md'Panel drop shadow depth
padding'none' | 'sm' | 'md' | 'lg' | 'xl''md'Padding for header, body, and footer

Events ​

EventDetailDescription
open-change{ open: boolean, reason: string }Fired whenever the dialog opens or closes
close-request{ reason: 'trigger' | 'escape' | 'outside-click' }Fired before close and can be prevented

Slots ​

SlotDescription
(default)Dialog body content
headerCustom header content: replaces the default title + close-button layout
footerAction buttons or supplemental content pinned to the bottom of the panel

CSS Custom Properties ​

PropertyDescriptionDefault
--dialog-bgPanel background colorvar(--color-canvas)
--dialog-border-colorPanel border colorvar(--color-contrast-300)
--dialog-radiusPanel border radiusvar(--rounded-lg)
--dialog-shadowPanel drop shadowvar(--shadow-xl)
--dialog-paddingPadding for header, body, and footer sectionsvar(--size-6)
--dialog-gapGap between footer action buttonsvar(--size-4)
--dialog-backdrop-bgBackdrop veil colorvar(--overlay-veil)
--dialog-max-widthMaximum panel width (overridden by size)32rem

Accessibility ​

The dialog component follows the WAI-ARIA Dialog (Modal) Pattern and is built on the native <dialog> element for WCAG 2.1 Level AA compliance.

The inner <dialog> element carries role="dialog" implicitly, so no extra ARIA role is needed. aria-modal="true" signals to assistive technologies that content outside the dialog is inert while it is open. When label is set, it becomes the aria-label of the dialog, giving screen readers a concise title to announce on open: always set a label (or provide a custom header slot), because a missing label creates a disorienting "unlabelled dialog" announcement when focus moves into the panel.

Keyboard navigation is handled natively by the browser. Tab moves focus to the next focusable element inside the dialog and wraps around; Shift + Tab moves to the previous focusable element; Escape closes the dialog. On open, the browser moves focus into the dialog panel automatically: no manual focus() call is required. Focus is trapped inside the dialog while it is open, and on close the browser returns focus to the element that triggered the dialog.