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.

Features

• 🔒 Native <dialog> — correct top-layer stacking, built-in backdrop, browser focus trapping
• ⌨️ Escape to close — handled by the browser natively
• 🎯 Controlled open state — toggle with the open attribute or property
• 🔘 Dismissable — optional close (×) button in the header
• 🛡️ Persistent mode — prevent accidental close via backdrop click
• 🧩 Flexible slots — header, default body, and footer
• 📐 5 Sizes: sm, md, lg, xl, full
• 🎨 3 Variants: default, plain, bordered
• ♿ Accessible: role="dialog", aria-modal="true", aria-label from label prop, labelled close button

Source Code

View Source Code

import { computed, defineComponent, handle, html, onMount, ref, watch, fire } from '@vielzeug/craftit';

import type { PaddingSize, RoundedSize } from '../../types';

import { closeIcon } from '../../icons';
import { coarsePointerMixin, elevationMixin, reducedMotionMixin, roundedVariantMixin } from '../../styles';
import { awaitExit } from '../../utils/animation';
import { lockBackground, unlockBackground } from '../../utils/background-lock';
import { useOverlay } from '../../utils/use-overlay';
import componentStyles from './dialog.css?inline';

type DialogSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
type DialogBackdrop = 'opaque' | 'blur' | 'transparent';
type DialogElevation = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';

/** Dialog component properties */

export type BitDialogEvents = {
  close: undefined;
  open: undefined;
};

export type BitDialogProps = {
  /** Backdrop style — 'blur' (default): dark overlay + blur; 'opaque': dark overlay only; 'transparent': no overlay */
  backdrop?: DialogBackdrop;
  /** Show a close (×) button in the header */
  dismissible?: boolean;
  /** Panel shadow elevation — defaults to 'xl' */
  elevation?: DialogElevation;
  /**
   * CSS selector for the element inside the dialog that should receive focus when the dialog opens.
   * Defaults to the first focusable element (browser default).
   * @example 'input[name="email"]' | '#confirm-btn'
   */
  'initial-focus'?: string;
  /** Dialog title shown in the header (used as aria-label when no header slot) */
  label?: string;
  /** Controls the open state of the dialog */
  open?: boolean;
  /** Internal padding size */
  padding?: PaddingSize;
  /** When true, clicking the backdrop does not close the dialog */
  persistent?: boolean;
  /**
   * When true (default), focus returns to the element that triggered the dialog after it closes.
   * Set to false if you want to manage focus manually.
   */
  'return-focus'?: boolean;
  /** Border radius */
  rounded?: RoundedSize | '';
  /** Dialog size */
  size?: DialogSize;
};

/**
 * A modal dialog that traps focus, blocks page interaction, and dismisses on
 * `Escape`. Built on the native `<dialog>` element for correct top-layer stacking
 * and browser-managed accessibility.
 *
 * @element bit-dialog
 *
 * @attr {boolean} open - Open/close the dialog
 * @attr {string} label - Dialog title (also used as aria-label)
 * @attr {string} size - Size: 'sm' | 'md' | 'lg' | 'xl' | 'full'
 * @attr {boolean} dismissible - Show a close (×) button in the header
 * @attr {boolean} persistent - Prevent backdrop-click from closing
 * @attr {string} rounded - Border radius size
 * @attr {string} backdrop - Backdrop style: 'opaque' (default) | 'blur' | 'transparent'
 * @attr {string} elevation - Panel shadow: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
 * @attr {string} padding - Padding: 'none' | 'sm' | 'md' | 'lg' | 'xl'
 *
 * @fires open - Fired when the dialog opens
 * @fires close - Fired when the dialog closes (any trigger)
 *
 * @slot - Dialog body content
 * @slot header - Custom header content (replaces the default title + close layout)
 * @slot footer - Action buttons or additional content at the bottom
 *
 * @cssprop --dialog-bg - Panel background color
 * @cssprop --dialog-border-color - Panel border color
 * @cssprop --dialog-radius - Panel border radius
 * @cssprop --dialog-shadow - Panel drop shadow
 * @cssprop --dialog-padding - Padding for header, body, and footer sections
 * @cssprop --dialog-gap - Gap between footer action buttons
 * @cssprop --dialog-backdrop - Backdrop overlay color
 * @cssprop --dialog-max-width - Maximum panel width (overridden by size prop)
 *
 * @example
 * ```html
 * <bit-dialog label="Confirm action" dismissible>
 *   <p>Are you sure you want to delete this item?</p>
 *   <div slot="footer">
 *     <bit-button variant="ghost" id="cancel">Cancel</bit-button>
 *     <bit-button color="error" id="confirm">Delete</bit-button>
 *   </div>
 * </bit-dialog>
 *
 * <script type="module">
 *   import '@vielzeug/buildit/dialog';
 *   const dialog = document.querySelector('bit-dialog');
 *   document.querySelector('#open-btn').addEventListener('click', () => {
 *     dialog.setAttribute('open', '');
 *   });
 *   document.querySelector('#cancel').addEventListener('click', () => {
 *     dialog.removeAttribute('open');
 *   });
 * </script>
 * ```
 */
