Docs / Helpers / Visually hidden

Visually hidden

Hide content from the screen while keeping it available to assistive technology. VisuallyHidden clips its children to a 1 px, off-screen box — the .visually-hidden helper — so screen readers still announce it. A focusable variant reveals the content when it receives keyboard focus, the standard pattern for skip links.

Import

import { VisuallyHidden } from '@metatoy/bootstrap-styled';

Example

Use it to give an icon-only control a spoken name. The star is hidden from the screen reader with aria-hidden, and the visually-hidden text supplies the accessible label — sighted users see only the icon, screen-reader users hear “Add to favorites”.

Focusable variant (skip links)

Pass focusable to render .visually-hidden-focusable: the content stays clipped until it is focused (or contains focus), then appears. This is the canonical skip-to-content link — render it as an anchor with as="a" and an href to the main region.

Props

VisuallyHidden renders a <span> by default and forwards native attributes plus a ref. When rendered as a link (as="a") it also accepts href, target, rel, and download.

Theming

Nothing to theme — the helper transcribes the exact Bootstrap clip pattern (width/height: 1px, margin: -1px, clip: rect(0,0,0,0), position: absolute) and inlines it, all with !important so it can’t be accidentally overridden. When focusable content is revealed on focus, it renders with your normal typography and link theme.

Accessibility

This helper is an accessibility tool — the correct way to provide text for assistive tech without showing it on screen. Key points:

• Prefer it over display: none or visibility: hidden, both of which remove content from the accessibility tree entirely.
• Pair icon-only controls (aria-hidden="true" on the glyph) with a VisuallyHidden label so the control has a spoken name.
• For skip links, place a focusable anchor as the first focusable element in the page and point its href at the id of your main content region.
• Content stays in the DOM and in the reading order, so keep it concise and meaningful.

Explore in Ladle

Open in Ladle (and the focusable variant).