PrimitivesStable

VisuallyHidden

Parity report: docs/atoms.md

A wrapper that hides content visually but keeps it in the DOM for screen readers (position: absolute; clip-path: inset(50%) — the "sr-only" technique). as span (default) / div / p / label.

When to use

  • Giving a full accessible name to a link/button whose visible text is short ("See more →" + " about the August report").
  • Announcing a context change that's only obvious visually. Labeling a field with no visible label.
  • Hiding from everyone (visual and readers) → hidden / display: none. Hiding from readers only → aria-hidden.

Examples

A link's full name
sobre o relatório de agosto
the screen reader reads "See more about the August report, link"; on screen, just "See more →".
<a href="/relatorios/agosto">
  <span aria-hidden>Ver mais</span>
  <Icon icon={ArrowRight} size="sm" />
  <VisuallyHidden> sobre o relatório de agosto</VisuallyHidden>
</a>
Inline in text

O texto (este trecho só é lido por leitores de tela) ao redor continua visível. Inspecione o DOM para ver o span oculto.

<p>
  O texto <VisuallyHidden>(só é lido por leitores de tela)</VisuallyHidden> ao redor continua visível.
</p>

Props

PropTypedefaultDescription
as"span" | "div" | "p" | "label"—Elemento renderizado. Default `"span"`.

Accessibility

  • The content stays in the accessibility tree and the reading order — so write text that makes sense read aloud, in the position where it sits.
  • Don't put focusable elements inside (a link hidden this way becomes an invisible focus trap).