VisuallyHidden

Text that screen readers announce and sighted users never see.

Primitives VisuallyHidden.jsx VisuallyHidden.d.ts VisuallyHidden.md

Playground

Change a prop and watch it. The code below follows along.

Live

Install and import

VisuallyHidden is in @dovetail-ds/react. Install it with React, if you haven't:

npm install @dovetail-ds/react react react-dom

import { VisuallyHidden } from "@dovetail-ds/react";

Import @dovetail-ds/react/styles.css once at your app's root, then your theme after it. Setup covers the stylesheets, fonts and dark mode.

Guidelines

Text that screen readers announce and sighted users never see.

Use it when

A heading is needed for document structure but would be visual noise.
A table's action column needs a header.
Live-region status text accompanies a purely visual change.

Don't use it when

You want to hide something from everyone. Use display: none.
An icon-only button needs a name. Those take a required label prop already.

Example

<VisuallyHidden as="h2">Account settings</VisuallyHidden>

Accessibility

Uses the clip-path technique rather than display: none or zero dimensions, both of which remove content from the accessibility tree.

Props

The typed contract, from VisuallyHidden.d.ts.

import * as React from "react";

/** Content available to screen readers but not shown. Never use it to hide something from everyone. */
export interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
  /** @default "span" */
  as?: keyof React.JSX.IntrinsicElements;
  children?: React.ReactNode;
}

export declare function VisuallyHidden(props: VisuallyHiddenProps): React.JSX.Element;

Tokens it reads

None. VisuallyHidden.jsx resolves no custom property: it sets structure and nothing a theme can move.

Source

React only, no dependencies, every value a token.

import React from "react";

export function VisuallyHidden({ as: Tag = "span", children, ...rest }) {
  return (
    <Tag
      style={{ position: "absolute", width: 1, height: 1, padding: 0, margin: -1, overflow: "hidden", clip: "rect(0 0 0 0)", clipPath: "inset(50%)", whiteSpace: "nowrap", border: 0 }}
      {...rest}
    >
      {children}
    </Tag>
  );
}

In context

VisuallyHidden also appears on the primitives reference cards, alongside the rest of its family.

PrimitivesDetail