Details

Accessibility and usability expectations

Cognition

• Provide clear, descriptive <Button> labels to help users understand what information is hidden/shown
• Keep content inside <Details> concise and relevant to avoid cognitive overload
• Consider defaulting critical content to expanded state for better discoverability if it's likely to be missed

Vision

• Ensure the visible <Button> label text, and the text that expands and becomes visible, meets the minimum contrast requirement of 4.5:1
• If the visible label is represented by an icon, ensure the icon has a 3:1 contrast ratio against the background

Mobility

• Ensure the <Button> element has a minimum target size of 24×24 CSS pixels. This is to ensure that the control is large enough to be easily activated by users with motor impairments

Adaptability

• The <Button> label, and the text that expands, should remain legible when resized up to 200%
• When zoomed to 400% or viewed at a width of 320px, content and functionality must remain fully available without horizontal scrolling
• When adding additional text spacing, make sure that the visible label and the expanded content can still be read in their entirety

Interaction

Keyboard

• Ensure the <Button> control is focusable and can be toggled using Enter or Space
• Focus should remain logical and not jump unexpectedly when expanding/collapsing
• When the details component contains a callback for clicking outside the component, ensure focus moves to the first focusable element within the dialog. E.g. the "O.K" button

Touch and mouse

• The <Button> control must be activated on the up event, and not the down event, or there must be a way to prevent the action from taking place on the down event

Engineering for Assistive Technology (AT) compatibility

Screen reader support

• The expanded/collapsed state should be announced (most modern screen readers support this natively)
• Provide context in the <Button> so the user knows what kind of content they’re revealing
• Avoid using <Details> for critical instructions or required information that should always be visible

Speech recognition

• The <Button> accessible name should match or include the visible label

Built-in accessibility features

• The <Button> element is focusable by default
• Its possible to expand and collapse the element using enter and/or space
• <Details> and <Button> are recognised as interactive disclosure widgets
• The <Button> automatically exposes a button like role to screen readers
• The expanded/collapsed state is implicitly conveyed via the aria-expanded attribute

Implementation requirements

• The <Button> element must be the first child of the <Details> element to ensure correct behaviour and browser compatibility
• Ensure the visible label is clear, descriptive, and provides meaningful context about the content being revealed
• Avoid using <Details> to hide essential or critical information, as hidden content may be easily missed or skipped by users, especially those using assistive technologies

How to test the component

Integration tests

• Ensure screen readers correctly announce the label and the expanded/collapsed state
• Confirm that important content isn't accidentally hidden when <Details> is collapsed

Component tests

• Ensure that clicking or pressing Enter/Space on the <Button> toggles the <Details> content
• Verify that the content is hidden by default and visible after toggle
• Ensure the <Button> element can receive focus with Tab and that it can be expanded/collapsed with keyboard