Native HTML accordions with <details> and <summary>

Want a no-JS way to show/hide content in a clean, semantic, and accessible way? Look no further than the <details> and <summary> tags. They’re built into HTML, work out of the box, and are perfect for FAQs, collapsible sections, and progressive disclosure.

What is <details>?

The <details> element creates a disclosure widget that users can open and close — like a toggle. Inside it, the <summary> element acts as the clickable label or header. Anything else inside is revealed when expanded.

Here’s the simplest example:

<details>
  <summary>This is hte text shown in the default collapsed state.</summary>
  <p>I'm the text revealed when expanded.</p>
</details>

• The <summary> is always visible.
• Clicking it toggles the visibility of the rest of the <details> content.
• It’s keyboard accessible and has built-in ARIA roles under the hood.
• You can style both parts with CSS.

Styling with CSS

You can customize how it looks — especially the default triangle. If you’d like to change it to a (+) or (-) on expand, you can use the CSS below.

details:open summary::after {
  transform: rotate(0deg);
}

details summary {
  
  	/* Hide the default marker */
      &::marker {
        content: "";
      }

      &::before,
      &::after {
        /* Custom marker dimensions */
        content: "";
        border-block-start: 3px solid black;
        height: 0;
        width: 1rem;

        /* Positions the lines */
        inset-block-start: 1rem;
        inset-inline-end: -10px;

        /* Anchor the shape to the summary */
        position: absolute;
        position-anchor: --summary;
        position-area: top end;
      }

      /* Rotate just the ::after line to create a "+"" shape */
      &::after {
        transform: rotate(90deg);
        transform-origin: 50%;
      }
    }

Accessibility (a11y)

The <details> and <summary> elements are built with accessibility in mind, but they’re not perfect out of the box. Screen readers generally recognize them as interactive elements, and they are keyboard accessible (users can toggle them with the Space or Enter key). That said, there are a few things you can do to enhance their usability:

• Use clear, descriptive text in the <summary> so users know what they’re expanding.
• Don’t use complex elements (like buttons or inputs) inside <summary> — it’s meant to be a simple toggle.
• If styling heavily, preserve focus indicators and visual cues.
• You can add aria-expanded dynamically if needed for better screen reader support, although most modern readers already track the open state.

Here’s an optional enhancement using JavaScript to reflect the open state with aria-expanded:

document.querySelectorAll('details').forEach(detail => {
  const summary = detail.querySelector('summary');
  detail.addEventListener('toggle', () => {
    summary.setAttribute('aria-expanded', detail.open);
  });
});

While not strictly required, this technique can improve clarity for assistive tech users in custom UI contexts. Keep in mind that <details> is a progressive enhancement — it works even when JavaScript is disabled, which is another win for accessibility.

Summary

The <details> tag is one of those native HTML elements that most developers ignore — but it solves a real problem without needing extra JS or ARIA gymnastics. It’s semantic, accessible, and easy to style. Next time you’re building an accordion or toggle UI, consider skipping the JavaScript and reaching for this hidden HTML powerhouse.