You appear to be using an unsupported browser, and it may not be able to display this site properly. You may wish to upgrade your browser.

We use cookies to collect anonymous data to help us improve your site browsing experience.

Click 'Accept all cookies' to agree to all cookies that collect anonymous data. To only allow the cookies that make the site work, click 'Use essential cookies only.' Visit 'Set cookie preferences' to control specific cookies.

Set cookie preferences

Your cookie preferences have been saved. You can change your cookie settings at any time.

Accessibility semantics for website developers

ARIA names and descriptions

Last updated
30 Jan 2024

In web development an element's name, or accessible name, is how it's identified. An element's name is announced by screen readers. It's also used by speech recognition software to indicate exactly which element to target with a voice command. You should always use Native Hyper Text Markup Language (HTML)  when available. But if they're not, Web Accessibility Initiative - Accessible Rich Internet Applications (WAI-ARIA) can be used to add names and descriptions.

Name

ARIA has two attributes that can be used to provide accessible names for elements. When there's no visible label that can be used as the accessible name, aria-label can be used. You can do this for search buttons with no labels or close buttons on a modal dialog that visually shows as 'X'.

The aria-label attribute takes a piece of text as its value. This text becomes the element's label or accessible name.

Example code that uses an aria-label to provide an accessible name for a button. The screen reader will announce 'Search button':

<button id='search' aria-label='Search'></button>

The aria-labelledby attribute uses text that exists elsewhere in the document as a label. It takes the value of the id attribute on the element it points to, so it becomes the label or accessible name for the element with aria-labelledby applied to it.

Example code that uses aria-labelledby to provide an accessible name for a button. The screen reader will also announce 'Search button':

<h2 id='searchLabel'>Search</h2>

<label for='search'>Search term
  <input type='search' id='search'>
</label>
<button aria-labelledby='searchLabel'></button>

Description

The aria-describedby attribute gives an element an accessible description. It also points to text elsewhere in the document taking its value from the id attribute on the element it points to. 

Example code that uses aria-describedby to provide an accessible description for a password input. A screen reader will announce 'Password, minimum of 8 characters, with at least one number and a mixture of uppercase and lowercase letters':

<label for='passwordLabel'>Password</label> <input type='password' id='passwordLabel' name='password' aria-describedby='passwordDescription'> 

<p id='passwordDescription'>Minimum of 8 characters, with at least one number, and a mixture of uppercase and lowercase letters</p>

While an interactive element must have an accessible name, an accessible description is optional. Screen readers will announce the element's role, state (if it's important) and its accessible name. After a brief pause, it will announce its accessible description.

Tips

Follow these tips to improve user experience for your colleagues:

  • always use semantic HTML over ARIA when it's available
  • do not change native semantics unless you really have to
  • use WAI-ARIA Authoring Practices 1.1 as a reference for how to apply role, name, description, state and keyboard behaviour for accessible custom components
Back to top