ScreenReaderText
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.
---
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.
Saved — the form was submitted at 13:45
---
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.
---
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 exhibitionA label under an icon
The words are the whole name; the icon is decoration.
SearchThe 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.
SavedRefused: interactive content
A link inside the hidden span would take focus without being seen. Visible error in development, nothing in production.