Hide content properly

Not all content hiding techniques are suitable for users of screen readers or other assistive technologies. This page outlines the primary methods for hiding content from all users or from screen reader users only.

Making Content Invisible (Visually Hidden)

If an element on the page:

• is an interactive element but should be visually hidden for theming purposes (e.g., links, checkboxes, radio buttons, or form controls with custom styles),
• is a heading or label for something where the purpose is obvious (thus not needed for sighted users, e.g., a section label or form element label),
• should not be visible to sighted users but should remain visible to screen reader users,

...then you should make it visually hidden.

You can do this by:

• adding the visually-hidden class to the element,
• in Drupal 8, setting field labels to “- Visually Hidden -” via the Manage Display settings for entity subtypes (e.g., "Tags" field on an Article content type),
• using CSS to position the element offscreen, or
• using the following CSS:

position: absolute !important;
clip: rect(1px, 1px, 1px, 1px);
overflow: hidden;
height: 1px;
width: 1px;
word-wrap: normal;

Example:
Hiding the heading for error, warning, and status messages.

Rationale:
Most themes display status messages prominently within a colored border, making them visually noticeable. However, according to WCAG 2.0 Section 1.3.3, understanding content should not rely solely on sensory characteristics such as shape, size, visual location, or orientation.

Without a heading indicating what the messages are, screen reader users may be confused. Most screen readers let users navigate by heading, so adding a heading improves accessibility.

Make Content Invisible Until Focused with Keyboard

If an element on the page:

• is a link to help users skip to main content or navigation,
• is an alternative to elements that are only mouse-accessible, or
• should not be visible to sighted users unless navigated to via keyboard,

...then it should be hidden until it receives keyboard focus.

You can do this by:

• adding both visually-hidden and focusable classes, or
• using this CSS:

css_selector_for_my_element {
  position: absolute !important;
  clip: rect(1px, 1px, 1px, 1px);
  overflow: hidden;
  height: 1px;
  width: 1px;
  word-wrap: normal;
}
css_selector_for_my_element:active,
css_selector_for_my_element:focus {
  position: static !important;
  clip: auto;
  overflow: visible;
  height: auto;
  width: auto;
}

Example:
A "Skip to main content" link at the top of each page in core themes.

Rationale:
Keyboard and screen reader users want a quick way to access the main content. To comply with WCAG 2.0 Section 2.4.1, you must provide a way to skip repetitive blocks of content.

Completely Hiding Content from All Users

If an element on the page:

• should only be visible after being triggered via JavaScript,
• is irrelevant for both sighted and screen reader users in the current context,
• contains values read/written by JavaScript but not meant for direct display, or
• generally should not be seen or read by any user,

...then it should be fully hidden from all users.

You can do this by:

• adding the hidden class (in Drupal 8),
• setting the field’s format to “- Hidden -” on the Manage Display page for the entity subtype,
• setting a field label to “- Hidden -”, or
• using CSS: display: none;

Example:
Hiding the color module’s preview area until JavaScript is enabled:

/* color.css (Drupal 7 and 8) */
#preview {
  display: none;
}

Rationale:
The preview does not work without JavaScript, so it’s not needed otherwise.

Misuse

A common misuse of “display: none” is hiding a form label or heading to improve visual design. However, this makes the form element unusable for screen reader users.

For example, if you hide a form label with “display: none”, a screen reader user might hear “required field” with no idea what the field is for. A better approach would be to visually hide the label while keeping it accessible.

Hiding Content from Screen Readers

If an element on the page:

• is confusing on its own, or
• should only be visible to sighted users,

...then it should be hidden from screen readers.

You can do this by:

• adding the attribute aria-hidden="true" to the element.

Example:
A filter remove control shows an “x” to sighted users and includes a visually hidden instruction for screen reader users:

Currently filtering by: <a href="...">Module 
  <span class="visually-hidden">Click to remove this filter.</span> 
  <span aria-hidden="true">x</span>
</a>

Rationale:
An accessible alternative text is already provided. Hearing “x” may confuse screen reader users after hearing the instruction.

Misuse

Hiding content from screen readers means users relying on assistive tech cannot perceive or interact with it. To meet WCAG 2.0 Section 1.1, you must provide accessible alternatives, or assistive tech users will miss important content.

More on Hidden Content

• WebAIM Recommendations
• The display: none problem for screen readers