To work with HTML elements via their ARIA attributes, you must learn a minimum about two ARIA attributes:
- The ARIA role
- The ARIA accessible name, which can and should be a human-readable piece of text such as
Your Name, not an html id like your-name.
But it is said that no ARIA is better than bad ARIA! So here is your bare-minimum ‘must-know’ to work successfully with aria role and aria accessible name.
An example: aria roles and names for a small form
testing-library pushes you to target elements in your tests by aria role and name, in the hope that you are then testing what your user interface actually presents to a user. Here's a testable example of the role and accessible names for a small form which you can run from an npm project with devDependencies @jest and @testing-library:
import '@jest/globals'
import '@testing-library/jest-dom'
import {screen, fireEvent} from '@testing-library/dom'
test('Example role and accessible names', ()=>{
const div= document.createElement('div')
div.innerHTML=`<form data-testid='form1'>
<fieldset>
<legend>Form Alpha</legend>
<label>Search : <input type='search' value="something" /></label>
<label><input type='checkbox' /> In Stock Only</label>
<button>The Go Button</button>
</fieldset>
</form>`
document.body.appendChild(div)
const fieldSet= screen.getByRole('group',{name:"Form Alpha"})
expect(fieldSet).toBeVisible()
const searchBox=screen.getByRole('searchbox', {name:/Search/i})
expect(searchBox).toHaveValue('something')
const checkBox=screen.getByRole('checkbox', {name:/in stock only/i})
expect(checkBox).not.toBeChecked()
fireEvent.click(checkBox)
expect(checkBox).toBeChecked()
const form=screen.getByTestId('form1')
expect(form).toBeVisible()
})
Now, some of these names and roles you could have guessed and some of it you couldn't. Let's take out the guesswork.
What Role and what Accessible Name do my HTML elements have?
HTML Element Roles
You can get a quick idea of roles just by looking at some of the defined ARIA roles:
- article, banner, button, cell, checkbox, columnheader, combobox, command, comment, complementary, composite, contentinfo, definition, dialog, document, figure, form, generic, grid, gridcell, group, heading, img, input, landmark, link, list, listbox, listitem, log, main, mark, marquee, math, menu, menubar, menuitem, menuitemcheckbox, menuitemradio, meter, navigation, option, presentation, progressbar, radio, radiogroup, range, region, roletype, row, rowgroup, rowheader, scrollbar, search, searchbox, section, sectionhead, select, separator, slider, spinbutton, status, structure, suggestion, switch, tab, table, tablist, tabpanel, term, textbox, timer, toolbar, tooltip, tree, treegrid, treeitem, widget, window
Most of them split into document structure and landmark roles vs widget and composite widget roles and you can probably guess most of which html elements implicitly have which roles by default, but some you would guess wrong. The other categories of roles are Abstract, Live Region, and Window. Some of the roles form hierarchies, with sub-roles.
Here is a table of the implicit ARIA role given by default to some commonly used html elements, along with the permitted overrides.
Implicit ARIA Roles for some common HTML elements
| HTML Element |
Implicit ARIA Role |
Permissible explicit Roles |
| nav |
navigation |
none |
| article |
article |
document, main, presentation &c |
| a href="..." |
link |
button,checkbox,menuitem &c |
| a without href |
none |
any |
| button |
button |
tab, checkbox, combobox, link, menuitem, &c |
| form |
form but only if it has an accessible name |
search, none or presentation |
| fieldset |
group |
radiogroup, presentation, none |
| img alt="..." |
img |
button, checkbox, link, menuitem, option, tab &c |
| img alt="" |
presentation |
presentation, none |
| input[type=button] |
button |
checkbox, combobox, link, &c |
| input[type=checkbox] |
checkbox |
button with aria-pressed, &c |
| input[type=image] |
button |
link, menuitem, radio, switch &c |
| input[type=number] |
spinbutton |
|
| input[type=radio] |
radio |
menuitemradio |
| input[type=range] |
slider |
|
| input[type=reset] |
button |
|
| input[type=submit] |
button |
|
| input[type=search] with no list attribute |
searchbox |
none |
| input[type=search] with list attribute |
combobox |
none |
| input[type=email] with no list attribute |
textbox |
none |
| input[type=email] with list attribute |
combobox |
none |
| input[type=tel] with no list attribute |
textbox |
none |
| input[type=tel] with list attribute |
combobox |
none |
| input[type=text] with no list attribute |
textbox |
combobox, searchbox, &c |
| input[type=text] with list attribute |
combobox |
none |
| input[type=url] with no list attribute |
textbox |
none |
| input[type=url] with list attribute |
combobox |
none |
| ul,ol |
list |
directory, group, listbox, menu, menubar, &c |
| label,legend,caption |
none |
none |
| main |
main |
none |
| menu |
list |
directory, group, listbox, menu, menubar, &c |
| optgroup |
group |
none |
| option |
option |
none |
| select with multiple attribute & no size greater than 1 |
combobox |
menu |
| select otherwise |
listbox |
none |
| textbox |
textbox |
none |
| table |
table |
any |
| td |
cell, if a descendant of a table |
any |
| th |
columnheader or rowheader |
any |
You can see some patterns:
- Many elements such as main, article, option, textbox have a fixed semantic meaning which is pretty much the same as their role. They can only have that fixed role and it can't be overridden.
- Some elements have no implicit Aria role but can be given any explicit role. These elements include div,span,code,blockquote,most of text elements such as em,strong, &c. Only give them a role if they really will play that role! For instance if you use them as parts of a custom widget. Otherwise they are best without a role. Not everything should have a role.
- Invisible elements such as style and script have no aria role and are not permitted an explicit role either.
- Label, legend, caption are in a sense special elements whose aria job is to label some other element with an accessible name. They can't be given any other role.
- Some element roles including a,img,select (and of course input) depend on how their attributes are set.
- See the HTML element reference pages to find the full list of html elements and the full list of permitted explicit roles for those that aren't in the above table.
The table mentions what explicit roles can be given. An explicit role is given to an HTML element by giving it a role="rolename" attribute. But the advice is to only do this when you have to. Work with the native HTML roles.
HTML Element Accessible Names
An accessible name can and should be a human-readable piece of text such as 'Your Name', not an html id like your-name.
To understand what the accessible name of a component is, you must understand the accessible name computation. Here are, roughly, the first 3 steps of the accessible name computation for HTML. This is enough to get you off the ground and calculate most of your accessible names.
The Accessible Name Computation for HTML Elements
- The
aria-labelledby property is used if present.
- If the name is still empty, the
aria-label property is used if present.
- If the name is still empty, then the 3rd step depends on the element and is described in the w3.org Accessible Name Computation Section By HTML Element. Here is a summary table:
| HTML Element |
Accessible Name Calculation if the element has no aria-label or aria-labelledby |
<input type="text">, <input type="password">, <input type="number">, <input type="search">, <input type="tel">, <input type="email">, <input type="url"> and <textarea> |
Use the associated label element or elements accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
If the accessible name is still empty, then: use the control's title attribute.
Use the control's placeholder value. |
<input type="button">, <input type="submit"> and <input type="reset"> Accessible Name Computation |
Use the associated label element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Use the value attribute.
For input type=submit and type=reset: if the prior steps do not yield a usable text string, and the value attribute is unspecified use the implementation defined string respective to the input type.
Otherwise, if the control still has no accessible name use title attribute. |
<input type="image"> Accessible Name Computation |
Use the associated label element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Use alt attribute if present and its value is not the empty string.
Use title attribute if present and its value is not the empty string.
Otherwise if the previous steps do not yield a usable text string, use the implementation defined string respective to the input type (an input in the image state represents a submit button). For instance, a localized string of the word "submit" or the words "Submit Query". |
<button> |
Use the associated label element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Use the button element subtree.
Use title attribute. |
<fieldset> |
If the accessible name is still empty, then: if the fieldset element has a child that is a legend element, then use the subtree of the first such element.
If the accessible name is still empty, then:, if the fieldset element has a title attribute, then use that attribute.
Otherwise, there is no accessible name. |
<output> |
Use the associated label element or elements accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Use title attribute. |
| Other Form Elements |
Use label element.
Use title attribute. |
<summary> |
If the first summary element, which is a direct child of the details element, has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings.
Use summary element subtree.
Use title attribute.
If there is no summary element as a direct child of the details element, the user agent should provide one with a subtree containing a localized string of the word "details".
If there is a summary element as a direct child of the details element, but none of the above yield a usable text string, there is no accessible name. |
<figure> |
If the accessible name is still empty, then: if the figure element has a child that is a figcaption element, then use the subtree of the first such element.
If the accessible name is still empty, then: if the figure element has a title attribute, then use that attribute. |
<img> |
Use alt attribute, even if its value is the empty string.
NOTE
An img with an alt attribute whose value is the empty string is mapped to the presentation role. It has no accessible name.
Otherwise, if there is no alt attribute use the title attribute. |
<table> |
if the table element has a child that is a caption element, then use the subtree of the first such element.
if the table element has a title attribute, then use that attribute. |
tr, td, th |
Use the title attribute. |
<a> |
Use a element subtree.
Use the title attribute. |
<area> |
Use area element's alt attribute.
Use the title attribute. |
<iframe> |
Use the title attribute.
NOTE
The document referenced by the src of the iframe element gets its name from that document's title element, like any other document |
Section and Grouping p, hr, pre, blockquote, ol, ul, li, dl, dt, dd, figure, figcaption, div, main and body, article, section, nav, aside, h1, h2, h3, h4, h5, h6, header, footer, address |
Use the title attribute. |
Text-level Elements: abbr, b, bdi, bdo, br, cite, code, dfn, em, i, kbd, mark, q, rp, rt, ruby, s, samp, small, strong, sub and sup, time, u, var, wbr |
Use the title attribute. |
If this step 3 seems a bit ad hoc, the underlying logic is ARIA's categorisation into roles (and therefore elements) that have
- Name from Author, meaning that you as the content author use a
<label> (or legend or caption or figcaption or alt= attribute, or similar as appropriate to the html element) to provide an explicit accessible name
- Name from Content, meaning that the browser reads the text nodes of the element and uses that as that accessible name.
- No name. After all, you don't want a name for every paragraph or span or div. That would be really unhelpful.
Note that multiple labels or multiple content sources are valid, and will be concatenated with spaces.
The 3 Cases of the 3rd Step of the Accessible Name Calculation:
If you learn
- which html elements have name from content,
- which rely on a label,
- which should not be named
then you've got 95% of what you need. You can then choose the appropriate way to aria-name your element:
- Naming with child content.
- Naming form controls with the label element.
- Naming fieldsets with the legend element.
- Naming tables and figures with captions.
- Naming with a string attribute via aria-label.
- Naming by referencing content with aria-labelledby.
Overriding the default name and not using the fallback
Steps 1 and 2, using either an aria-label="This is my name" attribute, or an aria-labelledby="id-of-a-labelling-element-with-text-content" is the override mechanism.
The common fallback mechanism — which you can always avoid using— is the title attribute. Prefer using the explicit override rather than letting a title set your name.
Parting comments
-
See https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/ for an understanding of why you are naming things and how to do it well.
-
Returning to my original example, you can see that aria is opiniated. Many aria roles and naming rules are what you'd expect, but ARIA thinking is not identical to html thinking. The input elements get accessible names from their labels, but the form as a whole only gets an accessible name if you explicitly give it one, and it only gets the Aria role of form if it has an accessible name.
-
I have only discussed roles and names. ARIA also has descriptions and states and properties. For instance, you can use aria-busy=true on elements when they are loading or waiting to be populated with data.
-
See testing-library's intro example for more on using testing-library with vanilla html or major frameworks
Learning to do it well
A starting point for learning how to create good accessible sites is https://www.w3.org/WAI/ARIA/apg/
