Skip to main content
On this page

Progressive disclosure

Choose the right way to hold back secondary content, and keep what everyone needs on the page.

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.
  • If there are several such blocks and users pick between them, use Accordion.
  • If each one is a complete view of the same subject, use Tabs.
  • If it's too much for a Disclosure and leaving the page would lose the user's place, use 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.

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 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.

Loading...
Edit live code
<Disclosure title="How this estimate was calculated">
  <P>
    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.
  </P>
</Disclosure>

Several blocks the user picks between​

Use 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.

Loading...
Edit live code
<AccordionGroup>
  <Accordion title="When will my refund arrive?">
    <P>
      Refunds reach the account they were paid from within five working days of
      approval.
    </P>
  </Accordion>
  <Accordion title="Can I change where my refund goes?">
    <P>
      Yes, up until the point the refund is approved. After that it has to be
      reversed and reissued.
    </P>
  </Accordion>
</AccordionGroup>

Complete views of the same subject​

Use 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.

Loading...
Edit live code
<Tabs>
  <TabList>
    <Tab>Payments</Tab>
    <Tab>Meter readings</Tab>
  </TabList>
  <TabPanel>
    <P>Four payments in the last six months, all collected on time.</P>
  </TabPanel>
  <TabPanel>
    <P>Two readings submitted in the last six months, both estimated.</P>
  </TabPanel>
</Tabs>

More detail without losing your place​

Use 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.

A word or phrase explained in place​

Use 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.

Loading...
Edit live code
<P>
  The account is on a{' '}
  <DefinitionTooltip tooltip="A tariff whose unit rate is fixed for an agreed period.">
    fixed tariff
  </DefinitionTooltip>{' '}
  until April.
</P>

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.

Loading...
Edit live code
<P>
  <span style={{ display: 'inline-flex', alignItems: 'center', gap: '0.25em' }}>
    Estimated annual cost
    <IconTooltip tooltip="Based on the last 12 months of usage at your current rates" />
  </span>
</P>

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.

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.
  • 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.
  • 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​