Learn how to build a disclosure component using the native HTML details tag

When building interactive user interfaces, collapsible or expandable sections appear constantly. Whether it's an FAQ, a settings panel, or an accordion-style navigation, developers have traditionally relied on JavaScript and ARIA attributes to create these patterns. However, HTML5 introduced a native solution that handles most of the heavy lifting automatically.

Introducing the Disclosure Pattern

The disclosure pattern is a classic UI component that shows and hides content on demand. Users expect to expand sections to reveal additional information without navigating to a new page. While many frameworks provide pre-built solutions, the native HTML details and summary elements deliver this functionality with zero JavaScript and built-in accessibility.

How Details and Summary Work

The details element acts as a container for collapsible content, while the summary element provides the interactive label that toggles visibility. When a user clicks or focuses on the summary and presses Enter or Space, the content inside details expands or collapses. The browser handles all state management, keyboard interactions, and animation automatically.

Here is a basic example of the markup structure. The summary element must be the first child of details. Any content following summary inside the details element becomes the collapsible region. You can place paragraphs, lists, images, or even nested interactive elements within the disclosure.

By default, the browser provides a disclosure triangle alongside the summary text. This visual indicator communicates the expandability state to users, and it updates automatically when the content opens or closes.

Accessibility Built In

One of the strongest arguments for using native details and summary elements is the accessibility foundation they provide. The elements expose the appropriate ARIA roles and states to assistive technologies without any additional attributes. Screen readers announce the disclosure state, allow keyboard navigation, and communicate the interactive nature of the summary as a button.

The pattern supports full keyboard operability out of the box. Users can Tab to focus the summary, then activate it with Enter or Space. The summary element receives an implicit button role, making it focusable and interactive in the expected manner. This means you do not need to add tabindex, role, or custom keydown handlers to achieve basic accessibility compliance.

Styling Possibilities

While the default browser styling works for prototyping, you can customize the appearance extensively through CSS. The disclosure triangle can be hidden or replaced with custom icons using the ::marker pseudo-element or by styling the summary element directly and hiding the default indicator.

You can animate the opening and closing using CSS transitions on the details element, though full height animations traditionally require small JavaScript workarounds since animating to height: auto is not directly supported. CSS container queries allow you to adapt disclosure components responsively based on their container size, which is useful when building design system components.

When to Use Native Disclosure

The native implementation excels for simple expand-collapse needs like FAQs, help documentation, or supplementary content sections. It degrades gracefully in older browsers by showing content expanded by default. However, for complex scenarios requiring multiple sections open simultaneously, custom accordion behavior, or tight integration with framework state management, you may still need a JavaScript-based solution.

For most content-focused websites and applications, starting with native details and summary elements represents a pragmatic choice. You gain semantic correctness, accessibility, and reduced JavaScript bundle size without sacrificing the user experience that people expect from collapsible interfaces.

Further reading: https://micaavigliano.com/en/blog/all-you-need-is-details