# Progressive disclosure Choose the right way to hold back secondary content, and keep what everyone needs on the page. Section: patterns Docs: https://nebula.kaluza.com/patterns/progressive-disclosure --- ## Overview Progressive disclosure keeps a page scannable by holding back information that only some users need, behind something they can open when they need it. Nebula has several components that do this and they aren't interchangeable. This pattern covers which one to use. Each component's own page covers how to use it. ## The core decision What to use depends on how much information you're holding back, and whether the user needs it beside the page or in place of it. - If it's one block of supporting detail, use [Disclosure](/components/disclosure). - If there are several such blocks and users pick between them, use [Accordion](/components/accordion). - If each one is a complete view of the same subject, use [Tabs](/components/tabs). - If it's too much for a Disclosure and leaving the page would lose the user's place, use [Modal](/components/modal). - If it's a long or multi-step task, give it a page. A short one can sit in a modal. - If it's a word or phrase that needs explaining, use [Tooltip](/components/tooltip). ## Principles ### Show what most users need If most users will need to see the information, it's better to show it on the page. That isn't a judgement about how critical the information is, but about how many users need it and how often they need it. ### Say what's behind the trigger The label is all a user has to go on when they decide whether to open something, so it needs to describe what's there. A trigger reading 'More information' makes them open it to find out whether they needed to. ### Remember that hidden content isn't searchable Find-in-page won't match text inside a collapsed Disclosure or Accordion, or inside an inactive tab panel. If users are likely to search the page for a term, keep that term in the visible text. ## Scenarios ### One block of supporting detail Use [Disclosure](/components/disclosure) for a single block of detail that a user reads in the context of what surrounds it. Keep the content modest. If you find yourself putting a heading, a form or a primary action inside one, the content has outgrown the component. ```tsx

The estimate uses the last three meter readings and the average consumption for similar properties in the area. It is replaced by an actual figure as soon as a new reading is submitted.

``` ### Several blocks the user picks between Use [Accordion](/components/accordion), inside an `AccordionGroup`, where there are several blocks of detail and the user chooses which to open. A set of frequently asked questions is the clearest case. The group is what makes it an Accordion rather than several Disclosures. If you only have one toggle, use a Disclosure, which carries less visual weight. ```tsx

Refunds reach the account they were paid from within five working days of approval.

Yes, up until the point the refund is approved. After that it has to be reversed and reissued.

``` ### Complete views of the same subject Use [Tabs](/components/tabs) where each view stands on its own and the user needs one at a time, such as payments and meter readings for one account. Tabs imply the views are peers, so they're wrong for detail that supports the page rather than divides it. They're also wrong where the user needs to see two views at once, which is a comparison rather than a disclosure. ```tsx Payments Meter readings

Four payments in the last six months, all collected on time.

Two readings submitted in the last six months, both estimated.

 ``` ### More detail without losing your place Use [Modal](/components/modal) where the detail is more than a Disclosure should carry and leaving the page would cost the user their place. Someone mid-call who navigates away from an account to read a policy note has lost the thing they were working on. What makes this reasonable is that the user opened it. The caution about modals is about interrupting someone, and a modal a user opened to see more doesn't interrupt anything. It's still the heaviest option here, because focus is held inside it and the page behind it is hidden from assistive technology. Use it where keeping context matters, not wherever a Disclosure felt too small. > **Expandable rows** - some Advanced Tables reveal a row's detail by expanding it in place, which is another reasonable way to keep the user where they are. Advanced Table isn't part of Nebula yet, so this guidance will be updated when it is. ### Working through a task A short task can sit in a modal, particularly where the user needs to stay in the context of the page behind it. If it's longer, or has several steps, give it a page instead. A multi-step form in a modal has nowhere to put a step in the URL, and nothing to return to if the user needs to check something else first. See [Multi-step tasks](/patterns/multi-step-tasks). ### A word or phrase explained in place Use [Tooltip](/components/tooltip) for a short gloss on something already on screen, and `DefinitionTooltip` where you're explaining jargon. A tooltip holds nothing interactive and users can miss it entirely on touch, so whatever is inside one needs to exist somewhere else too. That makes it the narrowest option here: a sentence at most, and never the only route to something. ```tsx

The account is on a{' '} fixed tariff {' '} until April.

``` Where the explanation belongs beside a label or a heading rather than inside a sentence, use `IconTooltip`. It renders its own info icon, which you can't change. ```tsx

Estimated annual cost

``` ### What to type into a field Use the field's own hint text, not a tooltip. Hint text is always visible, sits between the label and the input, and needs no discovery. See [Forms](/patterns/forms#labels-and-hints). If you're reaching for a tooltip on a form field, the label is usually doing too little work. Improve the label first. ## Accessibility - **Each component announces its own state.** Disclosure renders a native `details` and `summary`, so the browser supplies the expanded state without any props. See [Disclosure](/components/disclosure). - **Collapsed content is hidden from assistive technology as well as from view**, which is what makes hiding something everyone needs a barrier rather than a tidy-up. - **A tooltip is the least reachable option.** It doesn't take focus, it holds nothing interactive, and users can miss it on touch. See [Tooltip](/components/tooltip). - **Triggers are reached in reading order**, so if you put a Disclosure above the content it explains, it's announced before there's anything to explain. - **Nesting is ruled out**, for a Disclosure inside a Disclosure and an Accordion inside an Accordion. If content seems to need it, the hierarchy is too deep for disclosure at all. ## Copy guidance ### Name what's behind the trigger The label is the whole basis for deciding whether to open it. **Do:** How this estimate was calculated **Don't:** More information ### Write a trigger as a label, not a link A trigger that reads like navigation suggests the user will be taken somewhere, and they'll lose their place looking for the way back. **Do:** Payment methods we accept **Don't:** View payment methods ### Keep tooltip text to a sentence If it needs more than that, the content belongs in a Disclosure where it can be read properly. **Do:** A tariff whose unit rate is fixed for an agreed period. **Don't:** A fixed tariff is one where the unit rate you pay is agreed in advance and does not change for the length of the agreement, which protects you from price rises but also means you do not benefit from falls. ## Related - [Disclosure](/components/disclosure) - [Accordion](/components/accordion) - [Tabs](/components/tabs) - [Tooltip](/components/tooltip) - [Modal](/components/modal) - [Forms](/patterns/forms)