Skip to main content

Helpers

Visually hidden

Hide content from sighted users while keeping it for assistive technology, optionally showing it on focus.

How it works

.visually-hidden shrinks an element to 1×1 px, clips it and takes it out of flow. The text remains in the accessibility tree, so screen readers announce it. Use it for labels, headings that only make sense aloud, and status text that a sighted user already gets from colour or an icon.

Do not use it on something a keyboard user must reach. For that, see .visually-hidden-focusable.

Title for screen readers

The heading above this sentence is announced but not drawn.

HTML
<h2 class="visually-hidden" id="visually-hidden-heading">Title for screen readers</h2>
<p class="mb-0">The heading above this sentence is announced but not drawn.</p>

A badge whose meaning is carried by colour gets a spoken suffix:

HTML
<button type="button" class="btn btn-primary position-relative">
  Inbox
  <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill text-bg-danger">
    3<span class="visually-hidden"> unread messages</span>
  </span>
</button>

An icon-only button needs a text name:

HTML
<button type="button" class="btn btn-outline-secondary">
  <svg width="1em" height="1em" viewBox="0 0 16 16" fill="currentcolor" aria-hidden="true"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/></svg>
  <span class="visually-hidden">Match rules</span>
</button>

Visually hidden, focusable

.visually-hidden-focusable hides the element until it, or anything inside it, receives focus. It is the right class for skip links. This docs site uses one — press Tab once on any page.

Skip to the next section

Tab into this example and the skip link appears above this paragraph.

HTML
<a class="visually-hidden-focusable" href="#visually-hidden-target">Skip to the next section</a>
<p class="mb-0" id="visually-hidden-target">Tab into this example and the skip link appears above this paragraph.</p>

Because the rule uses :focus-within, a hidden container with a focusable child also appears when the child is focused.

Main content placeholder · Navigation placeholder

HTML
<div class="visually-hidden-focusable">
  <a href="#visually-hidden-content">Skip to main content</a>
  <a href="#visually-hidden-nav">Skip to navigation</a>
</div>
<p class="mb-0"><span id="visually-hidden-content">Main content placeholder</span> · <span id="visually-hidden-nav">Navigation placeholder</span></p>

Table captions

A <caption> cannot be absolutely positioned without breaking table layout in some engines, so the rule excludes it: .visually-hidden:not(caption) gets position: absolute; a caption is clipped in place.

Championship lineage, 1985–2002
YearChampion
1985The Inaugural One
1994Tournament Winner
HTML
<table class="table table-sm mb-0">
  <caption class="visually-hidden">Championship lineage, 1985–2002</caption>
  <thead><tr><th scope="col">Year</th><th scope="col">Champion</th></tr></thead>
  <tbody>
    <tr><td>1985</td><td>The Inaugural One</td></tr>
    <tr><td>1994</td><td>Tournament Winner</td></tr>
  </tbody>
</table>

CSS

.visually-hidden,
.visually-hidden-focusable:not(:focus):not(:focus-within) {
  width: 1px !important;
  height: 1px !important;
  padding: 0 !important;
  margin: -1px !important;
  overflow: hidden !important;
  clip: rect(0, 0, 0, 0) !important;
  white-space: nowrap !important;
  border: 0 !important;
}
.visually-hidden:not(caption),
.visually-hidden-focusable:not(:focus):not(:focus-within):not(caption) {
  position: absolute !important;
}

Sass: @include visually-hidden; and @include visually-hidden-focusable;. More on when to hide and when not to in Accessibility.