Skip to main content
Join the waitlist

VisuallyHidden

Keeps text in the accessibility tree while taking it off the screen.

import { VisuallyHidden } from "@usefragments/ui";Source

Preview

import { MagnifyingGlass } from '@phosphor-icons/react';
import { Button } from '@usefragments/ui';
import { VisuallyHidden } from '@usefragments/ui';

<Button variant="ghost">
  <MagnifyingGlass aria-hidden />

Usage

Use when

  • An icon-only control needs a name
  • A link's text is vague out of context
  • A skip link needs to hide until focused

Avoid when

  • Nobody should see or hear it (render nothing)
  • The content is just collapsed (use aria-expanded)

Implementation notes

  • Every icon-only button gets one
  • Say the action, not the icon: "Search", not "magnifier"
  • Keep it short — it is read aloud
  • Visible text beats hidden text whenever there is room
  • A skip link uses focusable, so it shows while it holds focus

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

Supplementary Text

Gives a vague link the context sighted readers get from layout.

import { Link } from '@usefragments/ui';
import { VisuallyHidden } from '@usefragments/ui';

<Link href="#features">
  Read more
  <VisuallyHidden> about our accessibility features</VisuallyHidden>

Skip Link

Hidden until focused, then it shows as a chip and jumps keyboard users past the nav.

import { VisuallyHidden } from '@usefragments/ui';

<VisuallyHidden focusable>
  <a href="#main-content">Skip to main content</a>
</VisuallyHidden>

API reference

Component props
Prop
Type
Default
Description
as"div" | "span" | undefineddivspanspanHTML element to render
childrenRequiredReact.ReactNodeNot setContent to hide visually
focusableboolean | undefinedfalseReveal the content while focus is inside it, as a chip (surface plane, strong hairline, control height, control radius, focus ring) pinned to the top inline-start corner. Use it for skip links.

Accessibility

  • Screen readers announce it; the layout never moves
  • Focusable children inside still receive focus; with focusable they also become visible
  • Required for WCAG 2.1 on icon-only controls

Related components

  • ButtonchildUse inside icon-only buttons for accessible labels
  • IconsiblingPair with icons to provide text alternatives

Next steps