HTML <details> Tag: Create Collapsible Content Elements

Introduction to the <details> Tag

The <details> tag is one of the most practical HTML elements for creating interactive content without relying on JavaScript. It allows you to build collapsible sections that your users can open or close with a simple click, significantly improving the user experience on your web pages.

If you want to master HTML and all its interactive tags perfectly, our HTML course guides you step by step in creating modern and accessible websites. You will discover how to effectively use elements like <details> to enhance your interfaces.

This tag is particularly useful for FAQs, accordion menus, contextual help sections, or any content you want to hide by default to avoid cluttering your page. Let's explore together all the possibilities it offers.

Definition and Syntax of the <details> Tag

What is the <details> tag?

The <details> tag is a semantic HTML5 element that creates a disclosure widget. This widget allows you to show or hide additional information. By default, the content inside <details> is hidden, and the user must click to reveal it.

This tag works in tandem with the <summary> tag, which defines the visible and clickable title of the element. Without <summary>, the browser displays default text such as "Details".

Basic Syntax

Here is the fundamental structure of the <details> tag:

<details>
  <summary>Click to learn more</summary>
  <p>This is the hidden content that appears when you expand the element.</p>
</details>

In this example, only the text "Click to learn more" is initially visible. The paragraph only appears when the user interacts with the element.

Available Attributes

The <details> tag accepts several important attributes:

The open Attribute

The open attribute allows you to display the content expanded when the page loads:

<details open>
  <summary>Already open section</summary>
  <p>This content is visible immediately when the page loads.</p>
</details>

Practical Examples of Use

Creating an Interactive FAQ

One of the most common use cases for <details> is creating FAQs (Frequently Asked Questions). Here's how to structure a FAQ for your Believemy website:

<section class="faq-believemy">
  <h2>Frequently Asked Questions About Our Courses</h2>
  
  <details>
    <summary>How do I access my course?</summary>
    <p>After registration, you will receive a confirmation email 
    with your credentials. Then log in to your learner dashboard 
    to access all your courses.</p>
  </details>
  
  <details>
    <summary>Do I have lifetime access to courses?</summary>
    <p>Yes! Once enrolled, you keep unlimited access to your 
    course as well as all future updates.</p>
  </details>
  
  <details>
    <summary>Can I get a certificate?</summary>
    <p>Absolutely. At the end of each course, you can 
    download your personalized certificate of completion.</p>
  </details>
</section>

This structure is perfectly semantic and accessible. Search engines can index the content, and screen readers handle this type of element natively.

Creating an Exclusive Accordion Menu

Since 2023, the name attribute allows you to create groups of <details> elements where only one can be open at a time. This is the typical behavior of an accordion:

<div class="accordion-course">
  <details name="html-modules">
    <summary>Module 1: HTML Basics</summary>
    <ul>
      <li>Introduction to the web</li>
      <li>HTML page structure</li>
      <li>Essential tags</li>
    </ul>
  </details>
  
  <details name="html-modules">
    <summary>Module 2: Forms</summary>
    <ul>
      <li>The form tag</li>
      <li>Input fields</li>
      <li>Data validation</li>
    </ul>
  </details>
  
  <details name="html-modules">
    <summary>Module 3: Semantic HTML</summary>
    <ul>
      <li>The importance of semantics</li>
      <li>Structural tags</li>
      <li>Accessibility and SEO</li>
    </ul>
  </details>
</div>

When you open one module, the others close automatically. This feature is native and requires no JavaScript!

Displaying Collapsible Source Code

For tutorials and technical documentation, <details> is ideal for hiding long code blocks:

<details>
  <summary>View complete source code</summary>
  <pre><code class="language-javascript">
function calculateCoursePrice(basePrice, discount) {
  const finalPrice = basePrice * (1 - discount / 100);
  return finalPrice.toFixed(2);
}

const price = calculateCoursePrice(299, 20);
console.log(`Price after discount: $${price}`);
  </code></pre>
</details>

This approach keeps your articles readable while offering the complete code to interested readers.

CSS Customization of the <details> Tag

Styling the Summary and Marker

The ::marker pseudo-element allows you to customize the arrow or triangle that indicates the open/closed state:

/* Style the summary */
details summary {
  cursor: pointer;
  padding: 1rem;
  background-color: #f5f5f5;
  border-radius: 8px;
  font-weight: 600;
  list-style: none; /* Remove default marker */
}

/* Hover state */
details summary:hover {
  background-color: #e8e8e8;
}

