Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
visually-hidden · base base · style base-lyraOpen under the product theme

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

Theme
Density
Text
Status
Accent theme
Accent
visually-hidden-a-name-for-an-icon-button · base base · style base-lyraOpen under the product theme
visually-hidden-a-name-for-an-icon-button.tsx
import { 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>
  )
}

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.

Theme
Density
Text
Status
Accent theme
Accent
visually-hidden-context-for-a-repeated-link · base base · style base-lyraOpen under the product theme
visually-hidden-context-for-a-repeated-link.tsx
import { 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 link instead.
  • You are labelling a form input and want the label, the hint and the error wired together.Use field instead.
  • The words explain jargon and should be readable by everyone, not only by assistive technology.Use term instead.

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.
KeyActionNotes
TabSkips the hidden textNever a tab stop. A control placed inside keeps its own place in the order.
Shift+TabSkips the hidden text in reverseReverse order matches forward order, because there is nothing to stop on.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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.