Visually Hidden

Takes words out of sight and leaves them in the accessibility tree, for the name a control needs when its face is a picture.

Example

<ul class="stack" data-gap="sm" role="list">
    <li><a href="#hidden-trail">Read more<span class="visually-hidden"> about the trail map</span></a></li>
    <li><a href="#hidden-guide">Read more<span class="visually-hidden"> about the field guide</span></a></li>
</ul>

When to use it

Words a screen reader needs and the page has no room for: the name of an icon-only button, the number on a carousel dot, the subject of the third "Read more" link on a page.

It is not the hidden attribute, and the difference is the whole point — it is also why this is the one class in Yeti with two words in its name. hidden takes the element out of the page and out of the accessibility tree with it, so a reader hears nothing. This class takes it out of sight and leaves it in the tree, so a reader hears everything. The visibility guide has both, and the ten other ways to hide something, on one page.

<a href="/trail-map.pdf">Read more<span class="visually-hidden"> about the trail map</span></a>

How it works

The old clip-rect recipe, with clip-path in place of the deprecated clip property. The box is taken out of the flow with position: absolute, so it cannot open a gap in the line it sits in; it is sized a pixel square, because some engines drop a zero-size box altogether; and it is clipped to nothing with clip-path: inset(50%) and overflow: hidden. white-space: nowrap stops a long string being wrapped into a one-character column, which some screen readers read out letter by letter.

display: none and visibility: hidden are both shorter, and both do the one thing this must not: they take the text out of the accessibility tree.

Put only text in here. Everything inside is still in the page, so a link or a button inside would take Tab focus with nothing on screen to show for it, which is worse than either showing it or leaving it out.

Accessibility

The text is announced in source order and becomes part of the accessible name of whatever contains it, which is what makes a button with a picture on its face and a word inside it a named button.

A control is named once. Where an aria-label is present the browser uses that and ignores the text inside, so pick one: the label when the name is a rewording of the content, the hidden text when the name is the content and the design has no room for it.

It is a tool of last resort. A control with room for a word should have the word.

Attributes

None. This is configured through its children and tokens only.

Children

No structural requirements.

Tokens

No public tokens.

Accessibility

• This is the opposite of the hidden attribute, which removes the element from the accessibility tree as well: text carrying this class is still announced, in source order, and becomes part of the accessible name of whatever contains it. The two words in the name are there to keep the two apart. A control named twice is named once: where an aria-label is present the browser uses it and ignores the text inside, so use one or the other. Put only text in here. Anything focusable is still focusable and would take Tab focus with nothing on screen to show for it.

Browser support

• Used without guards: clip-path
• Behind @supports: nothing

JavaScript

None. This component is CSS only.

Available since 7.0.0.