Import VisuallyHidden, VISUALLY_HIDDEN_ELEMENTS from @prepared911/ui/visually-hidden.
as
Choose a tag from VisuallyHiddenElement: span (default) or div.
children
Content rendered inside the element. The fixed hiding CSS applies regardless of content, including a long unbroken string.
Forwarded native props
id, lang, dir, title, ARIA attributes other than role, aria-label, and aria-labelledby, and data-* (other than a reserved design-system state name; see below) pass through unfiltered. ref is typed to the host element for the chosen as. Every other native attribute for the rendered tag passes through, except className, style, tabIndex, contentEditable, aria-hidden, aria-label, aria-labelledby, hidden, inert, role, and every on* handler, which are dropped even when cast in past the type system.
aria-hidden, aria-label, aria-labelledby, hidden, inert, and role
Not props (Decision VH-7), and declared as never rather than only omitted, so a value assigned to any of them is a JSX type error, not merely a missing one. aria-hidden="true", hidden, and inert would each remove VisuallyHidden's content from the accessibility tree; the opposite of what the primitive exists to do, and a silent one (WCAG 4.1.2: an icon-only button relying on this text for its name would lose that name with no error); dropping any of these three at runtime also warns once in development. role is excluded so a caller cannot replace the fixed hiding semantics with different assistive-technology behavior (also warned once when dropped). With role fixed, the host's implicit ARIA role is always generic, and ARIA 1.2 does not compute an accessible name for a generic element, so aria-label and aria-labelledby are excluded too; dropped silently, since there is no equivalent loss-of-function to call out. To name a region VisuallyHidden's content labels, use aria-labelledby on the other element, pointed at VisuallyHidden's id.
Reserved data-* names
A data-* name reserved for design-system state (src/models/state.ts's reservedStateDataAttributes, for example data-orientation or data-open) is dropped at runtime and warned about once in development, the same way Box drops one.
What is fixed, not a prop
The hiding CSS (position: absolute, a 1px box, a matching negative margin, overflow: hidden, clip: rect(0 0 0 0), clip-path: inset(50%), white-space: nowrap, border-style: none, pointer-events: none) is not configurable. There is no prop to change it, and there is no className to override it.
Props
Prop
Default
Meaning
children
Content rendered inside the element. The fixed hiding CSS applies regardless of content.
as
Element to render. Defaults to span.
ref
Ref to the rendered element.
aria-hidden
Would remove hidden content from the accessibility tree (WCAG 4.1.2). Not a prop.
aria-label
ARIA 1.2 prohibits naming a generic element, which is what role being fixed makes the host. Not a prop.
aria-labelledby
Same reason as aria-label. Not a prop.
hidden
Would remove hidden content from the accessibility tree (WCAG 4.1.2). Not a prop.
inert
Would remove hidden content from the accessibility tree (WCAG 4.1.2). Not a prop.
role
Would replace the fixed hiding semantics with different assistive-technology behavior. Not a prop.
Props
Name
Type
Default
Description
aria-hidden
undefined
—
Would remove hidden content from the accessibility tree (WCAG 4.1.2). Not a prop.
aria-label
undefined
—
ARIA 1.2 prohibits naming a generic element, which is what role being fixed makes the host. Not a prop.
aria-labelledby
undefined
—
Same reason as aria-label. Not a prop.
as
"span" | "div"
—
Element to render. Defaults to span.
children
ReactNode
—
Content rendered inside the element. The fixed hiding CSS applies regardless of content.
hidden
undefined
—
Would remove hidden content from the accessibility tree (WCAG 4.1.2). Not a prop.
inert
undefined
—
Would remove hidden content from the accessibility tree (WCAG 4.1.2). Not a prop.
ref
Ref<VisuallyHiddenHost<T>>
—
Ref to the rendered element.
role
undefined
—
Would replace the fixed hiding semantics with different assistive-technology behavior. Not a prop.
Storybook
Interactive examples and edge cases for this component are in Storybook.