Automattic Design System

Components

VisuallyHidden

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 componentsPermalink to this section

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:

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

View on Storybook

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
children

ReactNode

The content to be rendered inside the component.

className

string

CSS class name to apply to the element.

style

CSSProperties

CSS style to apply to the element.

render

ComponentRenderFn<HTMLAttributesWithRef<any>> | ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>> | undefined

Replaces the component’s default HTML element using a given React element, or a function that returns a React element.

ExamplesPermalink to this section

DefaultPermalink to this section

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

With Custom ElementPermalink to this section

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"
            />
        </>
    );
};