Chapter 43: Visually Hidden (Utility)

Core Idea

Hides content visually while keeping it in the accessibility tree — an alternative to aria-label/aria-labelledby when you want the actual text content (not just an attribute string) announced to assistive technology.

Key Concepts

• Root: single part; anything nested inside is visually hidden but still announced by screen readers.
• Used internally by other primitives: AccessibleIcon and Dialog's hide-title-visually pattern both build on this.

Code Examples

<button>
  <GearIcon />
  <VisuallyHidden.Root>Settings</VisuallyHidden.Root>
</button>

• What it demonstrates: labeling an icon-only button with real (hidden) text content instead of an aria-label attribute.

Key Takeaways

1. Prefer this over aria-label when the accessible name is naturally expressed as visible-looking text content (e.g. localized strings already rendered elsewhere) rather than a short attribute string.
2. This is the building block AccessibleIcon wraps — reach for AccessibleIcon directly for the common "label this icon" case, and VisuallyHidden directly for anything else that needs the same visual-hide-but-announce treatment (e.g. a hidden Dialog.Title).

Connects To

• Accessible Icon: built on top of this utility.
• Dialog / Alert Dialog: their Title/Description hide-visually pattern uses this.