HTML Dialog Element: Native Modals Without Libraries

Bootstrap Modal, Headless UI Dialog, Radix Dialog, @reach/dialog — most popular UI kits include a modal component. These exist because building a fully accessible modal from scratch is genuinely hard:

• Focus must be trapped inside the modal • Background content must be non-interactive (aria-hidden or inert) • The Escape key must close it • Focus must return to the trigger element on close • Screen readers must announce the modal • Scroll must be locked on the body

The `<dialog>` element handles every one of these requirements natively. In 2022, it reached full cross-browser support. It's time to stop shipping 10kb+ modal libraries.

<button id="open-dialog">Open Dialog</button>

<dialog id="confirm-modal" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm Action</h2>
  <p>Are you sure you want to delete this item? This cannot be undone.</p>
  <div class="dialog-actions">
    <form method="dialog">
      <button value="cancel">Cancel</button>
      <button value="confirm" class="btn-danger" autofocus>Delete</button>
    </form>
  </div>
</dialog>

<script>
  const dialog = document.getElementById('confirm-modal');
  const trigger = document.getElementById('open-dialog');

  trigger.addEventListener('click', () => dialog.showModal());

  dialog.addEventListener('close', () => {
    if (dialog.returnValue === 'confirm') {
      performDelete();
    }
  });
</script>

`showModal()` — not `show()` — opens the dialog as a modal with: a backdrop, focus trap, scroll lock, aria-modal semantics, and Escape to close.

dialog {
  /* Remove UA styles */
  border: none;
  border-radius: 16px;
  padding: 0;
  width: min(90vw, 480px);
  background: #12121a;
  color: white;

  /* Center on screen */
  position: fixed;
  inset: 0;
  margin: auto;

  /* Animation */
  opacity: 0;
  transform: scale(0.95) translateY(8px);
  transition: opacity 0.2s ease, transform 0.2s ease;
}

dialog[open] {
  opacity: 1;
  transform: scale(1) translateY(0);
}

@starting-style {
  dialog[open] {
    opacity: 0;
    transform: scale(0.95) translateY(8px);
  }
}

dialog::backdrop {
  background: rgba(0, 0, 0, 0.7);
  backdrop-filter: blur(4px);
  -webkit-backdrop-filter: blur(4px);
}

@starting-style {
  dialog[open]::backdrop {
    background: rgba(0, 0, 0, 0);
  }
}

The `@starting-style` rule defines the initial state for enter animations — without it, CSS transitions on `display: none → block` have no starting point.

<dialog id="settings-dialog">
  <h2>Settings</h2>
  <form method="dialog">
    <label>
      Theme
      <select name="theme">
        <option value="dark">Dark</option>
        <option value="light">Light</option>
      </select>
    </label>
    <!-- This button closes the dialog and sets returnValue to 'save' -->
    <button type="submit" value="save">Save Settings</button>
    <button value="cancel">Cancel</button>
  </form>
</dialog>

`form[method="dialog"]` submits the form to the dialog (not the server). The dialog closes, and `dialog.returnValue` is set to the value of the submit button that was clicked. Read form data via `FormData` in the close handler.

// Modal: top layer, backdrop, focus trap, Escape to close
dialog.showModal();

// Non-modal: rendered in-flow, no backdrop, no focus trap
dialog.show();

`show()` is useful for non-critical inline messaging — a settings panel, a nested form, or a contextual info box. The element is visible in the normal stacking context, not the top layer.

The `dialog` element uses `display: none` when closed. CSS transitions can't animate from `none` to `block`. To animate the close transition, you need to defer the close:

function closeWithAnimation(dialog) {
  dialog.classList.add('closing');
  dialog.addEventListener('animationend', () => {
    dialog.classList.remove('closing');
    dialog.close();
  }, { once: true });
}

.closing {
  animation: dialogExit 0.2s ease forwards;
}

@keyframes dialogExit {
  to { opacity: 0; transform: scale(0.95); }
}

Alternatively, in Chrome 117+ and Safari 17.5+, the `transition-behavior: allow-discrete` property enables transitions on `display` changes natively.

• ✅ `aria-labelledby` pointing to the dialog title • ✅ `autofocus` on the primary action button • ✅ `form[method="dialog"]` returns a value, not a server request • ✅ Escape key closes automatically (provided by showModal) • ✅ Focus returns to trigger on close (provided by browser) • ✅ `::backdrop` prevents interaction with background (provided by showModal)

Does <dialog> work in React? Yes. Use a `ref` to access the dialog element and call `showModal()`. React 19 added `dialog` to its list of elements where `ref` is first-class.

What about scroll locking? `showModal()` automatically prevents body scroll in most browsers. If you need manual scroll locking (for custom modal implementations), use `document.body.style.overflow = 'hidden'`.

Can I stack multiple dialogs? Yes. Each call to `showModal()` adds a new dialog to the top layer. They stack correctly with proper focus management.

Does it work with React portals? Yes — a `<dialog>` rendered via a React portal works correctly because `showModal()` handles the top-layer placement natively.