export const DIALOG_TAG = defineComponent<BitDialogProps, BitDialogEvents>({
  props: {
    backdrop: { default: undefined },
    dismissible: { default: false },
    elevation: { default: undefined },
    'initial-focus': { default: undefined },
    label: { default: '' },
    open: { default: false },
    padding: { default: undefined },
    persistent: { default: false },
    'return-focus': { default: true },
    rounded: { default: undefined },
    size: { default: 'md' },
  },
  setup({ emit, host, props, slots }) {
    const dialogRef = ref<HTMLDialogElement>();
    const hasHeader = computed(() => slots.has('header').value || !!props.label.value || props.dismissible.value);
    const hasFooter = computed(() => slots.has('footer').value);
    const { applyInitialFocus, captureReturnFocus, closeWithAnimation, restoreFocus } = useOverlay(
      host,
      dialogRef,
      () => dialogRef.value?.querySelector<HTMLElement>('.panel'),
      props,
    );

    onMount(() => {
      const dialog = dialogRef.value;

      if (!dialog) return;

      // Sync prop changes → native dialog
      watch(
        props.open,
        (open) => {
          if (open) {
            if (!dialog.open) {
              captureReturnFocus();
              dialog.showModal();
              applyInitialFocus();
              lockBackground(host);
              emit('open');
            }
          } else {
            closeWithAnimation();
          }
        },
        { immediate: true },
      );

      // Native dialog 'close' fires after animation finishes or on programmatic .close()
      const handleNativeClose = () => {
        unlockBackground();
        // Sync the open prop back to the host attribute if closed externally
        host.removeAttribute('open');
        // Return focus to the triggering element unless opted out
        restoreFocus();
        emit('close');
      };
      // Intercept Escape to play exit animation first; also enforce persistent mode
      const handleKeydown = (e: KeyboardEvent) => {
        if (e.key === 'Escape') {
          e.preventDefault();

          if (!props.persistent.value) {
            closeWithAnimation();
          }
        }
      };
      // Backdrop click: the click target is the <dialog> element itself (not the panel)
      const handleBackdropClick = (e: MouseEvent) => {
        if (props.persistent.value) return;

        // When clicking the backdrop, the event target is the <dialog> element itself.
        // Clicks inside the panel bubble up with a more specific target.
        if (e.target === dialog) {
          closeWithAnimation();
        }
      };

      handle(dialog, 'close', handleNativeClose);
      handle(dialog, 'click', handleBackdropClick);
      handle(dialog, 'keydown', handleKeydown);

      return () => {
        // Ensure the native dialog is closed on unmount to release top-layer
        if (dialog.open) dialog.close();

        unlockBackground();
      };
    });

    const handleDismiss = () => {
      const dialog = dialogRef.value;

      if (!dialog) return;

      fire.custom(dialog, 'close-request');
      dialog.classList.add('closing');

      const panel = dialog.querySelector<HTMLElement>('.panel');
      const finish = () => {
        dialog.classList.remove('closing');
        dialog.close();
      };

      if (panel) {
        awaitExit(panel, finish, 'transition');
      } else {
        finish();
      }
    };

    return html`
      <dialog
        ref=${dialogRef}
        class="dialog"
        part="dialog"
        :aria-label="${() => props.label.value || null}"
        aria-modal="true">
        <div class="overlay" part="overlay" aria-hidden="true"></div>
        <div class="panel" part="panel" :data-size="${props.size}">
          <div class="header" part="header" ?hidden=${() => !hasHeader.value}>
            <slot name="header">
              <span class="title" part="title">${() => props.label.value}</span>
            </slot>
            <button
              class="close"
              part="close"
              type="button"
              aria-label="Close dialog"
              ?hidden=${() => !props.dismissible.value}
              @click=${handleDismiss}>
              ${closeIcon}
            </button>
          </div>
          <div class="body" part="body">
            <slot></slot>
          </div>
          <div class="footer" part="footer" ?hidden=${() => !hasFooter.value}>
            <slot name="footer"></slot>
          </div>
        </div>
      </dialog>
    `;
  },
  styles: [elevationMixin, roundedVariantMixin, coarsePointerMixin, reducedMotionMixin, componentStyles],
  tag: 'bit-dialog',
});