/* Customize the marker */
details summary::marker {
  color: #3498db;
  font-size: 1.2em;
}

/* Alternative: use ::before for a custom marker */
details summary::before {
  content: '▶ ';
  display: inline-block;
  transition: transform 0.3s ease;
}

details[open] summary::before {
  transform: rotate(90deg);
}

Animating Opening and Closing

Animating the content of <details> is tricky because the browser handles the display in a binary manner. Here's a technique using CSS Grid:

details {
  border: 1px solid #ddd;
  border-radius: 8px;
  margin-bottom: 1rem;
  overflow: hidden;
}

details summary {
  padding: 1rem 1.5rem;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  cursor: pointer;
}

details .details-content {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 0.3s ease-out;
}

details[open] .details-content {
  grid-template-rows: 1fr;
}

details .details-content > div {
  overflow: hidden;
}

details .details-content > div > * {
  padding: 1rem 1.5rem;
}

And the corresponding HTML:

<details>
  <summary>Discover the program</summary>
  <div class="details-content">
    <div>
      <p>Our HTML course covers all essential aspects...</p>
    </div>
  </div>
</details>

Accessibility and Best Practices

Native Accessibility

The <details> tag is inherently accessible. Assistive technologies recognize this element and inform users that it is collapsible content. Here are the native accessibility features:

• Screen readers announce the state (expanded or collapsed)
• Keyboard navigation works with Enter or Space keys
• Focus is properly managed
• The element is in the browser's accessibility tree

Best Practices to Follow

To ensure an optimal experience, follow these recommendations:

SEO Considerations

The content inside <details> is present in the DOM and therefore indexable by search engines. Google has confirmed that this content is taken into account for SEO, even if it is visually hidden. This is a major advantage over JavaScript solutions that might not load content immediately.

JavaScript Events with <details>

Detecting Opening and Closing

You can listen for the toggle event to react to state changes:

const detailsElement = document.querySelector('details.course-believemy');

detailsElement.addEventListener('toggle', (event) => {
  if (detailsElement.open) {
    console.log('The section has been opened');
    // You can load dynamic content for example
    // or send an analytics event
  } else {
    console.log('The section has been closed');
  }
});

Controlling State Programmatically

You can open or close a <details> element via JavaScript:

const details = document.getElementById('my-section');

// Open
details.open = true;

// Close
details.open = false;

// Toggle state
details.open = !details.open;

// Utility function to open or close all
function toggleAllDetails(isOpen) {
  document.querySelectorAll('details').forEach(detail => {
    detail.open = isOpen;
  });
}

// Open all details
toggleAllDetails(true);

// Close all details
toggleAllDetails(false);

Common Mistakes to Avoid

Forgetting the summary Tag

Without <summary>, the browser uses uninformative default text:

<!-- ❌ Avoid -->
<details>
  <p>Content without explicit summary</p>
</details>

<!-- ✅ Correct -->
<details>
  <summary>Learn more about this topic</summary>
  <p>Content with a clear summary</p>
</details>

Incorrect summary Placement

The <summary> must be the first child of <details>:

<!-- ❌ Incorrect -->
<details>
  <p>Some content before</p>
  <summary>The summary</summary>
</details>

<!-- ✅ Correct -->
<details>
  <summary>The summary</summary>
  <p>The content after</p>
</details>

Using details for Critical Content

Don't hide essential information that the user absolutely needs to see:

<!-- ❌ Avoid: critical information hidden -->
<details>
  <summary>Important conditions</summary>
  <p>Warning: your order will be cancelled if not paid within 24 hours.</p>
</details>

<!-- ✅ Better: information visible directly -->
<p class="alert">⚠️ Your order will be cancelled if not paid within 24 hours.</p>

Browser Compatibility

The <details> tag enjoys excellent support in modern browsers:

Frequently Asked Questions About the <details> Tag

Yes, you can nest <details> elements, but we recommend not exceeding two levels of nesting to maintain a good user experience. Each level should have its own descriptive <summary>.

Yes, Google indexes content present in <details> tags even if it is visually hidden. Since the content is present in the DOM from page load, it is accessible to indexing bots. This is a significant advantage for the SEO of your FAQs and collapsible content.

Use the name attribute with the same value on multiple <details> elements. The browser will automatically close other elements in the group when a new element is opened. This feature has been supported by modern browsers since 2023.

To master HTML, CSS, and all interactive tags like <details>, we recommend taking our HTML course. This course guides you step by step in creating modern, accessible, and SEO-optimized websites.