Accessibility pattern · Disclosure and content

Show more

A real button with aria-expanded shows or hides the rest of the text, and focus stays on the button. The hidden part comes straight after the button and uses hidden="until-found", so find-in-page still reaches every word.

WCAG criteria
6
Keyboard rules
2
Checked with
axe, keyboard and the inspector
Try it Copy the code All patterns

Live demo

Try it

Use it with a mouse, a keyboard or a screen reader. The inspector beside it shows what the browser tells assistive technology as you go: focus, state changes and announcements.

Handwoven in Varanasi

Banarasi silk saree, peacock blue

₹18,400

Woven by hand on a pit loom, this saree pairs a peacock-blue body, scattered with small gold motifs, with a broad zari border. It drapes softly and holds its pleats through a long day.

Care and storage

Dry clean only. Store it folded in muslin, away from damp, and refold it along new lines every few months so the zari does not crack.

The demo works without JavaScript only as far as its HTML does; the inspector needs JavaScript.

Keyboard

Keys it answers to

Every action works without a pointer.

KeyWhat it does
TabMoves from More about this saree to Care and storage; a link in the revealed text would come in between.
Enter or SpaceShows or hides the text the focused button or summary controls; focus stays where it is.

Screen readers

What it announces

Written from the roles, names and states in the markup.

WhenExpected announcement
Focus reaches the buttonMore about this saree, button, collapsed
Enter shows the restExpanded
Reading on from the buttonEach saree takes one weaver about three weeks…
Focus reaches the details summaryCare and storage, button, collapsed
Find-in-page matches hidden textThe text is revealed and the button reports expanded

These are expected announcements, not recordings. Wording and order differ between screen readers and browsers.

Code

Copy the code

The exact files this demo runs on. The styles are served with a prefix that keeps this site's own styles out of the demo; what you copy is the original.

The markup

<div class="ap-disclosure" data-ap-disclosure>
  <div class="ap-disclosure__layout">
    <div class="ap-disclosure__swatch" aria-hidden="true">
      <svg viewBox="0 0 200 200" preserveAspectRatio="xMidYMax slice" focusable="false">
        <defs>
          <pattern id="disc-butti" width="40" height="36" patternUnits="userSpaceOnUse">
            <path class="ap-disclosure__butti" d="M20 10l5 8-5 8-5-8ZM0-8l5 8-5 8-5-8ZM40-8l5 8-5 8-5-8ZM0 28l5 8-5 8-5-8ZM40 28l5 8-5 8-5-8Z"/>
          </pattern>
          <pattern id="disc-zari" width="14" height="42" patternUnits="userSpaceOnUse">
            <path class="ap-disclosure__zari-line" d="M0 25l7-8 7 8"/>
          </pattern>
        </defs>
        <rect class="ap-disclosure__silk" width="200" height="200"/>
        <rect width="200" height="136" fill="url(#disc-butti)"/>
        <rect class="ap-disclosure__zari" y="158" width="200" height="42"/>
        <rect y="158" width="200" height="42" fill="url(#disc-zari)"/>
        <path class="ap-disclosure__zari-line" d="M0 164h200M0 194h200"/>
      </svg>
    </div>

    <div class="ap-disclosure__body">
      <p class="ap-disclosure__kicker">Handwoven in Varanasi</p>
      <h3 class="ap-disclosure__name">Banarasi silk saree, peacock blue</h3>
      <p class="ap-disclosure__price">₹18,400</p>

      <p class="ap-disclosure__intro">Woven by hand on a pit loom, this saree pairs a peacock-blue body, scattered with small gold motifs, with a broad zari border. It drapes softly and holds its pleats through a long day.</p>
      <button type="button" class="ap-disclosure__toggle" aria-expanded="false" aria-controls="disc-more">
        <span>More about this saree</span>
        <svg class="ap-disclosure__chev" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m6 9 6 6 6-6"/></svg>
      </button>
      <div class="ap-disclosure__more" id="disc-more" hidden="until-found">
        <div class="ap-disclosure__more-in">
          <p>Each saree takes one weaver about three weeks. Small changes in the weave are the mark of a handloom, not flaws.</p>
          <dl class="ap-disclosure__facts">
            <div><dt>Fabric</dt><dd>Katan silk with zari</dd></div>
            <div><dt>Length</dt><dd>5.5 m, with a 0.8 m blouse piece</dd></div>
            <div><dt>Weight</dt><dd>About 650 g</dd></div>
          </dl>
        </div>
      </div>

      <details class="ap-disclosure__details">
        <summary class="ap-disclosure__summary">
          <span>Care and storage</span>
          <svg class="ap-disclosure__chev" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m6 9 6 6 6-6"/></svg>
        </summary>
        <div class="ap-disclosure__details-in">
          <p>Dry clean only. Store it folded in muslin, away from damp, and refold it along new lines every few months so the zari does not crack.</p>
        </div>
      </details>
    </div>
  </div>
