VisuallyHidden

Renders content that is available to assistive technology but hidden from view. Use it for screen-reader-only labels, `aria-live` announcements, and "skip" affordances. The hiding styles are intentionally not customizable — `className` and `style` are not accepted — but accessibility-relevant props (`aria-*`, `role`, `id`, `data-*`, event handlers) pass through to the root element.

Examples

Default

This text is only announced by screen readers.

<VisuallyHidden>
  This text is only announced by screen readers.
</VisuallyHidden>

Icon Only Control Label

★Add to favorites

<button
  className={css({
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    w: '10',
    h: '10',
    borderWidth: '1px',
    borderColor: 'border',
    rounded: 'md',
    cursor: 'pointer',
  })}
  type="button">
  <span aria-hidden="true">★</span>
  <VisuallyHidden>Add to favorites</VisuallyHidden>
</button>

Inline With Visible Text

Uploaded 5 GBgigabytes of data.

<Text as="p" type="body">
  Uploaded 5 <span aria-hidden="true">GB</span>
  <VisuallyHidden>gigabytes</VisuallyHidden> of data.
</Text>

Live Region Announcer

Add item

0 items added (this text is visible; the announcement below is not).

function LiveRegionAnnouncer() {
  const [count, setCount] = useState(0);

  return (
    <div
      className={css({display: 'flex', flexDirection: 'column', gap: '3'})}>
      <Button label="Add item" onClick={() => setCount(value => value + 1)} />
      <Text as="p" type="body">
        {count} item{count === 1 ? '' : 's'} added (this text is visible; the
        announcement below is not).
      </Text>
      <VisuallyHidden aria-live="polite" as="div" role="status">
        {count === 0 ? '' : `${count} items in the list`}
      </VisuallyHidden>
    </div>
  );
}

API

VisuallyHidden

Renders content that is available to assistive technology but hidden from view. Use it for screen-reader-only labels, `aria-live` announcements, and "skip" affordances. The hiding styles are intentionally not customizable — `className` and `style` are not accepted — but accessibility-relevant props (`aria-*`, `role`, `id`, `data-*`, event handlers) pass through to the root element.

Prop	Type	Default	Description
as	"div" | "label" | "p" | "span"	—	Element rendered as the root. Default is span. Use div (or another block element) for block content and aria-live regions.
children	ReactNode	—
data-testid	string	—	Test id applied to the root element.
ref	Ref<HTMLElement>	—	Ref forwarded to the root element.