---
title: "VisuallyHidden"
description: "Content that screen readers announce and eyes do not see, such as the name of a button that shows only an icon."
url: "https://opsinjs.pensievelabs.org/docs/components/visually-hidden"
source: "https://opsinjs.pensievelabs.org/docs/components/visually-hidden.md"
section: "Components"
status: "shipped"
kind: "component"
category: "utility"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["sr only", "screen reader only", "clip"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="visually-hidden"
  status="shipped"
  questions="[
  &#x22;Nobody has listened to this component in VoiceOver, NVDA, JAWS or TalkBack, so announcement everywhere is argued from the clip pattern rather than measured.&#x22;,
  &#x22;Whether the component should refuse or warn when a focusable control sits inside it is unsettled, so an always-hidden keyboard trap is not prevented.&#x22;,
  &#x22;The contrast report is empty because nothing is painted, so a reviewer must read it as nothing to measure rather than a gap left unfilled.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="visually-hidden" unbuilt="false" importPath="@/components/ui/visually-hidden" />

```tsx
import { VisuallyHidden } from "@/components/ui/visually-hidden"
```

```tsx
<button type="button">
  <XIcon aria-hidden="true" />
  <VisuallyHidden>Close the panel</VisuallyHidden>
</button>
```

## Examples [#examples]

<ComponentPreview name="visually-hidden" />

### A name for an icon-only button [#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`.

<ComponentPreview name="visually-hidden-a-name-for-an-icon-button" kind="example" align="start" />

### Context for a repeated link [#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.

<ComponentPreview name="visually-hidden-context-for-a-repeated-link" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Give an icon-only control an accessible name, by putting the words the icon stands for inside it.&#x22;,
  &#x22;Add context a sighted reader gets from layout, such as the subject of a repeated \&#x22;Read more\&#x22; link.&#x22;,
  &#x22;Provide a heading or a label for a region that reads clearly to the eye without one.&#x22;,
]"
  avoid="[
  { case: &#x22;The content must become visible when it receives focus, which is how a skip link works.&#x22;, instead: &#x22;link&#x22; },
  { case: &#x22;You are labelling a form input and want the label, the hint and the error wired together.&#x22;, instead: &#x22;field&#x22; },
  { case: &#x22;The words explain jargon and should be readable by everyone, not only by assistive technology.&#x22;, instead: &#x22;term&#x22; },
]"
/>

## Accessibility [#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.

<KeyboardTable
  name="visually-hidden"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the hidden text&#x22;,
    notes: &#x22;Never a tab stop. A control placed inside keeps its own place in the order.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the hidden text in reverse&#x22;,
    notes: &#x22;Reverse order matches forward order, because there is nothing to stop on.&#x22;,
  },
]"
/>

<ContrastReport component="visually-hidden" />

## Props interface [#props-interface]

<PropsTable name="VisuallyHiddenProps" />

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