Skip to main content
Since Shoelace 2.0 Code stable

Visually Hidden

<sl-visually-hidden> | SlVisuallyHidden

The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.

Examples

Visually Hidden Basics

According to The A11Y Project, “there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field’s label as a common magnifying glass icon is used in its stead.”

Since visually hidden content can receive focus when tabbing, the element will become visible when something inside receives focus. This behavior is intentional, as sighted keyboard user won’t be able to determine where the focus indicator is without it.

<div style="min-height: 1.875rem;">
  <sl-visually-hidden>
    <a href="#">Skip to main content</a>
  </sl-visually-hidden>
</div>
div style="min-height: 1.875rem;"
  sl-visually-hidden
    a href="#" Skip to main content

In this example, the link will open a new window. Screen readers will announce “opens in a new window” even though the text content isn’t visible to sighted users.

<a href="https://example.com/" target="_blank">
  Visit External Page
  <sl-icon name="arrow-top-right-on-square"></sl-icon>
  <sl-visually-hidden>opens in a new window</sl-visually-hidden>
</a>
a href="https://example.com/" target="_blank"
  | Visit External Page
  sl-icon name="arrow-top-right-on-square"
  sl-visually-hidden opens in a new window

Content Conveyed By Context

Adding a label may seem redundant at times, but they’re very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content that will be announced by assistive devices such as screen readers.

Personal Info
<sl-card style="width: 100%; max-width: 360px;">
  <header>
    <sl-visually-hidden>Personal Info</sl-visually-hidden>
  </header>
  <sl-input label="Name" style="margin-bottom: .5rem;"></sl-input>
  <sl-input label="Email" type="email"></sl-input>
</sl-card>
sl-card style="width: 100%; max-width: 360px;"
  header
    sl-visually-hidden Personal Info
  sl-input label="Name" style="margin-bottom: .5rem;"
  sl-input label="Email" type="email"

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/visually-hidden/visually-hidden.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/visually-hidden/visually-hidden.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/visually-hidden/visually-hidden.js';

To import this component as a React component:

import SlVisuallyHidden from '@shoelace-style/shoelace/dist/react/visually-hidden';

Slots

Name Description
(default) The content to be visually hidden.

Learn more about using slots.