The details and summary Elements

Learn how to create accessible, collapsible content sections using only HTML5 semantic elements.

What it is

The <details> and <summary> elements provide a native way to hide and reveal content. The <details> element acts as the container for the expandable section, while the <summary> element provides the visible heading or label that users click to toggle visibility. This pattern creates an interactive widget without requiring JavaScript or complex CSS frameworks.

Related terms include "accordion," "collapsible panel," and "disclosure widget." These are common UI patterns used to manage information density on web pages.

Why it matters

• No JavaScript required: Reduces page weight and improves performance by eliminating script dependencies for basic interactions.
• Built-in accessibility: Screen readers automatically announce the state (expanded/collapsed) and handle keyboard navigation correctly.
• Semantic clarity: Search engines and assistive technologies understand the relationship between the header and the hidden content.
• Cross-browser support: Supported in all modern browsers, including Chrome, Firefox, Safari, and Edge.

Syntax or steps

1. Create a <details> element to wrap the entire component.
2. Place a <summary> element as the first child of <details>. This text will always be visible.
3. Add any valid HTML content after the <summary> tag inside the <details> block. This content remains hidden until toggled.
4. Optionally, add the open attribute to the <details> tag if you want the section expanded by default.

Example

<details>
  <summary>What is your return policy?</summary>
  <p>You can return items within 30 days of purchase.</p>
  <ul>
    <li>Items must be unused.</li>
    <li>Original packaging is required.</li>
  </ul>
</details>

<details open>
  <summary>Shipping Information</summary>
  <p>Standard shipping takes 3-5 business days.</p>
</details>

In this example, the first FAQ item starts collapsed. Users click "What is your return policy?" to see the paragraph and list. The second item uses the open attribute, so "Shipping Information" is visible immediately upon page load. Both sections function independently.

Common mistakes

• Placing non-summary elements before summary: The <summary> must be the first child of <details>. If other elements appear first, they may not render correctly or break accessibility.
• Nesting details incorrectly: Avoid placing <details> directly inside another <details> without proper spacing or styling, as this can cause confusing visual hierarchies.
• Forgetting the closing tag: Always close </details>. Unclosed tags can cause subsequent content to become unexpectedly hidden or malformed.
• Using divs instead: Developers often use <div> with JavaScript for accordions. This loses native accessibility features and increases maintenance burden unnecessarily.

When to use it

Use <details> for static content like FAQs or legal disclaimers. Use JavaScript solutions when you need persistent state across sessions or complex animation sequences.

Practice

Guided Exercise: Create a "Terms of Service" section where the full text is hidden behind a summary labeled "Read Terms." Ensure the content includes at least one paragraph and one unordered list.

Challenge: Style the <summary> element to remove the default triangle marker using list-style: none; and add a custom "+" icon using CSS pseudo-elements (::before). Hint: You may need to adjust padding to align the custom icon properly.

Quick check

Question: How do you make a details element expanded by default?

Answer: Add the boolean attribute open to the <details> tag.

Summary

The <details> and <summary> elements offer a lightweight, accessible solution for collapsible content. By leveraging native browser behavior, developers can reduce JavaScript overhead while maintaining high usability standards for all users.