Details

Props

• summary: string (required) -- text displayed in the summary toggle
• open: boolean (default: false) -- whether the details section is expanded; bindable
• children: slot (required) -- content revealed when expanded

Keyboard Interactions

• Enter or Space: toggles the disclosure open/closed when the <summary> element is focused (native browser behavior)

ARIA

• Native <details> and <summary> elements provide built-in ARIA semantics
• The browser automatically exposes the expanded/collapsed state to assistive technology
• No additional ARIA attributes are needed because the native elements handle accessibility

When to Use

• Use to make a page easier to scan by hiding supplementary information that only some users need
• Use to provide contextual help within forms, such as "Why are we asking this question?"
• Use when the summary text clearly indicates what information is hidden beneath
• Use for secondary guidance that supports but is not essential to the main content

When Not to Use

• Do not use to hide information that the majority of users need — keep essential content visible
• Do not use when the hidden content is critical for task completion — it may be missed
• Do not use when you need more visual prominence for the expandable content — use Expander instead
• Do not use in transactional forms where users may fear clicking will lose their progress — consider showing the information inline

Headless

This headless component provides native <details> and <summary> elements with built-in browser accessibility, including automatic expanded/collapsed state announcements. It supports two-way binding on the open prop. The consumer provides all visual styling for the summary toggle and expanded content area.

Styles

The consumer provides all CSS styling. The component renders with a .details class for targeting. No default styles are included — this is a fully headless component.

Testing

• Verify the component renders a <details> element with class details
• Verify keyboard interactions work correctly
• Verify pass-through attributes are applied

Advice

• Designers: Make the summary text descriptive enough that users understand what content will be revealed. Use visual cues (such as a chevron icon) to indicate expandability.
• Developers: Use the bindable open prop to synchronize state with parent components. Avoid nesting multiple levels of Details deeply, as it can create confusing navigation.

Implementation Notes

• Renders native <details> and <summary> HTML elements for built-in browser accessibility
• Supports two-way binding on the open prop for two-way state synchronization on the open prop
• The summary prop provides the clickable toggle text
• Accepts a children slot for the expandable content area
• Spreads restProps onto the <details> element for consumer customization
• Similar to Collapsible but uses a more generic, standards-based API

Related components

• collapsible — a container that can be expanded or collapsed
• expander — a control that expands to reveal more content
• accordion-list-item — an accordion list item component
• summary-box — a boxed callout highlighting key takeaways or next steps from a longer page

References

• MDN details element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
• MDN summary element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary
• WAI-ARIA Disclosure Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/