VisuallyHidden

The VisuallyHidden component hides its content from sighted users while keeping it available to screen readers. Use it to include accessible names, descriptions, or helper text without affecting visual layout.

Features

• Hides content visually, preserves it for screen readers and assistive tech
• Works with any inline content
• Useful for accessible names, button text, and non-visual instructions
• Accepts standard span props (e.g., className, style)

Usage

import { VisuallyHidden } from '@loke/ui/visually-hidden';

export default function Example() {
  return (
    <button type="button">
      <VisuallyHidden>Save the file</VisuallyHidden>
      <span aria-hidden>💾</span>
    </button>
  );
}

Tip:

• Pair with a visual-only icon and hide the text for screen readers using VisuallyHidden — or vice‑versa, make the icon aria-hidden and rely on hidden text for the accessible name.

Props

Examples

Basic (icon button with accessible text)

<button type="button">
  <VisuallyHidden>Save the file</VisuallyHidden>
  <span aria-hidden>💾</span>
</button>

Hidden label for input

<label htmlFor="email">
  <VisuallyHidden>Email address</VisuallyHidden>
</label>
<input id="email" type="email" placeholder="email@example.com" />

Additional context without visual clutter

<button type="button">
  Subscribe
  <VisuallyHidden>to our product updates newsletter</VisuallyHidden>
</button>

Custom styles (still visually hidden)

<CustomStylesVisuallyHiddenExample />

Accessibility

The component applies a set of CSS properties that:

• Remove the element from visual flow without removing it from the accessibility tree
• Reduce the element’s rectangle to 1×1px and clip its content
• Prevent layout shifts and accidental exposure

This approach is widely used in production frameworks and aligns with best practices.

Best practices

• Use for concise text that improves the accessible name or description of a control
• Avoid hiding large blocks of content; keep it short and meaningful
• Prefer VisuallyHidden for labels on icon‑only controls instead of relying solely on aria-label (either approach is acceptable, but hidden text can be easier to localize and manage)
• Don’t hide critical information that sighted users also need
• Combine with aria-hidden on decorative icons to avoid duplicate announcements