Clean Markup

Animating Native Accordions with the CSS details-content Pseudo-Element

Animating Native Accordions with the CSS details-content Pseudo-Element

The HTML <details> and <summary> elements give developers accessible, zero-script disclosure widgets out of the box, complete with keyboard interaction, built-in name grouping for exclusive accordions, and automatic screen reader state announcements. Until recently, however, smoothly animating a <details> panel open or closed in pure CSS remained impractical because the browser wraps all slotted non-summary content inside an anonymous shadow container whose content-visibility and block-size: auto could not be cleanly targeted or interpolated.

Modern CSS resolves both hurdles through the ::details-content pseudo-element and intrinsic size interpolation. By pairing ::details-content with interpolate-size: allow-keywords and transition-behavior: allow-discrete, stylesheets can transition block-size directly from 0 to auto while keeping content-visibility active for the duration of the closing animation. As of early 2026, this pure-CSS pattern degrades gracefully in older engines—falling back to an instant native toggle without breaking disclosure semantics or requiring JavaScript height measurements.

Example

:root {
  interpolate-size: allow-keywords;
}

details::details-content {
  overflow: hidden;
  block-size: 0;
  opacity: 0;
  transition:
    block-size 0.3s ease,
    opacity 0.25s ease,
    content-visibility 0.3s allow-discrete;
}

details[open]::details-content {
  block-size: auto;
  opacity: 1;
}

Implementation

<section class="faq-accordion" aria-label="Frequently Asked Questions">
  <details class="faq-item" name="faq-group" open>
    <summary class="faq-trigger">
      <span>How does native accordion grouping work?</span>
      <span class="faq-chevron" aria-hidden="true"></span>
    </summary>
    <div class="faq-body">
      <p>
        Sharing the same <code>name</code> attribute across multiple
        <code>&lt;details&gt;</code> elements instructs the browser to close
        sibling panels automatically whenever a new item is expanded.
      </p>
    </div>
  </details>

  <details class="faq-item" name="faq-group">
    <summary class="faq-trigger">
      <span>What happens in browsers without ::details-content?</span>
      <span class="faq-chevron" aria-hidden="true"></span>
    </summary>
    <div class="faq-body">
      <p>
        The disclosure widget remains fully interactive and accessible,
        switching between open and closed states immediately without layout
        glitches or JavaScript dependencies.
      </p>
    </div>
  </details>
</section>
/* ==========================================================================
   Accessible Native Accordion using ::details-content & interpolate-size
   ========================================================================== */

.faq-accordion {
  --accordion-border: #e2e8f0;
  --accordion-surface: #ffffff;
  --accordion-accent: #0f172a;
  --accordion-duration: 0.32s;

  max-inline-size: 42rem;
  display: grid;
  gap: 0.75rem;
  interpolate-size: allow-keywords;
}

.faq-item {
  border: 1px solid var(--accordion-border);
  border-radius: 0.75rem;
  background-color: var(--accordion-surface);
  overflow: clip;
}

.faq-trigger {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 1rem;
  padding: 1rem 1.25rem;
  font-weight: 600;
  color: var(--accordion-accent);
  cursor: pointer;
  list-style: none;
  user-select: none;
}

.faq-trigger::-webkit-details-marker {
  display: none;
}

.faq-trigger:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: -2px;
  border-radius: 0.75rem;
}

.faq-chevron {
  inline-size: 0.65rem;
  block-size: 0.65rem;
  flex-shrink: 0;
  border-inline-end: 2px solid currentColor;
  border-block-end: 2px solid currentColor;
  transform: rotate(45deg) translateY(-2px);
  transition: transform 0.25s ease;
}

.faq-item[open] .faq-chevron {
  transform: rotate(-135deg) translateY(-2px);
}

/* Animate only when the engine supports intrinsic size interpolation */
@supports (interpolate-size: allow-keywords) {
  .faq-item::details-content {
    block-size: 0;
    opacity: 0;
    overflow: hidden;
    transition:
      block-size var(--accordion-duration) cubic-bezier(0.22, 1, 0.36, 1),
      opacity 0.22s ease,
      content-visibility var(--accordion-duration) allow-discrete;
  }

  .faq-item[open]::details-content {
    block-size: auto;
    opacity: 1;
  }
}

.faq-body {
  padding: 0 1.25rem 1.25rem;
  color: #475569;
  line-height: 1.6;
}

.faq-body p {
  margin: 0;
}

@media (prefers-reduced-motion: reduce) {
  .faq-chevron,
  .faq-item::details-content {
    transition: none;
  }
}

Main Point: Combining the ::details-content pseudo-element with interpolate-size: allow-keywords and discrete content-visibility transitions delivers smooth, accessible native <details> accordions with zero JavaScript.

Credits

Photo by Tobias Keller on Unsplash

← Home