More Details on `details`

The Hidden Quirks of <details> and <summary>

Recent discussions across the web development community have brought renewed attention to the <details> and <summary> elements, uncovering a handful of implementation quirks that raise questions about how the browser handles them. From display behavior to accessibility concerns, there are several edges to examine closely.

Why Won't <details> Respect Grid Layouts?

An interesting display issue arises when using <details> as a grid container. In normal usage, it renders as a block-level element, which aligns with the user agent stylesheet. Suppose you attempt to apply a CSS Grid layout to it explicitly:

DevTools shows the element's computed display style, but the observable behavior tells a different story. In practice, with the element set to display: grid, the markup includes the required <summary> plus nested divisions:

When an explicit grid is applied with a height, for instance, you might expect the grid structure to allocate space according to the defined rows:

The expectation would be something like a container sized at 40vh, with rows where the final row fills remaining vertical space:

But that's not what happens. Instead of distributing the grid items across the rows, the additional rows appear stuck—the elements do not occupy the expected track sizes:

The root cause traces back to implementation details of the <details> element's internal structure. The HTML spec describes it as “expected to render as a block box,” but notes that it contains an internal shadow tree with two slots. Critically, the second slot gets inline styling conditioned on the open attribute:

The details element’s second slot is expected to have its style attribute set to display: block; content-visibility: hidden; when the details element does not have an open attribute. When it does have the open attribute, the style attribute is expected to be removed from the second slot.

With <details open>, those nested elements should no longer be locked to block display, so an override to grid should apply. Slots are set to display: contents by default, but directly styling elements inside slots remains locked out. Whether that's a spec oversight or a browser bug, the outcome feels inconsistent with expectations for custom styling.

Menu Patterns and Missing Semantics

<details> has gained traction as a lightweight way to implement disclosure widgets, including menu-like structures. GitHub has even built features on top of this pattern. The basic notion:

The spec does seem to sanction usage beyond simple information disclosure:

The details element represents a disclosure widget from which the user can obtain additional information or controls.

If you think of <details> as the container—carrying an implicit role=group—and <summary> as the interactive toggle that flips the open state, things make intuitive sense. The <summary> has an implied button role, but no direct WAI-ARIA equivalent exists.

Testing with assistive technology, however, reveals practical limitations when this pattern is used for navigation menus. If <summary> is omitted from <details>, the browser is required to generate its own legend text like “Details.”

Marking up the element without a <summary>, though, results in invalid HTML per validators:

Include a <summary> and the markup validates cleanly:

The basic interaction works, but the semantics raise flags. Announced with assistive tech, <details> gives no clue about the interactive content within until the user opens it. And a collapsed <details> hides its content from find-in-page, save for modern Chromium.

Interactive Elements Inside <summary>

The question of whether <summary> may contain another interactive element, such as a link, remains an active issue in the WhatWG spec discussion. Markup like a link inside the summary:

<details>
  <summary><a href="...">Link element</a></summary>
</details>

<!-- or -->

<details>
  <summary><input></summary>
</details>

is technically valid, but creates significant accessibility trouble. Screen readers like JAWS fail to announce the nested link separately, giving the same result when keyboard focus moves through:

The link is not discoverable at all to JAWS when navigating with its virtual cursor. If navigating to the summary element via the Tab key, JAWS announces “example text, button” as the name and role of the element. If hitting Tab key again, JAWS again announces “example text, button” even though keyboard focus is on the link.

Validators confirm the content model currently allows such markup, even if the real-world experience is inconsistent or completely broken in screen readers.

Setting role=button on <summary> might seem like a workable fix for consistent announcements. Since button cannot contain interactive elements, that change would simplify the model. But Safari treats the element as a standard button once role=button is applied, dropping the expanded/collapsed state readout that a proper <summary> provides. The announced role becomes correct while the toggle state disappears entirely.

These inconsistencies leave plenty of room for debate about the intended mental model and browser vendor priorities. For developers, the lesson is about caution: before using <details> and <summary> for anything more than the simplest disclosure pattern, check how assistive technologies handle the content inside, and be mindful of what hidden content means for discoverability.