VisuallyHidden – Automattic Design System

Visually hides content while keeping it accessible to screen readers. Useful when providing context that’s only meaningful to assistive technology.

Renders a <div> by default. Use the render prop to swap the underlying element while preserving the visually-hidden behavior.

Composing with other components

When composing with another component that uses the render prop pattern, keep VisuallyHidden as the host (outer component) and pass the other component via render. This keeps the other component’s HTML element and semantics intact, while VisuallyHidden only adds its hiding styles:

View on Storybook

View source on GitHub

Import

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

Props

Name	Type	Description
`className`	`string`	CSS class name to apply to the element.
`style`	`React.CSSProperties`	CSS style to apply to the element.
`render`	`\| ComponentRenderFn< HTMLAttributesWithRef > \| React.ReactElement< Record< string, unknown > >`	Replaces the component’s default HTML element using a given React element, or a function that returns a React element.
`children`	`React.ReactNode`	The content to be rendered inside the component.

Examples

Default

const Default = () => (
    <>
        <VisuallyHidden>This should not show.</VisuallyHidden>
        <div>
            This text will <VisuallyHidden>but not inline </VisuallyHidden>
            always show.
        </div>
    </>
);

With Custom Element

Use the render prop to change the underlying HTML element. By default, VisuallyHidden renders a <div>. Here it renders a <label> instead, keeping the native label–input association while hiding the label text visually.

const WithCustomElement = function WithCustomElementStory() {
    const inputId = useId();
    return (
        <>
            { /* eslint-disable-next-line jsx-a11y/label-has-associated-control */ }
            <VisuallyHidden render={ <label htmlFor={ inputId } /> }>
                Accessible label
            </VisuallyHidden>
            <input
                id={ inputId }
                placeholder="This input has a visually hidden label"
            />
        </>
    );
};