Basic Usage

Use the open attribute to show the dialog and remove it (or set it to false) to close it.

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

<bit-dialog label="Confirm action" dismissable id="dialog">
  <p>Are you sure you want to delete this item? This action cannot be undone.</p>
  <div slot="footer">
    <bit-button variant="ghost" id="cancel-btn">Cancel</bit-button>
    <bit-button color="error" id="confirm-btn">Delete</bit-button>
  </div>
</bit-dialog>

<script type="module">
  import '@vielzeug/buildit/dialog';
  import '@vielzeug/buildit/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

PreviewCode

RTL

Dismissable

Add dismissable to show a close (×) button in the top-right corner of the header.

PreviewCode

RTL

Backdrop

Control the backdrop appearance with the backdrop attribute.

PreviewCode

RTL

Elevation

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

PreviewCode

RTL

Padding

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

PreviewCode

RTL

Custom Header

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

PreviewCode

RTL

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.

PreviewCode

RTL

Listening to Events

const dialog = document.querySelector('bit-dialog');

dialog.addEventListener('open', () => {
  console.log('Dialog opened');
});

dialog.addEventListener('close', () => {
  console.log('Dialog closed');
  // Re-enable the trigger button, reset form state, etc.
});

API Reference

Attributes

Attribute	Type	Default	Description
open	boolean	false	Controls whether the dialog is visible
label	string	''	Dialog title shown in the header; used as aria-label
size	'sm' | 'md' | 'lg' | 'xl' | 'full'	'md'	Panel width preset
dismissable	boolean	false	Show a close (×) button in the header
persistent	boolean	false	Prevent backdrop-click from closing the dialog
rounded	'none' | 'sm' | 'md' | 'lg' | ... | 'full'	—	Override the panel border radius
backdrop	'blur' | 'opaque' | 'transparent'	'opaque'	Backdrop style — blur overlay, opaque (default) overlay, or none
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

Event	Detail	Description
open	—	Fired once when the dialog transitions to open
close	—	Fired when the dialog closes (any trigger)

Slots

Slot	Description
(default)	Dialog body content
header	Custom header content — replaces the default title + close-button layout
footer	Action buttons or supplemental content pinned to the bottom of the panel

CSS Custom Properties

Property	Description	Default
--dialog-bg	Panel background color	var(--color-canvas)
--dialog-border-color	Panel border color	var(--color-contrast-300)
--dialog-radius	Panel border radius	var(--rounded-lg)
--dialog-shadow	Panel drop shadow	var(--shadow-xl)
--dialog-padding	Padding for header, body, and footer sections	var(--size-6)
--dialog-gap	Gap between footer action buttons	var(--size-4)
--dialog-backdrop	Backdrop overlay colour	rgba(0, 0, 0, 0.5)
--dialog-max-width	Maximum 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.

bit-dialog

✅ Keyboard Navigation

Key	Action
Tab	Move focus to the next focusable element inside the dialog (wraps around)
Shift + Tab	Move focus to the previous focusable element (wraps around)
Escape	Close the dialog (handled natively by the browser)

✅ Screen Readers

• The inner <dialog> element carries role="dialog" implicitly — 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.
• When dismissable is set, the close button has a descriptive aria-label="Close dialog".

✅ Focus Management

• On open, the browser moves focus into the dialog panel automatically — no manual focus() call required.
• Focus is trapped inside the dialog while it is open; pressing Tab cycles only through interactive elements within the panel.
• On close, focus returns to the element that triggered the dialog — standard browser behavior for the native <dialog>.

Label every dialog

Always set a label (or provide a custom header slot). Screen readers announce the dialog title immediately when focus moves into the panel, so a missing label creates a disorienting "unlabelled dialog" announcement.

Persistent dialogs

When using persistent, always include an accessible way to dismiss — either dismissable or a clearly labelled cancel button in the footer. A dialog with no dismissal mechanism traps keyboard users indefinitely.

Best Practices

Do:

• Provide a descriptive label — it becomes the accessible dialog title.
• Include a clearly labelled cancel/close action in the footer slot so keyboard and pointer users can dismiss without relying solely on Escape.
• Use persistent only when data would be lost otherwise (e.g. multi-step forms). Always still provide a way to intentionally dismiss (use dismissable or a footer cancel button).
• Keep dialog content focused — if a dialog requires scrolling, it's usually a sign the content should live on its own page.

Don't:

• Nest dialogs; stack them in a queue instead.
• Use dialogs for non-blocking notifications — use bit-alert or a toast component instead.
• Open dialogs without user intent (e.g. on page load) — this is disorienting for screen reader users.