Components
VisuallyHidden
Content that screen readers announce and eyes do not see, such as the name of a button that shows only an icon.
Usage
pnpm dlx shadcn@latest add @opsinjs/visually-hidden
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { VisuallyHidden } from "@/components/ui/visually-hidden"<button type="button">
<XIcon aria-hidden="true" />
<VisuallyHidden>Close the panel</VisuallyHidden>
</button>Examples
visually-hidden · base base · style base-lyraOpen under the product themeA name for an icon-only button
The button shows only a cross. The words inside VisuallyHidden become its accessible
name, and the icon is aria-hidden.
visually-hidden-a-name-for-an-icon-button · base base · style base-lyraOpen under the product themeimport { X } from "lucide-react"
import { VisuallyHidden } from "@/components/ui/visually-hidden"
export default function VisuallyHiddenANameForAnIconButton() {
return (
<button
type="button"
className="inline-flex min-h-(--opsin-target-minimum,2.75rem) min-w-(--opsin-target-minimum,2.75rem) items-center justify-center rounded-opsin-md border border-border bg-card text-card-foreground focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)] focus-visible:outline-ring"
>
<X aria-hidden="true" className="size-opsin-5" />
<VisuallyHidden>Close the example panel</VisuallyHidden>
</button>
)
}Context for a repeated link
Three rows end in the same two words, which a screen reader can list out of context. Appending the subject inside VisuallyHidden names each link without changing a pixel.
visually-hidden-context-for-a-repeated-link · base base · style base-lyraOpen under the product themeimport { VisuallyHidden } from "@/components/ui/visually-hidden"
const ARTICLES = [
"Keeping a simple daily log",
"What an estimate is and what it is not",
"Reading a range without a verdict",
] as const
export default function VisuallyHiddenContextForARepeatedLink() {
return (
<ul className="m-0 flex list-none flex-col gap-opsin-4 p-0">
{ARTICLES.map((title) => (
<li key={title} className="flex flex-col gap-opsin-1">
<span className="text-opsin-body [color:var(--foreground)]">{title}</span>
<a
href="#example"
className="w-fit text-opsin-body underline underline-offset-2 [color:var(--foreground)] focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)] focus-visible:outline-ring"
>
Read more<VisuallyHidden> about {title}</VisuallyHidden>
</a>
</li>
))}
</ul>
)
}When to use it
Use it when
- Give an icon-only control an accessible name, by putting the words the icon stands for inside it.
- Add context a sighted reader gets from layout, such as the subject of a repeated "Read more" link.
- Provide a heading or a label for a region that reads clearly to the eye without one.
Do not use it when
- The content must become visible when it receives focus, which is how a skip link works.Use
linkinstead. - You are labelling a form input and want the label, the hint and the error wired together.Use
fieldinstead. - The words explain jargon and should be readable by everyone, not only by assistive technology.Use
terminstead.
Accessibility
Content is announced because the span is clipped, not display:none,
visibility:hidden or the hidden attribute, each of which removes content from the
tree. The clip was checked against the WebAIM sr-only reference and stays hidden
through 200% text and increased text spacing, because neither touches its overflow and
clip-path. It
paints nothing and sets no colour or type size, so there is nothing to reflow at 200%
text, and as text rather than a control it is never focusable or a tab stop. Axe,
target size, focus visibility and reflow at 320px raised nothing.
The audit added a development-only warning when a focusable control sits inside the always hidden clip, a keyboard trap with no visible focus ring. The component walks its children to find one, and the warning changes no markup, class or visual output.
Residual items.
- No gate checks whether VoiceOver, NVDA, JAWS and TalkBack announce the content.
- Whether hidden text duplicates a visible name beside it is a per-usage question the component cannot see, so it stays a concern for the caller.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the hidden text | Never a tab stop. A control placed inside keeps its own place in the order. |
| Shift+Tab | Skips the hidden text in reverse | Reverse order matches forward order, because there is nothing to stop on. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from VisuallyHiddenProps in registry/bases/base/visually-hidden.tsx.
children is required. Empty children, an empty string, undefined or false raise
a development warning naming the mistake, and the span still renders. className
reaches the span for positioning, and a class that makes the content visible defeats
the component.