HTML details & summary: collapsible disclosure elements

The details and summary elements let you hide and reveal content without JavaScript. They are useful for FAQs, feature explanations, extra notes, and any content that should stay out of the way until the reader chooses to open it.

Quick answer: Use details as the collapsible container and place exactly one summary as its first child. The summary text becomes the visible toggle, and the rest of the content is shown or hidden automatically.

Difficulty: Beginner

You'll understand this better if you know: basic HTML element structure, how nested elements work, and the difference between semantic and presentational markup.

1. What Are HTML details and summary?

The details element is a built-in disclosure widget. It contains content that can be expanded or collapsed by the user. The summary element provides the visible label or heading that the user clicks or taps to toggle the disclosure.

details wraps the hidden and visible content.
summary must be the first child of details.
Browsers handle open and closed states without extra scripting.
The pattern is semantic and keyboard accessible by default.

Think of it as a native, lightweight way to show optional information.

2. Why HTML details and summary Matter

Many pages need extra information that should not interrupt the main reading flow. Collapsible content helps keep pages shorter, easier to scan, and less overwhelming, especially on mobile screens.

This pattern is especially useful when you want to:

Hide long answers in FAQs until the reader asks for them.
Keep technical notes, implementation details, or legal text available without dominating the page.
Avoid building custom toggle behavior for simple disclosure interactions.
Provide accessible interaction with minimal markup.

Because the browser manages the interaction, the markup is easier to maintain than a custom accordion built from generic elements.

3. Basic Syntax or Core Idea

The minimal structure is straightforward. The summary label goes first, followed by the content you want to hide or reveal.

Minimal structure

This example shows the required nesting and the default closed state.

<details>
  <summary>More information</summary>
  <p>This content is hidden until the user opens the disclosure.</p>
</details>

By default, details is closed. When the user activates summary, the rest of the content becomes visible.

Opening the disclosure by default

You can add the open attribute to start in the expanded state.

<details open>
  <summary>Project notes</summary>
  <p>These notes are visible as soon as the page loads.</p>
</details>

The open attribute is useful when the content is important enough to show immediately.

4. Step-by-Step Examples

Example 1: FAQ answer

A common use case is an FAQ item. The question belongs in summary, and the answer goes inside the disclosure body.

<details>
  <summary>What file format should I upload?</summary>
  <p>Upload a .png or .jpg file under 5 MB.</p>
</details>

This is one of the clearest and most readable uses of disclosure content.

Example 2: Nested explanatory content

You can include multiple elements inside details, not just a paragraph.

<details>
  <summary>Installation notes</summary>
  <p>Install the package with your project’s package manager.</p>
  <ul>
    <li>Use the latest stable version.</li>
    <li>Restart your editor after installation.</li>
  </ul>
</details>

This works well when a short label needs to reveal a richer explanation.

Example 3: Structured help content

details can contain headings, lists, and other semantic HTML, as long as the structure remains meaningful.

<details>
  <summary>Shipping estimate</summary>
  <h3>Delivery times</h3>
  <p>Standard delivery usually takes 3 to 5 business days.</p>
  <p>Express delivery usually takes 1 to 2 business days.</p>
</details>

Use this when the hidden content has a natural internal structure.

Example 4: Multiple disclosures on one page

Several disclosures can appear together without extra scripting.

<details>
  <summary>What is included?</summary>
  <p>The plan includes core support and regular updates.</p>
</details>

<details>
  <summary>What is not included?</summary>
  <p>Custom integrations and on-site services are billed separately.</p>
</details>

This pattern is common for help centers, product pages, and documentation pages.

5. Practical Use Cases

FAQ sections where each question reveals a short answer.
Documentation pages that hide advanced notes or edge cases.
Product pages that list specifications without crowding the layout.
Privacy or legal pages where definitions can be collapsed for readability.
Help articles that contain optional troubleshooting details.

Use details when the content is genuinely optional, not when it is essential to understanding the page.

6. Common Mistakes

Mistake 1: Placing summary somewhere other than first

The browser expects summary to be the first child of details. If it is placed later, the disclosure may not behave as intended and the label can become confusing.

Problem: The toggle label is not the first child, so the structure is invalid for the intended disclosure pattern.

<details>
  <p>This content appears before the label.</p>
  <summary>More details</summary>
</details>

Fix: Move summary to the first position inside details.

<details>
  <summary>More details</summary>
  <p>This content appears after the label.</p>
</details>

The corrected version works because the browser can use summary as the disclosure control.

Mistake 2: Using details for content that should always be visible

Not every block of text should be collapsible. If the information is essential, hiding it adds friction and can make the page harder to understand.

Problem: Important instructions are hidden by default, so readers may miss them entirely.

