# Progressive disclosure (/patterns/progressive-disclosure)



Show the controls most people need first. Put less common options behind a named disclosure when that makes the task easier to understand. Keep information needed to make the current decision visible.

<PatternIllustration pattern="progressive-disclosure" />

## Choose what to hide [#choose-what-to-hide]

Good candidates include optional advanced settings, detailed explanations, and secondary metadata. Keep required fields, errors, costs, and the consequences of an action visible when they affect the person's decision.

Use a concrete label such as “Advanced import settings” instead of “More” when the hidden content has a clear purpose. If a hidden option has been changed, show a short summary so the person can see that the default no longer applies.

## Expand within the page [#expand-within-the-page]

Use a [Button](/components/button) that identifies the controlled region. Expose its expanded state and keep the region immediately after the button in reading order. A chevron can reinforce the state, while the label explains what will be revealed.

When expanding, keep focus on the control unless the task requires an immediate move. Let the next keyboard step reach the newly visible content. When collapsing a region containing focus, return focus to the disclosure control. Hidden controls should leave the keyboard order.

## Preserve state and validation [#preserve-state-and-validation]

Keep entered values when the region closes. If a hidden field fails validation on submission, expand its region before directing the person to the error. Avoid requiring them to search through collapsed sections for a problem.

Remember an expanded state only when it helps the same task across visits. Reset it when changing to a different object would make the previous state confusing. For a long secondary task, consider a separate page or [Drawer](/components/drawer) with a clear return path.

## Motion and testing [#motion-and-testing]

Use a short transition that preserves the relationship between the button and the content. Respect [reduced motion](/foundations/motion#reduced-motion), and keep surrounding controls from jumping under the pointer.

Check opening and closing by keyboard, submitting with an error inside the hidden region, preserving an edited value, and using the page at narrow widths. Each path should make the additional controls discoverable without blocking the common task.