semantic pattern · Progressive disclosure
Disclosure
A button that controls whether one related region of content is visible or hidden.
Decisive boundary
If several titled sections form one structure, use an Accordion.
Definition and intent
What is a Disclosure UI pattern?
Use the behavior, not the silhouette
A button that controls whether one related region of content is visible or hidden. The term is used here as a semantic pattern whose role and interaction contract carry more meaning than its appearance. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.
Let users reveal optional details without navigating or opening a floating surface. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.
Know when the label is wrong
The fastest way to identify a pattern is often to reject the nearest alternative. For Disclosure, the boundary is: If several titled sections form one structure, use an Accordion.
Do not implement it as Accordion for a single relation and Collapsible as a substitute for semantic control labeling. If those requirements describe the real task better, use the related pattern page or the full Progressive disclosure comparison before writing code.
Decision process
Decide before choosing a component
Record these requirements in plain language. A library component name is not a substitute for the contract.
Confirm the user job
Let users reveal optional details without navigating or opening a floating surface.
Define opening and closing
A button associated with one content region. The same button hides the region when collapse is allowed.
Specify access behavior
Focus stays on the controlling button after toggling. Enter or Space activates the button.
Reject the near miss
Accordion for a single relation and Collapsible as a substitute for semantic control labeling.
Behavior contract
What must survive the build
- trigger
- A button associated with one content region.
- dismissal
- The same button hides the region when collapse is allowed.
- modality
- Non-modal inline behavior.
- focus
- Focus stays on the controlling button after toggling.
- keyboard
- Enter or Space activates the button.
- interactive
- The revealed region can contain normal content and controls.
- persistence
- State may persist during the current task if helpful.
- placement
- The controlled region is logically related to the button.
- mobile
- Use a clear label that communicates both content and state.
Failure modes
Common wrong builds
- Using a link that does not navigate.
- Failing to expose expanded state.
- Moving focus into the revealed content without reason.
Observable checks
Verify the result
- The controller is a button.
- Expanded state is exposed.
- The controlled region is correctly referenced.
- Focus stays predictable.
- The label remains understandable in both states.
Coding-agent handoff
Implementation brief template
Pattern: Disclosure Purpose: Let users reveal optional details without navigating or opening a floating surface. Trigger: A button associated with one content region. Dismissal behavior: The same button hides the region when collapse is allowed. Modality: Non-modal inline behavior. Focus behavior: Focus stays on the controlling button after toggling. Keyboard behavior: Enter or Space activates the button. Interactive content: The revealed region can contain normal content and controls. Placement: The controlled region is logically related to the button. Mobile behavior: Use a clear label that communicates both content and state. Do not implement as: Accordion for a single relation and Collapsible as a substitute for semantic control labeling. Acceptance checks: - The controller is a button. - Expanded state is exposed. - The controlled region is correctly referenced. - Focus stays predictable. - The label remains understandable in both states.
Claim-level references
Sources, not a confidence score
Frequently asked questions
Disclosure UI pattern questions
Direct answers based on the reviewed behavior contract above.
What is a Disclosure in web UI?
A button that controls whether one related region of content is visible or hidden. In this reference set it is a semantic pattern whose role and interaction contract carry more meaning than its appearance.
When should I use a Disclosure?
Let users reveal optional details without navigating or opening a floating surface. The decisive boundary to confirm is this: If several titled sections form one structure, use an Accordion.
What keyboard and focus behavior does a Disclosure need?
Enter or Space activates the button. Focus stays on the controlling button after toggling. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.
How should a Disclosure behave on mobile?
Use a clear label that communicates both content and state. Its modality is a separate requirement: Non-modal inline behavior.
How do I verify a Disclosure implementation?
Start with observable checks: The controller is a button. Expanded state is exposed. The controlled region is correctly referenced. Then verify the remaining checks and compare the result with the linked source guidance.