Colour theme

ScreenReaderText

  • Primitives

Words for the accessible name only: read by assistive technology, never drawn. Always a span, because it is inline text that must not be seen — the pattern other systems call visually hidden. It is the one place the clip pattern lives; a component that needs hidden words renders this, and a component that needs to hide a control gates that itself, because a control must stay focusable.

An affix on a button

The visible words stay in the accessible name (WCAG 2.5.3, label in name); the hidden ones complete it before or after. Button carries the suffix as a prop and renders this component; a bare value like a page number takes both a prefix and a suffix.

astro
---
import LinkButton from "tsugite/Button/LinkButton.astro";
import ScreenReaderText from "tsugite/ScreenReaderText/ScreenReaderText.astro";
---
{/* The visible words stay in the name (WCAG 2.5.3, label in name); the hidden ones
    complete it. On Button the suffix is a prop; anywhere else it is the component. */}
<LinkButton href="#" screenReaderSuffix=" about the exhibition">Read more</LinkButton>
<button type="button"><ScreenReaderText text="Page " />3<ScreenReaderText text=" of 12" /></button>

Standalone

Under an icon the words are the whole name. Host attributes pass through, so a hidden span with aria-live is a status channel.

Search

Saved — the form was submitted at 13:45

astro
---
import ScreenReaderText from "tsugite/ScreenReaderText/ScreenReaderText.astro";
---
{/* The words are the whole accessible name; the icon is decoration and says so. */}
<a href="#">
  <svg width="24" height="24" aria-hidden="true" focusable="false"><circle cx="10" cy="10" r="7" fill="none" stroke="currentColor" stroke-width="2" /><path d="M15 15l6 6" stroke="currentColor" stroke-width="2" /></svg>
  <ScreenReaderText text="Search" />
</a>
<p>Saved <ScreenReaderText text="— the form was submitted at 13:45" aria-live="polite" /></p>

Refusals

Interactive content inside the hidden span — a link, a button, a field, anything with tabindex — is refused in development: it would take focus without being seen. Empty renders nothing. The element is always a span.

astro
---
import ScreenReaderText from "tsugite/ScreenReaderText/ScreenReaderText.astro";
---
{/* A link that cannot be seen can still take focus: a trap. Refused in development,
    nothing in production. Hiding a native control under a custom one is not this
    component's job either — that is the control's own gate, and it stays focusable. */}
<ScreenReaderText><a href="#">a hidden link</a></ScreenReaderText>

Test bench

The ScreenReaderText fixture — the three places hidden words belong and the one where they are refused, mounted unchanged.

ScreenReaderText

A suffix on a button

Visible "Read more"; accessible name "Read more about the exhibition".

Read more about the exhibition

A label under an icon

The words are the whole name; the icon is decoration.

Search

The unit a bare value lacks

Visible "3"; accessible name "Page 3 of 12".

A live region

Host attributes pass through: a hidden span with aria-live is a status channel.

Saved

Refused: interactive content

A link inside the hidden span would take focus without being seen. Visible error in development, nothing in production.