🏷️

Providing Accessible Names and Descriptions

Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most important responsibilities authors have.

This practice is documented in detail at Providing Accessible Names and Descriptions - WAI-ARIA APG . Below we provide additional context specific to our pattern implementations.

Overview

Every interactive element needs an accessible name that assistive technology can announce to users. Some elements also benefit from an accessible description that provides additional context. This practice explains how to provide these correctly.

Accessible Name vs Description

Concept	Purpose	Announced When
Accessible Name	Primary label that identifies the element	Focus, interaction
Accessible Description	Additional context or instructions	After the name (configurable)

Methods for Providing Accessible Names

1. Native HTML Labels

The most robust approach is using native HTML:

<label for="email">Email address</label>
<input type="email" id="email" />

<button type="submit">Send message</button>

<a href="/about">About us</a>

<img src="logo.png" alt="Company logo" />

2. aria-label

For elements without visible text, use aria-label:

<button type="button" aria-label="Close">
  <svg aria-hidden="true">...</svg>
</button>

<search aria-label="Site search">...</search>

3. aria-labelledby

Reference existing visible text:

<h2 id="billing-title">Billing Address</h2>
<section aria-labelledby="billing-title">...</section>

Methods for Providing Accessible Descriptions

aria-describedby

Link to elements containing descriptive text:

<label for="password">Password</label>
<input type="password" id="password" aria-describedby="pwd-hint" />
<p id="pwd-hint">Must be at least 8 characters with one number</p>

aria-description

Provide a description directly (newer; support may vary across browser and assistive technology combinations, so prefer aria-describedby when possible):

<button aria-description="Opens in a new window">External link</button>

Common Pitfalls

Empty or Redundant Names

<button><svg>...</svg></button>

Bad: No accessible name — screen readers cannot announce the button's purpose.

<img src="hero.jpg" alt="image" />

Bad: Redundant — screen readers announce "image image" since the role is already conveyed.

<img src="hero.jpg" alt="Tokyo Tower glowing at sunset" />

Good: Descriptive name that clearly identifies the image content.

Placeholder as Label

<input type="text" placeholder="Email" />

Bad: Placeholder text disappears when the user starts typing, leaving no visible label.

<label for="email">Email</label>
<input type="text" id="email" placeholder="you@example.com" />

Good: Persistent label that remains visible while typing.

Overriding Native Semantics

<p aria-label="Important">This is a paragraph</p>

Bad: aria-label on non-interactive element — paragraphs are not named by aria-label in the accessible name computation, so "Important" is ignored and only "This is a paragraph" is announced.

<p><strong>Important:</strong> This is a paragraph</p>

Good: Include the important information as text content — paragraph text naturally serves as accessible content.

Implementation Tips

Name Priority (Accessible Name Computation)

When multiple naming methods are present, browsers use this priority:

aria-labelledby (highest)
aria-label
Native HTML (label, alt, button text, etc.)
title attribute (not intended for naming, so typically yields low-quality accessible names — avoid where possible)

Test Your Names

Use browser DevTools accessibility inspector
Navigate with a screen reader
Check that names are:
- Unique within context
- Descriptive but concise
- Localized appropriately