HTML Tips: Use Native <details> and <dialog> for Lightweight UI Components

November 23, 2026

Before reaching for a JavaScript component library, look at what the browser already gives you. Native <details> and <dialog> elements can cover a surprising amount of everyday UI work: FAQ answers, filter panels, confirmations, and short forms. They ship with useful keyboard behavior and are easy to progressively enhance.

minimal web ui components

The key is choosing the right primitive. <details> is for showing and hiding related content in the normal page flow. <dialog> is for a separate task layer, especially a modal that demands attention. Neither one replaces a carefully built custom component when you need advanced interactions.

When to use <details>

Use <details> when the hidden content belongs directly after a visible summary. The browser handles expand/collapse state, and the built-in <summary> acts as the accessible control.

<details>
  <summary>How do I reset my password?</summary>
  <p>Open the account menu, choose Security, then select Reset password.</p>
</details>

This is a good fit for FAQs, inline help, advanced search options, and small filter groups. Avoid nesting interactive controls inside <summary>; keep it as a single clear label.

Exclusive accordions and the name attribute

Modern browsers support putting multiple <details> elements in an exclusive accordion by giving them the same name:

<details name="faq" open>
  <summary>Shipping</summary>
  <p>Orders usually ship within two business days.</p>
</details>

<details name="faq">
  <summary>Returns</summary>
  <p>Use the return link in your order confirmation email.</p>
</details>

Check current support before relying on this alone. MDN documents the name grouping behavior, and Can I Use tracks browser adoption: MDN details, Can I Use: details. For older engines, a tiny vanilla JavaScript fallback is enough:

document.querySelectorAll('details[name]').forEach((el) => {
  el.addEventListener('toggle', () => {
    if (!el.open) return;
    const group = el.getAttribute('name');
    document.querySelectorAll(`details[name="${group}"]`)
      .forEach((other) => {
        if (other !== el) other.open = false;
      });
  });
});

If exclusive behavior is not essential, omit the fallback and simply allow multiple panels to stay open. That is often perfectly usable.

accessible modal dialog interface

When to use <dialog>

Use <dialog> when the user must complete or dismiss a task separate from the page. Calling showModal() opens it in the browser's top layer. A modal dialog should have an accessible name, a visible close path, sensible initial focus, and predictable focus return when it closes.

MDN’s dialog documentation is the best starting point: MDN dialog. Support is good in current evergreen browsers, but older engines may need a polyfill or custom fallback: Can I Use: dialog.

Complete modal example

<button type="button" id="openDeleteDialog">Delete item</button>

<dialog id="deleteDialog" aria-labelledby="deleteTitle">
  <h2 id="deleteTitle">Delete this item?</h2>
  <p>This action cannot be undone.</p>

  <form method="dialog">
    <button type="button" id="cancelDelete">Cancel</button>
    <button type="submit" value="confirm">Delete</button>
  </form>
</dialog>

<script>
const opener = document.querySelector('#openDeleteDialog');
const dialog = document.querySelector('#deleteDialog');
const cancel = document.querySelector('#cancelDelete');

opener.addEventListener('click', () => {
  if (dialog.open) return;
  dialog.returnValue = '';
  dialog.showModal();
});

cancel.addEventListener('click', () => dialog.close('cancel'));

dialog.addEventListener('click', (event) => {
  if (event.target === dialog) dialog.close('backdrop');
});

dialog.addEventListener('cancel', (event) => {
  event.preventDefault();
  dialog.close('escape');
});

dialog.addEventListener('close', () => {
  if (dialog.returnValue !== 'confirm') {
    opener.focus();
    return;
  }
  // Run the destructive action, then restore focus.
  opener.focus();
});
</script>

Accessibility details that matter

  • Accessible name: use aria-labelledby pointing to the dialog title, or aria-label when there is no visible title.
  • Initial focus: the browser moves focus into the modal. For risky actions, focus the cancel button rather than the destructive confirm button. You can also focus the dialog itself by giving it tabindex="-1".
  • Focus return: after closing, return focus to the control that opened the dialog, or to another logical location if that control no longer exists.
  • Close button: include a visible cancel/close control. Do not depend only on clicking the backdrop.
  • Esc: pressing Escape fires a cancelable cancel event, followed by close. Prevent default only when you need custom cleanup or confirmation.
  • Backdrop click: compare event.target with the dialog. Clicks on padding or dialog content should not close it accidentally.
  • Scroll lock: modal dialogs are rendered in the top layer and commonly prevent normal interaction with the page, but do not assume every browser locks background scroll in every layout. Test it; add overflow: hidden to the document or body when required, and remove it on close.

Wrap showModal() in a guard or try/catch if openers can be activated repeatedly. Calling it on an already-open <dialog> throws an InvalidStateError.

What about popover?

The Popover API is useful for transient, non-modal overlays such as menus, toasts, and pickers. It provides top-layer display and light-dismiss behavior, but it is not automatically a full menu or select component. Check support before using it as your only implementation: MDN Popover API, Can I Use: popover.

Choosing the right component

ScenarioGood defaultNotes
FAQ answerdetailsUse name only when you need exclusive behavior and have a fallback strategy.
Filter panel in a sidebardetailsKeeps controls in document flow and easy to browse.
Confirmation boxdialogUse showModal() for a destructive or blocking choice.
Short form, such as invite by emaildialogKeep the task short and clearly titled.
Complex navigation menuPopover or customAdd roving tabindex, arrow keys, and menu semantics if needed.
Long form or multi-step wizardCustom page/panelA large dialog is often awkward on small screens and harder to navigate.
User must compare with background contentNon-modal popover/custom panelA modal blocks the very content the user may need to inspect.

Support and graceful degradation

For details, very old browsers may show both the summary and the extra content. That is usually an acceptable degradation: the information remains readable. If hiding is required, a small polyfill can add the toggling behavior.

For dialog, decide what happens when window.HTMLDialogElement is unavailable. Options include loading a polyfill, rendering a server-friendly page instead, or falling back to a custom focus-trapped modal. Do not silently render a non-modal <div> and call it done; focus trapping, Escape, backdrop behavior, and scroll locking still need to be managed.

if (!('HTMLDialogElement' in window)) {
  // Load a polyfill or activate your legacy modal path.
}

SEO claims to keep modest

Native HTML can reduce custom JavaScript and make content easier for browsers to parse, but using details or dialog is not, by itself, a guaranteed search ranking improvement. Treat these elements as an accessibility, maintenance, and performance choice first. Make sure important content is available in the HTML or rendered server-side when it needs to be indexed, rather than assuming any particular search engine treats disclosure widgets in a special way.

Practical takeaway

Start with details for inline disclosure, dialog for focused modal tasks, and popover for transient non-modal layers. Reach for a custom component when the interaction needs complex keyboard navigation, virtualized content, multi-step flow, or precise positioning. Native elements will not solve every UI problem, but they are often the smallest, most robust first implementation.