Skip to main content

Visually Hidden

Render content that screen readers announce and sighted users never see.

When to use

  • State context the visual design already carries: "(opens in a new tab)" on an external link, a caption on a layout table.
  • Give a screen reader a text alternative for content it cannot read, such as a decorative chart.
  • Style the message of a LiveRegion, which builds on the same technique.
  • Prefer aria-label to name an icon-only control, as IconButton's required label prop does. Voice-control software skips a control whose only label is hidden DOM text.
  • Prefer the hidden attribute or aria-hidden to hide content from assistive technology too.
  • Prefer SkipToMainLink for a link that appears on focus.

Polymorphism

VisuallyHidden accepts an asChild prop. When true, it renders its single child instead of its default <span>, forwarding its class names, data-* attributes, and ref onto that child. When the hidden content should be a more semantic element (a <caption>, a <legend>, a heading), reach for asChild.

How it hides content

VisuallyHidden renders a native <span> clipped to a one-pixel box (the sr-only technique, never display: none). Screen readers read the content, and sighted users never see it. The content also stays in copied and searched text.

API Reference

VisuallyHidden

All props from span, plus:

PropTypeDefaultDescription
asChild?booleanfalseUse the asChild prop to compose the VisuallyHidden hiding onto alternative element types or your own React components.
children?ReactNodeThe content read to screen readers.
className?stringAdditional CSS classes to apply to the hidden element.

Data attributes

Data AttributeValueDescription
data-slot"visually-hidden"Stamped on the rendered element, and joined onto the child via asChild.