API and Development
VisuallyHidden, VISUALLY_HIDDEN_ELEMENTS from @prepared911/ui/visually-hidden.
Choose a tag from VisuallyHiddenElement: span (default) or div.
Content rendered inside the element. The fixed hiding CSS applies regardless of content, including a long unbroken string.
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.
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.
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.
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.
| 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. |
| 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. |