<details>
  <summary>Read this first</summary>
  <p>Enter your billing address exactly as it appears on your statement.</p>
</details>

Fix: Keep essential information visible, and reserve details for supporting or optional content.

<p>Enter your billing address exactly as it appears on your statement.</p>
<details>
  <summary>Why we ask for this</summary>
  <p>We use it to reduce payment verification errors.</p>
</details>

The fixed version keeps the key instruction visible while still offering extra context.

Mistake 3: Using non-semantic clickable elements instead of summary

Some developers try to build a custom toggle with a generic element. That removes built-in keyboard behavior and accessibility semantics.

Problem: A generic element does not provide the native disclosure behavior, so keyboard and assistive technology support are weaker.

<details>
  <div>More information</div>
  <p>This content is meant to be hidden or shown.</p>
</details>

Fix: Use summary so the browser exposes the disclosure properly.

<details>
  <summary>More information</summary>
  <p>This content is meant to be hidden or shown.</p>
</details>

The corrected version is both semantic and accessible by default.

7. Best Practices

Practice 1: Write a clear summary label

The summary text should tell readers exactly what they will get if they open it. Vague labels reduce usability.

<details>
  <summary>Show shipping estimate for Europe</summary>
  <p>Delivery usually takes 5 to 7 business days.</p>
</details>

Specific labels help users decide whether to expand the content.

Practice 2: Keep the hidden content focused

Use a disclosure for one related idea, not a large page section with many unrelated topics. That keeps the interaction predictable.

<details>
  <summary>Refund policy</summary>
  <p>Refunds are available within 30 days for eligible purchases.</p>
</details>

A focused disclosure is easier to scan and understand than a mixed-content drawer.

Practice 3: Use open only when the content is worth showing immediately

The open attribute should not be used everywhere. If every item starts expanded, the page loses the readability benefit.

<details open>
  <summary>Current status</summary>
  <p>The service is operating normally.</p>
</details>

Use the expanded state strategically so it supports the content hierarchy.

8. Limitations and Edge Cases

Some browsers display a native disclosure marker that may vary slightly in appearance.
The default triangle or arrow is browser-controlled, so its styling is limited without additional CSS.
The details element is not the same as a fully custom accordion; it is a simple disclosure control.
If a page depends on all content being visible for search or scanning, hiding too much can hurt usability.
Older browsers may not fully support the element in the same way as modern browsers, although support is broadly available in current browsers.

Because the browser owns the interaction, behavior is consistent, but visual appearance can differ from one browser to another.

9. Practical Mini Project

Here is a small FAQ section that uses only semantic HTML. It shows how details and summary fit together in a real page.

<section aria-labelledby="faq-title">
  <h2 id="faq-title">Frequently asked questions</h2>

  <details>
    <summary>How long does shipping take?</summary>
    <p>Standard shipping usually takes 3 to 5 business days.</p>
  </details>

  <details>
    <summary>Can I track my order?</summary>
    <p>Yes. You will receive a tracking link after the package ships.</p>
  </details>
</section>

This pattern creates a clean FAQ area with built-in disclosure behavior and semantic structure.

10. Key Points

details creates a collapsible disclosure section.
summary is the visible label and must be the first child.
The open attribute makes the disclosure expanded by default.
Use it for optional supporting information, not essential instructions.
The element is semantic and accessible, so it is often better than a custom toggle for simple use cases.

11. Practice Exercise

Create a small product information section using details and summary.

Show a product name as a heading outside the disclosure.
Add one disclosure for specifications.
Add one disclosure for delivery information.
Make the summary labels specific and helpful.

Expected output: A page section with two collapsible blocks, each revealing related information when opened.

Hint: Put the most important visible content outside the disclosures, and use the summary text to describe each hidden section clearly.

Solution:

<section aria-labelledby="product-info">
  <h2 id="product-info">Wireless Headphones</h2>
  <p>Lightweight headphones with noise reduction and long battery life.</p>

  <details>
    <summary>View specifications</summary>
    <ul>
      <li>Battery life: 30 hours</li>
      <li>Bluetooth: 5.3</li>
      <li>Weight: 240 g</li>
    </ul>
  </details>

  <details>
    <summary>View delivery information</summary>
    <p>Delivery usually takes 2 to 4 business days, depending on location.</p>
  </details>
</section>

This solution works because the page keeps the core product summary visible while allowing supporting details to stay collapsed until needed.

12. Final Summary

HTML details and summary give you a native, semantic way to hide and reveal content. They are ideal for FAQs, notes, supplemental explanations, and any other content that should be available but not always visible.

The key rule is simple: put summary first, keep the content focused, and use open only when expanded content should appear by default. When used well, this pattern improves readability and accessibility without requiring custom scripting.

If you want to go further, compare details with custom accordion patterns so you can choose the right approach for your interface.