Accessible names

Accessible elements don’t just have a role. They can have a ‘name’ too, which helps the user tell elements with the same role apart.

These names are provided by HTML in a number of ways:

  • <label> relationship
  • aria-labelledby attribute
  • aria-label attribute
  • The displayed value
  • The text content for the following roles:
    • button
    • cell
    • checkbox
    • columnheader
    • gridcell
    • heading
    • link
    • menuitem
    • menuitemcheckbox
    • menuitemradio
    • option
    • radio
    • row
    • rowgroup
    • rowheader
    • switch
    • tab
    • tooltip
    • tree
    • treeitem

The algorithm is specified in W3C’s Accessible Name and Description Computation.

Examples of accessible names

<label>Email: <input type=email></label>
<label><input type=checkbox> Receive email alerts</label>
  <legend>Alert settings</legend>
  <label><input type=checkbox> Receive push notifications</label>
  <label><input type=checkbox> Receive email alerts</label>
  <label><input type=checkbox> Receive text messages</label>
<article aria-labelledby="faq-heading">
  <h2 id="faq-heading">Frequently Asked Questions</h2>
<nav aria-label="Primary">
<svg role="img">
  <title>New document</title>

You could query these elements using Testing Library:

getByRole('button', { name: 'Save' });
getByRole('textbox', { name: /Email/ });
getByRole('checkbox', { name: /Receive email alerts/i });
getByRole('fieldset', { name: /Alert settings/i });
getByRole('article', { name: /Frequently asked questions/i });
getByRole('navigation', { name: 'Primary' });
getByRole('img', { name: 'New document' });