</div>

WCAG 2.2

What it meets

The success criteria this pattern takes care of, and how.

  • 1.3.2 Meaningful Sequence Level A

    The revealed text comes straight after the button in the source, so reading on from the button reaches it first.

  • 2.1.1 Keyboard Level A

    Both versions open and close with Enter or Space; nothing depends on a pointer.

  • 2.4.3 Focus Order Level A

    Focus stays on the button when the text opens, and the next Tab goes into what was revealed.

  • 2.4.7 Focus Visible Level AA

    The button and the summary show a two-pixel focus ring that clears 3:1 against the card.

  • 2.5.8 Target Size (Minimum) Level AA

    The button and the summary row are at least 44 pixels high, well over the 24-pixel minimum.

  • 4.1.2 Name, Role, Value Level A

    aria-expanded on the button, and the open state of details, are exposed, so the state is announced as it changes.

Usage

When to use it

Use it

  • Long descriptions where most people need the first paragraph and some want the rest.
  • Secondary detail on a busy page: specifications, care instructions, terms.

Use something else

  • Text people need in order to decide or stay safe, like fees or warnings: show it.
  • Several related sections people scan: an accordion groups them.
  • Long lists of items: use pagination or a feed with Load more.

Common failures

How it usually goes wrong

  • Clamped with CSS alone

    line-clamp hides lines on screen, but a screen reader still reads every word, so the button promises something it does not do. Here the rest is hidden for everyone until asked for.

  • A link that goes nowhere

    An a href="#" announces a link, jumps to the top of the page when the script fails and has no expanded state. A button is the right element.

  • Text added above the button

    If the new text appears before the button, a screen reader user who pressed it has to go back to find it. Here it follows the button.

  • A label that says the state twice

    Swapping Show more for Show less while also setting aria-expanded gives "Show less, expanded". The name here describes the content and never changes.

  • A sentence cut in half

    Splitting a sentence around the button leaves two fragments that make sense to nobody. Cut at the end of a paragraph.

  • Hidden text find-in-page cannot reach

    Text hidden with display: none is invisible to Ctrl+F. hidden="until-found" and details both let the browser find the text and open it.

Notes

Building it

  • Use details and summary when the disclosure needs no script; use a button with aria-expanded when the trigger must sit apart from the content or be styled freely.
  • Many CSS resets set [hidden] { display: none !important }, which turns until-found back into plain hidden. The stylesheet restores display and content-visibility for the panel.
  • beforematch fires just before the browser reveals the text; the script uses it to set aria-expanded, so the button tells the truth.
  • hidden="until-found" and opening details on a find-in-page match work in Chromium browsers; elsewhere the text simply stays hidden until the button is used.
  • Don't move focus into the revealed text: people asked for more and will read on from where they are.

Sources: WAI-ARIA Authoring Practices: Disclosure · HTML: the details element · HTML: the hidden attribute

Checked with axe in light and dark themes, at desktop and phone widths, and by keyboard. Not yet tested with every screen reader and browser pair. Report a correction

Related

  • Accordion

    Stacked headings that each show or hide a panel, so a long page reads as a short list.

    5 WCAG criteria4 keyboard rules

  • FAQ

    Questions grouped by topic that open their answers, with live search, expand all, and links that open any question.

    6 WCAG criteria4 keyboard rules

  • Toggletip

    An info button that shows a short note when pressed and has it announced, for help that a label cannot hold.

    6 WCAG criteria3 keyboard rules

  • Feed with load more

    A stream of posts people read in order, with keys to move post by post, a Load more button and new posts that wait.

    7 WCAG criteria6 keyboard rules