Details

Details elements create expandable content sections that help organize information and reduce cognitive load. Use them to provide additional context, help text, or supplementary information that users can access on demand. The component supports both native browser styling and enhanced accordion-style presentation with custom icons.

Do

  • Use clear, descriptive summary text that accurately describes the hidden content.
  • Keep collapsed content scannable with concise summary labels that help users decide whether to expand.
  • Group related details logically when using multiple details elements on the same page.
  • Provide helpful context in expanded content that genuinely adds value to the user experience.
  • Use consistent styling throughout your site — choose either native or styled appearance and stick with it.
  • Consider progressive disclosure for complex forms or lengthy content sections.
  • Test with keyboard navigation to ensure smooth expand/collapse functionality.
  • Use for supplementary information that enhances but doesn't replace essential content.

Don’t

  • Don’t hide critical information that users need to complete their primary task.
  • Don’t use vague summary text like "More info" or "Click here" — be specific about the content.
  • Don’t create deeply nested details — keep the information hierarchy simple and logical.
  • Don’t overuse details elements — too many can make content feel fragmented and hard to navigate.
  • Don’t put essential form fields inside details elements where users might miss them.
  • Don’t use details for primary navigation — they’re for supplementary content, not main user paths.
  • Don’t forget mobile users — ensure details work well on touch devices with adequate touch targets.
  • Don’t mix styling approaches — maintain consistency between native and styled variants.

Default

Native browser-styled details element for help content. Demonstrates the unstyled variant that uses the browser's default disclosure triangle. Perfect for inline help text, form field explanations, or contextual guidance that doesn't need prominent visual treatment.

To achieve this style simply apply the details--expandable-content class to the element.

Help with community of residence

We ask for your current community of residence to determine which regional programs and services apply to you. If you live in a remote area or split your time between communities, use the location where you spend most of the year. This helps us direct your application to the right office.

Open example in a new tab

Styled

Enhanced accordion-style details with custom icons. Shows the styled variant with plus/minus icons that creates a more prominent, accordion-like appearance. Use this for more important supplementary content or when you need consistent visual styling across different browsers.

To achieve this style simply apply the details--accordion class to the element in addition to the details class.

Help with community of residence

We ask for your current community of residence to determine which regional programs and services apply to you. If you live in a remote area or split your time between communities, use the location where you spend most of the year. This helps us direct your application to the right office.

Open example in a new tab

Accessibility Best Practices

Screen Reader Support

  • Native semantics: Uses the HTML <details> and <summary> elements which provide built-in accessibility features.
  • Proper state announcement: Screen readers automatically announce expanded/collapsed states.
  • Logical content structure: Content within details maintains proper heading hierarchy and document flow.
  • Clear summary text: Summary elements contain descriptive text that explains the hidden content.

Keyboard Navigation

  • Full keyboard access: Details elements are natively keyboard accessible with Enter and Space keys.
  • Focus management: Focus moves logically between summary and content when expanded.
  • Standard interaction: Uses familiar browser keyboard shortcuts that users already know.
  • Tab navigation: Content within expanded details follows normal tab order.

Visual Accessibility

  • High contrast indicators: Expansion state is clearly visible through icons and visual cues.
  • Consistent focus states: Focus indicators work consistently across styled and unstyled variants.
  • Scalable icons: Custom icons scale appropriately with user font size preferences.
  • Clear visual hierarchy: Expanded content is visually distinct from surrounding page content.

Content Guidelines

  • Descriptive summaries: Write summary text that clearly explains what users will find when they expand.
  • Logical content organization: Structure expanded content with proper headings and paragraphs.
  • Scannable information: Use bullet points, short paragraphs, and clear language in expanded content.
  • Contextual relevance: Ensure details content directly relates to and supports the surrounding information.

Implementation Considerations

  • Progressive enhancement: Component works without JavaScript, relying on native browser functionality.
  • Cross-browser consistency: Styled variant provides consistent appearance across different browsers.
  • Performance optimization: Content is present in the DOM but hidden, so consider impact on page load.
  • Mobile optimization: Touch targets are appropriately sized for mobile interaction.

ARIA Attributes in Use

  • Native <details> and <summary> elements provide built-in ARIA semantics.
  • aria-expanded state is automatically managed by the browser.
  • Content is properly associated with its trigger through native HTML relationships.
  • No additional ARIA attributes needed due to semantic HTML structure.
Updated: Dec 02, 2025