Visually hidden

The VisuallyHidden utility is used for hiding content from sighted users, while still keeping it in the accessibility tree for screen readers and others assistive technologies. This is achieved using a very specific ruleset that has been tested across a variety of browsers and assistive technologies.

One common use for this component is to provide a text alternative for icons and symbols. In the following example, sighted users will see the star visual representation, while screen reader users will hear “3 stars out 5”.

import * as React from 'react';
import { VisuallyHidden } from '@itwin/itwinui-react';

export default () => {
  return (
    <>
      <div aria-hidden='true'>★★★☆☆</div>
      <VisuallyHidden>3 stars out of 5</VisuallyHidden>
    </>
  );
};

Another use for this component is to add additional text for screen readers to make it easy to differentiate between a set of similar buttons/links, without interfering with the design for sighted users. In the following example, the buttons will be announced by screen readers as “Delete item 1”, “Delete item 2”, etc.

import * as React from 'react';
import { VisuallyHidden } from '@itwin/itwinui-react';

export default () => {
  return (
    <ul>
      <li>
        Item 1{' '}
        <button>
          Delete <VisuallyHidden>item 1</VisuallyHidden>
        </button>
      </li>

      <li>
        Item 2{' '}
        <button>
          Delete <VisuallyHidden>item 2</VisuallyHidden>
        </button>
      </li>

      <li>
        Item 3{' '}
        <button>
          Delete <VisuallyHidden>item 3</VisuallyHidden>
        </button>
      </li>
    </ul>
  );
};

By default, if an interactive element is passed as a child and it gets focused, then it will “unhide”. This avoids confusion for keyboard users for whom the focus might otherwise get “lost”. If your design already has alternative means to indicate focus, then you can disable this behavior using unhideOnFocus={false}.

Props