- Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most important responsibilities authors have when developing accessible web experiences. - While doing so is straightforward for most elements, technical mistakes that can completely block users of assistive technologies are easy to make and unfortunately common. - To help authors effectively provide accessible names and descriptions, this section explains their purpose, when authors need to provide them, how browsers assemble them, and rules for coding and composing them. - It also guides authors in the use of the following naming and describing techniques and WAI-ARIA properties: -
-aria-label.aria-labelledby.aria-describedby.- An accessible name is a short string, typically 1 to 3 words, that authors associate with an element to provide users of assistive technologies with a label for the element. - For example, an input field might have an accessible name of "User ID" or a button might be named "Submit". -
-An accessible name serves two primary purposes for users of assistive technologies, such as screen readers:
-- Both the WAI-ARIA specification and WCAG require all focusable, interactive elements to have an accessible name. - In addition dialogs and some structural containers, such as tables and regions, are required to have a name. - Many other elements can be named, but whether a name will enhance the accessible experience is determined by various characteristics of the surrounding context. - Finally, there are some elements where providing an accessible name is technically possible but not advisable. - The Accessible Name Guidance by Role section lists naming requirements and guidelines for every ARIA role. -
-- An accessible description is also an author-provided string that is rendered by assistive technologies. - Authors supply a description when there is a need to associate additional information with an element, such as instructions or format requirements for an input field. -
-
- Assistive technologies present names differently from descriptions.
- For instance, screen readers typically announce the name and role of an element first, e.g., a button named Mute Conversation
could be spoken as Mute Conversation button
.
- If an element has a state, it could be announced either before or after the name and role; after name and role is the typical default.
- For example, a switch button named Mute Conversation
in the off
state could be announced as Mute Conversation switch button off
.
- Because descriptions are optional strings that are usually significantly longer than names, they are presented last, sometimes after a slight delay.
- For example, Mute Conversation Switch button off, Silences alerts and notifications about activity in this conversation.
- To reduce verbosity, some screen readers do not announce descriptions by default but instead inform users of their presence so that users can press a key that will announce the description.
-
- Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because authors can combine them in a practically endless number of ways, browsers implement fairly complex algorithms for assembling the strings. -The sections on accessible name calculation and accessible description calculation explain the algorithms and how they implement precedence. -However, most authors do not need such detailed understanding of the algorithms since nearly all circumstances where a name or description is useful are supported by the coding patterns described in the naming techniques and describing techniques sections. -
-- Several of the naming techniques below include notes that warn against specific coding patterns that are either prohibited by the ARIA specification or fall into gray space that is not yet fully specified. - Some of these prohibited or ambiguous patterns may appear logical and even yield desired names in some browsers. - However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses. -
-- In addition to heeding the warnings provided in the naming techniques, it is difficult to over emphasize the importance of testing to ensure that names browsers calculate match expectations. -
-- When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. - When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names will not be updated when the user interface design or content are changed. -
-- If an interactive element, such as an input field or button, does not have a visually persistent text label, consider adjusting the design to include one. - In addition to serving as a more robust source for an accessible name, visible text labels enhance accessibility for many people with disabilities who do not use assistive technologies that present invisible accessible names. - In most circumstances, visible text labels also make the user interface easier to understand for all users. -
-
- In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element for form elements and caption element for tables.
- While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences.
- Several of the naming techniques highlight specific accessibility advantages of using HTML features instead of ARIA attributes.
-
- When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fallback methods for generating a name.
- For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names.
- Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective.
-
- Similar to how visually crowded screens and ambiguous icons reduce usability, excessively long, insufficiently distinct, or unclear accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. - In other words, for a web experience to be accessible, its accessible names must be effective. - The section on Composing Effective and User-friendly Accessible Names provides guidance for balancing brevity and clarity. -
-- Certain elements get their name from the content they contain. - For example, the following link is named "Home". -
- -<a href="/">Home</a>- When assistive technologies render an element that gets its accessible name from its content, such as a link or button, the accessible name is the only content the user can perceive for that element. - This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented in addition to the value or content of the element. - For instance, the accessible name of a table can be derived from a caption element, and assistive technologies render both the caption and all other content contained inside the table. -
-Elements having one of the following roles are, by default, named by a string calculated from their descendant content:
-menu element is excluded.)group element is excluded.)
- When calculating a name from content for an element, user agents recursively walk through each of its descendant elements, calculate a name string for each descendant, and concatenate the resulting strings.
- In two special cases, certain descendants are ignored: group descendants of treeitem elements and menu descendants of menuitem elements are omitted from the calculation.
- For example, in the following tree, the name of the first tree item is Fruits
; Apples
, Bananas
, and Oranges
are omitted.
-
<ul role="tree">
- <li role="treeitem">Fruits
- <ul role="group">
- <li role="treeitem">Apples</li>
- <li role="treeitem">Bananas</li>
- <li role="treeitem">Oranges</li>
- </ul>
- </li>
-</ul>
- If an element with one of the above roles that supports naming from child content is named by using aria-label or aria-labelledby, content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby.
- It is strongly recommended to avoid using either of these attributes to override content of one of the above elements except in rare circumstances where hiding content from assistive technology users is beneficial.
- In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important.
-
aria-label- The aria-label property enables authors to name an element with a string that is not visually rendered. - For example, the name of the following button is "Close". -
-<button type="button" aria-label="Close">X</button>
- The aria-label property is useful when there is no visible text content that will serve as an appropriate accessible name.
-
- The aria-label property affects assistive technology users in one of two different ways, depending on the role of the element to which it is applied.
- When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces it with the value of aria-label.
- However, when applied to nearly any other type of element, assistive technologies will render both the value of aria-label and the content of the element.
- For example, the name of the following navigation region is "Product".
-
<nav aria-label="Product">
- <!-- list of navigation links to product pages -->
-</nav>- When encountering this navigation region, a screen reader user will hear the name and role of the element, e.g., "Product navigation region", and then be able to read through the links contained in the region. -
-aria-label is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users.
- It is strongly recommended to avoid using aria-label to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial.
- aria-label. They are identified in the table in the Accessible Name Guidance by Role section.aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.aria-label values are translated.aria-labelledby- The aria-labelledby property enables authors to reference other elements on the page to define an accessible name. - For example, the following switch is named by the text content of a previous sibling element. -
-<span id="night-mode-label">Night mode</span>
-<span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
- Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the labeling element activate the labeled element; that is an author responsibility.
- However, HTML label cannot be used to label a span element.
- Fortunately, an HTML input with type="checkbox" allows the ARIA switch role, so when feasible, using the following approach creates a more robust solution.
-
<label for="night-mode">Night mode</label>
-<input type="checkbox" role="switch" id="night-mode">The aria-labelledby property is useful in a wide variety of situations because:
It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, including aria-label.
It can concatenate content from multiple elements into a single name string.
It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with the HTML hidden attribute, CSS display: none, or CSS visibility: hidden in the calculated name string.
It incorporates the value of input elements, i.e., if it references a textbox, the value of the textbox is included in the calculated name string.
An example of referencing a hidden element with aria-labelledby could be a label for a night switch control:
<span id="night-mode-label" hidden>Night mode</span>
-<input type="checkbox" role="switch" aria-labelledby="night-mode-label">
- In some cases, the most effective name for an element is its own content combined with the content of another element.
- Because aria-labelledby has highest precedence in name calculation, in those situations, it is possible to use aria-labelledby to reference both the element itself and the other element.
- In the following example, the "Read more..." link is named by the element itself and the article’s heading, resulting in a name for the link of "Read more... 7 ways you can help save the bees".
-
<h2 id="bees-heading">7 ways you can help save the bees</h2>
-<p>Bees are disappearing rapidly. Here are seven things you can do to help.</p>
-<p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
- When multiple elements are referenced by aria-labelledby, text content from each referenced element is concatenated in the order specified in the aria-labelledby value.
- If an element is referenced more than one time, only the first reference is processed.
- When concatenating content from multiple elements, browsers trim leading and trailing white space and separate content from each element with a single space.
-
<button id="download-button" aria-labelledby="download-button download-details">Download</button>
-<span id="download-details">PDF, 2.4 MB</span>In the above example, the accessible name of the button will be "Download PDF, 2.4 MB", with a space between "Download" and "PDF", and not "DownloadPDF, 2.4 MB".
-aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.aria-labelledby. They are identified in the table in the Accessible Name Guidance by Role section.aria-labelledby is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby.
- It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial.
- aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
- The HTML label element enables authors to identify content that serves as a label and associate it with a form control.
- When a label element is associated with a form control, browsers calculate an accessible name for the form control from the label content.
-
- For example, text displayed adjacent to a checkbox may be visually associated with the checkbox, so it is understood as the checkbox label by users who can perceive that visual association.
- However, unless the text is programmatically associated with the checkbox, assistive technology users will experience a checkbox without a label.
- Wrapping the checkbox and the labeling text in a label element as follows gives the checkbox an accessible name.
-
<label>
- <input type="checkbox" name="subscribe">
- subscribe to our newsletter
-</label>
- A form control can also be associated with a label by using the for attribute on the label element.
- This allows the label and the form control to be siblings or have different parents in the DOM, but requires adding an id attribute to the form control, which can be error-prone.
- When possible, use the above encapsulation technique for association instead of the following for attribute technique.
-
<input type="checkbox" name="subscribe" id="subscribe_checkbox">
-<label for="subscribe_checkbox">subscribe to our newsletter</label>
- Using the label element is an effective technique for satisfying Rule 2: Prefer Visible Text.
- It also satisfies Rule 3: Prefer Native Techniques.
- Native HTML labels offer an important usability and accessibility advantage over ARIA labeling techniques: browsers automatically make clicking the label equivalent to clicking the form control.
- This increases the hit area of the form control.
-
- The HTML fieldset element can be used to group form controls, and the legend element can be used to give the group a name.
- For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons.
-
<fieldset>
- <legend>Select your starter class</legend>
- <label><input type="radio" name="starter-class" value="green">Green</label>
- <label><input type="radio" name="starter-class" value="red">Red</label>
- <label><input type="radio" name="starter-class" value="blue">Blue</label>
-</fieldset>- This grouping technique is particularly useful for presenting multiple choice questions. - It enables authors to associate a question with a group of answers. - If a question is not programmatically associated with its answer options, assistive technology users may access the answers without being aware of the question. -
-
- Similar benefits can be gained from grouping and naming other types of related form fields using fieldset and legend.
-
<fieldset>
- <legend>Shipping address</legend>
- <p><label>Full name <input name="name" required></label></p>
- <p><label>Address line 1 <input name="address-1" required></label></p>
- <p><label>Address line 2 <input name="address-2"></label></p>
- ...
-</fieldset>
-<fieldset>
- <legend>Billing address</legend>
- ...
-</fieldset>Using the legend element to name a fieldset element satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.
- The accessible name for HTML table and figure elements can be derived from a child caption or figcaption element, respectively.
- Tables and figures often have a caption to explain what they are about, how to read them, and sometimes giving them numbers used to refer to them in surrounding prose.
- Captions can help all users better understand content, but are especially helpful to users of assistive technologies.
-
- In HTML, the table element marks up a data table, and can be provided with a caption using the caption element.
- If the table element does not have aria-label or aria-labelledby, then the caption will be used as the accessible name.
- For example, the accessible name of the following table is Special opening hours
.
-
<table>
- <caption>Special opening hours</caption>
- <tr><td>30 May</td><td>Closed</td></tr>
- <tr><td>6 June</td><td>11:00-16:00</td></tr>
-</table>The following example gives the table a number (Table 1
) so it can be referenced.
<table>
- <caption>Table 1. Traditional dietary intake of Okinawans and other Japanese circa 1950</caption>
- <thead>
- <tr>
- <th></th>
- <th>Okinawa, 1949</th>
- <th>Japan, 1950</th>
- </tr>
- <tbody>
- <tr>
- <th>Total calories</th>
- <td>1785</td>
- <td>2068</td>
-
- [...]
-
-</table>Note: Above table content is from Caloric restriction, the traditional Okinawan diet, and healthy aging: the diet of the world's longest-lived people and its potential impact on morbidity and life span.
-
- If a table is named using aria-label or aria-labelledby, then a caption element, if present, will become an accessible description.
- For an example, see Describing Tables and Figures with Captions.
-
- Similarly, an HTML figure element can be given a caption using the figcaption element.
- The caption can appear before or after the figure, but it is more common for figures to have the caption after.
-
<figure>
- <img alt="Painting of a person walking in a desert." src="Hole_JesusalDesierto.jpg">
- <figcaption>Jesus entering the desert as imagined by William Hole, 1908</figcaption>
-</figure>
- Like with table elements, if a figure is not named using aria-label or aria-labelledby, the content of the figcaption element will be used as the accessible name.
- However unlike table elements, if the figcaption element is not used for the name, it does not become an accessible description unless it is referenced by aria-describedby.
- Nevertheless, assistive technologies will render the content of a figcaption regardless of whether it is used as a name, description, or neither.
-
Using the caption element to name a table element, or a figcaption element to name a figure element, satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.
- When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), browsers calculate an accessible name from other attributes as a fallback mechanism.
- Because the attributes used in fallback name calculation are not intended for naming, they typically yield low quality accessible names that are not effective.
-So, As advised by Rule 4: Avoid Browser Fallback, prefer the explicit labeling techniques described above over fallback techniques described in this section.
-
- Any HTML element can have a title attribute specified.
- The title attribute may be used as the element's fallback accessible name.
- The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device.
-
For example, a fieldset element without a legend element child, but with a title attribute, gets its accessible name from the title attribute.
<fieldset title="Select your starter class">
- <label><input type="radio" name="starter-class" value="green">Green</label>
- <label><input type="radio" name="starter-class" value="red">Red</label>
- <label><input type="radio" name="starter-class" value="blue">Blue</label>
-</fieldset>
- For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label.
- It is better to use a label element, since it does not disappear visually when the user focuses the form control.
-
<!-- Using a <label> is recommended -->
-<label>Search <input type=search name=q></label>
-
-<!-- A placeholder is used as fallback -->
-<input type=search name=q placeholder="Search">- For assistive technology users, especially screen reader users, the quality of accessible names is one of the most significant contributors to usability. - Names that do not provide enough information reduce users' effectiveness while names that are too long reduce efficiency. - And, names that are difficult to understand reduce effectiveness, efficiency, and enjoyment. -
-The following guidelines provide a starting point for crafting user friendly names.
-Xcloses a dialog, name it
Close, not
X. - Similarly, if a set of navigation links in the left side bar navigate among the product pages in a shopping site, name the navigation region
Product, not
Left. -
Edit,
Delete, and
Actionsbuttons for each contact, - then
Edit John Doe,
Delete John Doe, and
Actions for John Doewould be better accessible names than
John Doe edit,
John Doe delete, and
John Doe actions. - By placing the verb first in the name, screen reader users can more easily and quickly distinguish the buttons from one another as well as from the element that opens the contact card for John Doe. -
buttonin the name of a button, the word
imagein the name of an image, or the word
navigationin the name of a navigation region. - Doing so would create duplicate screen reader output since screen readers convey the role of an element in addition to its name. -
- Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. - The table below lists all ARIA roles and provides the following information for each : -
-aria-label or aria-labelledby is applied, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby.
- Avoid hiding descendant content except in the rare circumstances where doing so benefits assistive technology users.
- | role | -Necessity of Naming | -Guidance | -
|---|---|---|
alert |
- Discretionary | -
- Some screen readers announce the name of an alert before announcing the content of the alert.
- Thus, aria-label provides a method for prefacing the visible content of an alert with text that is not displayed as part of the alert.
- Using aria-label is functionally equivalent to providing off-screen text in the contents of the alert, except off-screen text would be announced by screen readers that do not support aria-label on alert elements.
- |
-
alertdialog |
- Required | -Use aria-labelledby if a visible label is present, otherwise use aria-label. |
-
application |
- Required | -Use aria-labelledby if a visible label is present, otherwise use aria-label. |
-
article |
- Recommended | -
-
|
-
banner |
- Discretionary | -
-
|
-
blockquote |
- Discretionary | -
- If a visible label is present, associating it with the blockquote by using aria-labelledby could benefit some assistive technology users.
- |
-
button |
- Required Only If Content Insufficient | -
-
|
-
caption |
- Prohibited | -- |
cell |
- Required Only If Content Insufficient | -
-
|
-
checkbox |
- Required Only If Content Insufficient | -
-
|
-
code |
- Prohibited | -- |
columnheader |
- Required Only If Content Insufficient | -
-
|
-
combobox |
- Required | -
-
|
-
complementary |
- Recommended | -
-
|
-
contentinfo |
- Discretionary | -
-
|
-
definition |
- Recommended | -Reference the term being defined with role="term", using aria-labelledby. |
-
deletion |
- Prohibited | -- |
dialog |
- Required | -Use aria-labelledby if a visible label is present, otherwise use aria-label. |
-
directory |
- Discretionary | -
-
|
-
document |
- Discretionary | -
- Elements with the document role are contained within an element with the application role, which is required to have a name.
- Typically, the name of the application element will provide sufficient context and identity for the document element.
- Because the application element is used only to create unusual, custom widgets, careful assessment is necessary to determine whether or not adding an accessible name is beneficial.
- |
-
emphasis |
- Prohibited | -- |
feed |
- Recommended | -
-
|
-
figure |
- Recommended | -
-
|
-
form |
- Recommended | -
-
|
-
generic |
- Prohibited | -- |
grid |
- Required | -
-
|
-
gridcell |
- Required Only If Content Insufficient | -
-
|
-
group |
- Discretionary | -
-
|
-
heading |
- Required Only If Content Insufficient | -
-
|
-
insertion |
- Prohibited | -- |
img |
- Required | -For the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label. |
-
link |
- Required Only If Content Insufficient | -
-
|
-
list |
- Discretionary | -
-
|
-
listbox |
- Required | -
-
|
-
listitem |
- Do Not Name | -Naming is not supported by assistive technologies; it is necessary to include relevant content within the list item. | -
log |
- Discretionary | -
- Some screen readers announce the name of a log element before announcing the content of the log element.
- Thus, aria-label provides a method for prefacing the visible content of a log element with text that is not displayed as part of the log element.
- Using aria-label is functionally equivalent to providing off-screen text in the contents of the log element, except off-screen text would be announced by screen readers that do not support aria-label on log elements.
- |
-
main |
- Discretionary | -
-
|
-
marquee |
- Discretionary | -Use aria-labelledby if a visible label is present, otherwise use aria-label. |
-
math |
- Recommended | -
-
|
-
menu |
- Recommended | -
-
|
-
menubar |
- Recommended | -
-
|
-
menuitem |
- Required Only If Content Insufficient | -
-
|
-
menuitemcheckbox |
- Required Only If Content Insufficient | -
-
|
-
menuitemradio |
- Required Only If Content Insufficient | -
-
|
-
meter |
- Required | -
-
|
-
navigation |
- Recommended | -
-
|
-
none |
- Prohibited | -An element with role="none" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label. |
-
note |
- Discretionary | -
-
|
-
option |
- Required Only If Content Insufficient | -
-
|
-
paragraph |
- Prohibited | -- |
presentation |
- Prohibited | -An element with role="presentation" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label. |
-
progressbar |
- Required | -
-
|
-
radio |
- Required Only If Content Insufficient | -
-
|
-
radiogroup |
- Required | -
-
|
-
region |
- Required | -
-
|
-
row |
-
- Required Only If Content Insufficient
- AND descendant of a treegrid
- AND the row is focusable
- |
-
- When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row.
- This is typically the most appropriate behavior.
- However, in some circumstances, it could be beneficial to change the order in which cells are announced or exclude announcement of certain cells by using aria-labelledby to specify which cells to announce.
- |
-
rowgroup |
- Do Not Name | -Naming is not supported by assistive technologies. | -
rowheader |
- Required Only If Content Insufficient | -
-
|
-
scrollbar |
- Discretionary | -
-
|
-
search |
- Recommended | -
-
|
-
searchbox |
- Required | -
-
|
-
separator |
- Discretionary | -
-
|
-
slider |
- Required | -
-
|
-
spinbutton |
- Required | -
-
|
-
status |
- Discretionary | -
- Some screen readers announce the name of a status element before announcing the content of the status element.
- Thus, aria-label provides a method for prefacing the visible content of a status element with text that is not displayed as part of the status element.
- Using aria-label is functionally equivalent to providing off-screen text in the contents of the status element, except off-screen text would be announced by screen readers that do not support aria-label on status elements.
- |
-
strong |
- Prohibited | -- |
subscript |
- Prohibited | -- |
superscript |
- Prohibited | -- |
switch |
- Required Only If Content Insufficient | -
-
|
-
tab |
- Required Only If Content Insufficient | -
-
|
-
table |
- Required | -
-
|
-
tablist |
- Recommended | -
-
|
-
tabpanel |
- Required | -
-
|
-
term |
- Do Not Name | -Since a term is usually the name for the role="definition" element, it could be confusing if the term itself also has a name. |
-
textbox |
- Required | -
-
|
-
time |
- Do Not Name | -Naming is not supported by assistive technologies. | -
timer |
- Discretionary | -
- Some screen readers announce the name of a timer element before announcing the content of the timer element.
- Thus, aria-label provides a method for prefacing the visible content of a timer element with text that is not displayed as part of the timer element.
- Using aria-label is functionally equivalent to providing off-screen text in the contents of the timer element, except off-screen text would be announced by screen readers that do not support aria-label on timer elements.
- |
-
toolbar |
- Recommended | -
-
|
-
tooltip |
- Required Only If Content Insufficient | -
-
|
-
tree |
- Required | -
-
|
-
treegrid |
- Required | -
-
|
-
treeitem |
- Required Only If Content Insufficient | -
-
|
-
- User agents construct an accessible name string for an element by walking through a list of potential naming methods and using the first that generates a name. - The algorithm they follow is defined in the accessible name specification. - It is roughly like the following: -
-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 host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:
-input whose type attribute is in the Button, Submit Button, or Reset Button statevalue attribute.input whose type attribute is in the Image Button stateimgareaalt attribute. fieldsetlegend element.label element(s).figurefigcaption element.tablecaption element.If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.
Finally, if the name is still empty, then other fallback host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:
-input whose type attribute is in the Text, Password, Search, Telephone, or URL statestextareatitle attribute. Otherwise, the placeholder attribute.input whose type attribute is in the Submit Button stateinput whose type attribute is in the Reset Button stateinput whose type attribute is in the Image Button statetitle attribute. Otherwise, a localized string of the phrase "Submit Query".summarytitle attribute.- The final step is a fallback mechanism. Generally when labeling an element, use one of the non-fallback mechanisms. -
-
- When calculating a name from content, the user agent walks through all descendant nodes except in the cases of treeitem and menuitem as described below.
- And, when following references in an aria-labelledby attribute, it similarly walks the tree of each referenced element.
- Thus, the naming algorithm is recursive.
- The following two sections explain non-recursive and recursive examples of how the algorithm works.
-
- When calculating a name from content for the treeitem role, descendant content of child group elements are not included.
- For example, in the following tree, the name of the first tree item is Fruits
; Apples
, Bananas
, and Oranges
are automatically omitted.
-
<ul role="tree">
- <li role="treeitem">Fruits
- <ul role="group">
- <li role="treeitem">Apples</li>
- <li role="treeitem">Bananas</li>
- <li role="treeitem">Oranges</li>
- </ul>
- </li>
-</ul>
- Similarly, when calculating a name from content for the menuitem role, descendant content of child menu elements are not included.
- So, the name of the first parent menuitem in the following menu is Fruits
.
-
<ul role="menu">
- <li role="menuitem">Fruits
- <ul role="menu">
- <li role="menuitem">Apples</li>
- <li role="menuitem">Bananas</li>
- <li role="menuitem">Oranges</li>
- </ul>
- </li>
-</ul>Consider an input element that has no associated label element and only a name attribute and so does not have an accessible name (do not do this):
<input name="code">If there is a placeholder attribute, then it serves as a naming fallback mechanism (avoid doing this):
<input name="code"
- placeholder="One-time code">If there is also a title attribute, then it is used as the accessible name instead of placeholder, but it is still a fallback (avoid doing this):
<input name="code"
- placeholder="123456"
- title="One-time code">If there is also a label element (recommended), then that is used as the accessible name, and the title attribute is instead used as the accessible description:
<label>One-time code
- <input name="code"
- placeholder="123456"
- title="Get your code from the app.">
-</label>If there is also an aria-label attribute (not recommended unless it adds clarity for assistive technology users), then that becomes the accessible name, overriding the label element:
<label>Code
- <input name="code"
- aria-label="One-time code"
- placeholder="123456"
- title="Get your code from the app.">
-</label>If there is also an aria-labelledby attribute, that wins over the other elements and attributes (the aria-label attribute ought to be removed if it is not used):
<p>Please fill in your <span id="code-label">one-time code</span> to log in.</p>
-<p>
- <label>Code
- <input name="code"
- aria-labelledby="code-label"
- aria-label="This is ignored"
- placeholder="123456"
- title="Get your code from the app.">
- </label>
-</p>The accessible name calculation algorithm will be invoked recursively when necessary. An aria-labelledby reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.
In this example, the label for the button is computed by recursing into each child node, resulting in Move to trash
.
<button>Move to <img src="bin.svg" alt="trash"></button>When following an aria-labelledby reference, the algorithm avoids following the same reference twice to avoid infinite loops.
In this example, the label for the button is computed by first following the aria-labelledby reference to the parent element, and then computing the label for that element from the child nodes, first visiting the button element again but ignoring the aria-labelledby reference and instead using the aria-label, and then visiting the next child (the text node). The resulting label is Remove meeting: Daily status report
.
<div id="meeting-1">
- <button aria-labelledby="meeting-1" aria-label="Remove meeting:">X</button>
- Daily status report
-</div>aria-describedby
- The aria-describedby property works similarly to the aria-labelledby property.
- For example, a button could be described by a sibling paragraph.
-
<button aria-describedby="trash-desc">Move to trash</button>
-...
-<p id="trash-desc">Items in the trash will be permanently removed after 30 days.</p>Descriptions are reduced to text strings. For example, if the description contains an HTML img element, a text equivalent of the image is computed.
<button aria-describedby="trash-desc">Move to <img src="bin.svg" alt="trash"></button>
-...
-<p id="trash-desc">Items in <img src="bin.svg" alt="the trash"> will be permanently removed after 30 days.</p>
- As with aria-labelledby, it is possible to reference an element using aria-describedby even if that element is hidden.
- For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget.
- The description could also be referenced from the text field directly with aria-describedby.
- In the following example, the accessible description for the input element is Your username is the name that you use to log in to this service.
-
<label for="username">Username</label>
-<input id="username" name="username" aria-describedby="username-desc">
-<button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
-<p id="username-desc" hidden>
- Your username is the name that you use to log in to this service.
-</p>
- In HTML, if the table is named using aria-label or aria-labelledby, a child caption element becomes an accessible description.
- For example, a preceding heading might serve as an appropriate accessible name, and the caption element might contain a longer description.
- In such a situation, aria-labelledby could be used on the table to set the accessible name to the heading content and the caption would become the accessible description.
-
<h2 id="events-heading">Upcoming events</h2>
-<table aria-labelledby="events-heading">
- <caption>
- Calendar of upcoming events, weeks 27 through 31, with each week starting with
- Monday. The first column is the week number.
- </caption>
- <tr><th>Week</th><th>Monday</th><th>Tuesday</th><th>Wednesday</th><th>Thursday</th><th>Friday</th><th>Saturday</th><th>Sunday</th></tr>
- <tr><td>27</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
- <tr><td>28</td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/events/9856">Crown Princess's birthday</a></td></tr>
- <tr><td>29</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
- <tr><td>30</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
- <tr><td>31</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
-</table>The HTML figure element can get its accessible name from its figcaption element, but it will not be used as the accessible description, even if it was not used as the accessible name. If the figcaption element is appropriate as an accessible description, and the accessible name is set using aria-labelledby or aria-label, then the figcaption can be explicitly set as the accessible description using the aria-describedby attribute.
<h2 id="neutron">Neutron</h2>
-<figure aria-labelledby="neutron" aria-describedby="neutron-caption">
- <img src="neutron.svg" alt="Within the neutron are three quarks (blue 'u',
- red 'd', green 'd') that are interconnected.">
- <figcaption id="neutron-caption">
- The quark content of the neutron. The color assignment of individual quarks is
- arbitrary, but all three colors must be present. Forces between quarks are
- mediated by gluons.
- </figcaption>
-</figure>If an accessible description was not provided using the aria-describedby attribute or one of the primary host-language-specific attributes or elements (e.g., the caption element for table), then, for HTML, if the element has a title attribute, that is used as the accessible description.
A visible description together with aria-describedby is generally recommended. If a description that is not visible is desired, then the title attribute can be used, for any HTML element that can have an accessible description.
Note that the title attribute might not be accessible to some users, in particular sighted users not using a screen reader and not using a pointing device that supports hover (e.g., a mouse).
For example, an input element with input constrained using the pattern attribute can use the title attribute to describe what the expected input is.
<label> Part number:
- <input pattern="[0-9][A-Z]{3}" name="part"
- title="A part number is a digit followed by three uppercase letters."/>
-</label>The title attribute in this case can be shown to the user as a tooltip when the user hovers or focuses the control, but also as part of the error message when the user agent validates the form, if the input element's value doesn't match the pattern.
As another example, a link can use the title attribute to describe the link in more detail.
<a href="http://twitter.com/W3C"
- title="Follow W3C on Twitter">
- <img src="/2008/site/images/Twitter_bird_logo_2012.svg"
- alt="Twitter" class="social-icon" height="40" />
-</a>- Like the accessible name calculation, the accessible description calculation produces a text string. -
-
- The accessible description calculation algorithm is the same as the accessible name calculation algorithm except for a few branch points that depend on whether a name or description is being calculated.
- In particular, when accumulating text for an accessible description, the algorithm uses aria-describedby instead of aria-labelledby.
-
- User agents construct an accessible description string for an element by walking through a list of potential description methods and using the first that generates a description. - The algorithm they follow is defined in the accessible name specification. - It is roughly like the following: -
-The aria-describedby property is used if present.
If the description is still empty, then host-language-specific attributes or elements are used if present, if it wasn't already used as the accessible name. For HTML, these are, depending on the element:
-input whose type attribute is in the Button, Submit Button, or Reset Button statevalue attribute.summarytablecaption element.Finally, if the description is still empty, then other host-language-specific attributes or elements are used if present, if it wasn't already used for the accessible name. For HTML, this is the title attribute.
- Unlike native HTML form elements, browsers do not provide keyboard support for graphical user interface (GUI) components that are made accessible with ARIA; authors have to provide the keyboard support in their code. - This section describes the principles and methods for making the functionality of a web page that includes ARIA widgets, such as menus and grids, as well as interactive components, such as toolbars and dialogs, operable with a keyboard. - Along with the basics of focus management, this section offers guidance toward the objective of providing experiences to people who rely on a keyboard that are as efficient and enjoyable as the experiences available to others. -
-This section covers:
-Work to complete this section is tracked by issue 217.
-- When operating with a keyboard, two essentials of a good experience are the abilities to easily discern the location of the keyboard focus and to discover where focus landed after a navigation key has been pressed. - The following factors affect to what extent a web page affords users these capabilities. -
- -- Occasionally, it may appear as if two elements on the page have focus at the same time. - For example, in a multi-select list box, when an option is selected it may be greyed. - Yet, the focus indicator can still be moved to other options, which may also be selected. - Similarly, when a user activates a tab in a tablist, the selected state is set on the tab and its visual appearance changes. - However, the user can still navigate, moving the focus indicator elsewhere on the page while the tab retains its selected appearance and state. -
- -- Focus and selection are quite different. - From the keyboard user's perspective, focus is a pointer, like a mouse pointer; it tracks the path of navigation. - There is only one point of focus at any time and all operations take place at the point of focus. - On the other hand, selection is an operation that can be performed in some widgets, such as list boxes, trees, and tablists. - If a widget supports only single selection, then only one item can be selected and very often the selected state will simply follow the focus when focus is moved inside of the widget. - That is, in some widgets, moving focus may also perform the select operation. - However, if the widget supports multiple selection, then more than one item can be in a selected state, and keys for moving focus do not perform selection. - Some multi-select widgets do support key commands that both move focus and change selection, but those keys are different from the normal navigation keys. - Finally, when focus leaves a widget that includes a selected element, the selected state persists. -
- -
- From the developer's perspective, the difference is simple -- the focused element is the active element (document.activeElement).
- Selected elements are elements that have aria-selected="true".
-
With respect to focus and the selected state, the most important considerations for designers and developers are:
- -in composite widgets where only one element may be selected, such as a tablist or single-select listbox, moving the focus may also cause the focused element to become the selected element. This is called having selection follow focus. Having selection follow focus is often beneficial to users, but in some circumstances, it is extremely detrimental to accessibility.
-- For example, in a tablist, the selected state is used to indicate which panel is displayed. - So, when selection follows focus in a tablist, moving focus from one tab to another automatically changes which panel is displayed. - If the content of panels is present in the DOM, then displaying a new panel is nearly instantaneous. - A keyboard user who wishes to display the fourth of six tabs can do so with 3 quick presses of the right arrow. - And, a screen reader user who perceives the labels on tabs by navigating through them may efficiently read through the complete list without any latency. -
-However, if displaying a new panel causes a network request and possibly a page refresh, the effect of having selection automatically focus can be devastating to the experience for keyboard and screen reader users. In this case, displaying the fourth tab or reading through the list becomes a tedious and time-consuming task as the user experiences significant latency with each movement of focus. Further, if displaying a new tab refreshes the page, then the user not only has to wait for the new page to load but also return focus to the tab list.
-- When selection does not follow focus, the user changes which element is selected by pressing the Enter or Space key. -
-As explained in section , all interactive UI components need to be reachable via the keyboard. This is best achieved by either including them in the tab sequence or by making them accessible from a component that is in the tab sequence, e.g., as part of a composite component. This section addresses building and managing the tab sequence, and subsequent sections cover making focusable elements that are contained within components keyboard accessible.
- -- The [[HTML]] tabindex and [[SVG2]] tabindex attributes can be used to add and remove elements from the tab sequence. - The value of tabindex can also influence the order of the tab sequence, although authors are strongly advised not to use tabindex for that purpose. -
- -- In HTML, the default tab sequence of a web page includes only links and HTML form elements, except In macOS, where it includes only form elements. - macOS system preferences include a keyboard setting that enables the tab key to move focus to all focusable elements. -
- -- The default order of elements in the tab sequence is the order of elements in the DOM. - The DOM order also determines screen reader reading order. - It is important to keep the keyboard tab sequence and the screen reader reading order aligned, logical, and predictable as described in . - The most robust method of manipulating the order of the tab sequence while also maintaining alignment with the reading order that is currently available in all browsers is rearranging elements in the DOM. -
- -The values of the tabindex attribute have the following effects.
- -- As described in section , the tab sequence should include only one focusable element of a composite UI component. - Once a composite contains focus, keys other than Tab and Shift + Tab enable the user to move focus among its focusable elements. - Authors are free to choose which keys move focus inside of a composite, but they are strongly advised to use the same key bindings as similar components in common GUI operating systems as demonstrated in . -
- -The convention for where focus lands in a composite when it receives focus as a result of a Tab key event depends on the type of composite. It is typically one of the following.
- -- The following sections explain two strategies for managing focus inside composite elements: creating a roving tabindex and using the aria-activedescendant property. -
- -- When using roving tabindex to manage focus in a composite UI component, the element that is to be included in the tab sequence has tabindex of "0" and all other focusable elements contained in the composite have tabindex of "-1". - The algorithm for the roving tabindex strategy is as follows. -
- -tabindex="0" on the element that will initially be included in the tab sequence and set tabindex="-1" on all other focusable elements it contains.tabindex="-1" on the element that has tabindex="0".tabindex="0" on the element that will become focused as a result of the key event.element.focus(), on the element that has tabindex="0".tabindex="0" when the composite loses focus.
- If it does not, set tabindex="0" on the target element and set tabindex="-1" on the element that previously had tabindex="0".
- - One benefit of using roving tabindex rather than aria-activedescendant to manage focus is that the user agent will scroll the newly focused element into view. -
-- If a component container has an ARIA role that supports the aria-activedescendant property, it is not necessary to manipulate the tabindex attribute and move DOM focus among focusable elements within the container. - Instead, only the container element needs to be included in the tab sequence. When the container has DOM focus, the value of aria-activedescendant on the container tells assistive technologies which element is active within the widget. - Assistive technologies will consider the element referred to as active to be the focused element even though DOM focus is on the element that has the aria-activedescendant property. - And, when the value of aria-activedescendant is changed, assistive technologies will receive focus change events equivalent to those received when DOM focus actually moves. -
- -The steps for using the aria-activedescendant method of managing focus are as follows.
- -aria-activedescendant="IDREF" where IDREF is the ID of the element within the container that should be identified as active when the widget receives focus.
- The referenced element needs to meet the DOM relationship requirements described below.
- - The specification for aria-activedescendant places important restrictions on the DOM relationship between the focused element that has the aria-activedescendant attribute and the element referenced as active by the value of the attribute. - One of the following three conditions must be met. -
-- By default, disabled HTML input elements are removed from the tab sequence. - In most contexts, the normal expectation is that disabled interactive elements are not focusable. - However, there are some contexts where it is common for disabled elements to be focusable, especially inside of composite widgets. - For example, as demonstrated in the pattern, disabled items are focusable when navigating through a menu with the arrow keys. -
- -- Removing focusability from disabled elements can offer users both advantages and disadvantages. - Allowing keyboard users to skip disabled elements usually reduces the number of key presses required to complete a task. - However, preventing focus from moving to disabled elements can hide their presence from screen reader users who "see" by moving the focus. -
- -- Authors are encouraged to adopt a consistent set of conventions for the focusability of disabled elements. - The examples in this guide adopt the following conventions, which both reflect common practice and attempt to balance competing concerns. -
- -One design technique for mitigating the impact of including disabled elements in the path of keyboard focus is employing appropriate keyboard shortcuts as described in .
-- The following key assignments can be used in any context where their conventionally associated functions are appropriate. - While the assignments associated with Windows and Linux platforms can be implemented and used in browsers running in macOS, - replacing them with macOS assignments in browsers running on a macOS device can make the keyboard interface more discoverable and intuitive for those users. - In some cases, it may also help avoid system or browser keyboard conflicts. -
-| Function | -Windows/Linux Key | -macOS Key | -
|---|---|---|
| open context menu | -Shift + F10 | -- |
| Copy to clipboard | -Control + C | -Command + C | -
| Paste from clipboard | -Control + V | -Command + V | -
| Cut to clipboard | -Control + X | -Command + X | -
| undo last action | -Control + Z | -Command + Z | -
| Redo action | -Control + Y | -Command + Shift + Z | -
- When effectively designed, keyboard shortcuts that focus an element, activate a widget, or both can dramatically enhance usability of frequently used features of a page or site. - This section addresses some of the keyboard shortcut design and implementation factors that most impact their effectiveness, including: -
-This section explains the following factors when determining which elements and features to assign keyboard shortcuts and what behavior to give each shortcut:
- -- Before assigning keyboard shortcuts, it is essential to ensure the features and functions to which shortcuts may be assigned are keyboard accessible without a keyboard shortcut. - In other words, all elements that could be targets for keyboard shortcuts need to be focusable via the keyboard using the methods described in: -
- - - -- Do not use keyboard shortcuts as a substitute for access via navigation. - This is essential to full keyboard access because: -
- -The following conventions may help identify the most advantageous behavior for a keyboard shortcut.
- -Work to draft content for this section is tracked in issue 219.
-The first goal when designing a keyboard interface is simple, efficient, and intuitive operation with only basic keyboard navigation support. If basic operation of a keyboard interface is inefficient, attempting to compensate for fundamental design issues, such as suboptimal layout or command structure, by implementing keyboard shortcuts will not likely reduce user frustration. The practical implication of this is that, in most well-designed user interfaces, the percentage of functionality that needs to be accessible via a keyboard shortcut in order to create optimal usability is not very high. In many simple user interfaces, keyboard shortcuts can be entirely superfluous. And, in user interfaces with too many keyboard shortcuts, the excess shortcuts create cognitive load that make the most useful ones more difficult to remember.
-Consider the following when deciding where to assign keyboard shortcuts:
- -When choosing the keys to assign to a shortcut, there are many factors to consider.
-- Methods for designing a key shortcut scheme that supports learning and memory is beyond the scope of this guide. - Unless the key shortcut scheme is extensive, it is likely sufficient to mimic concepts that are familiar from common desktop software, such as browsers. - Similarly, while localization is important, describing how to address it is left to other resources that specialize in that topic. -
-- The remainder of this section provides guidance balancing requirements and concerns related to key assignment conflicts. - It is typically ideal if key assignments do not conflict with keys that are assigned to functions in the user's operating system, browser, or assistive technology. - Conflicts can block efficient access to functions that are essential to the user, and a perfect storm of conflicts can trap a user. - At the same time, there are some circumstances where intentional conflicts are useful. - And, given the vast array of operating system, browser, and assistive technology keys, it is almost impossible to be certain conflicts do not exist. - So it is also important to employ strategies that mitigate the impact of conflicts whether they are intentional or unknown. -
-- In the following sections, meta key refers to the Windows key on Windows-compatible keyboards and the Command key on MacOS-compatible keyboards. -
-It is essential to avoid conflicts with keys that perform system level functions, such as application and window management and display and sound control. In general, this can be achieved by refraining from the following types of assignments.
- -- In addition, there are some important application level features that most applications, including browsers, generally support. - These include: -
- -- Even though assistive technologies have collectively taken thousands of key assignments, avoiding conflicts is relatively easy. - This is because assistive technologies have had to develop key assignment schemes that avoid conflicts with both operating systems and applications. - They do this by hijacking specific keys as modifiers that uniquely define their key commands. - For example, many assistive technologies use the Caps Lock key as a modifier. -
- -Deflect assistive technology key conflicts by steering clear of the following types of assignments.
- -While there is considerable similarity among browser keyboard schemes, the patterns within the schemes are less homogenous. Consequently, it is more difficult to avoid conflicts with browser key assignments. While the impact of conflicts is sometimes mitigated by the availability of two paths to nearly every function -- keyboard accessible menus and keyboard shortcuts, avoiding conflicts with shortcuts to heavily used functions is nonetheless important. Pay special attention to avoiding conflicts with shortcuts to:
- -- While avoiding key conflicts is usually desirable, there are circumstances where intentionally conflicting with a browser function is acceptable or even desirable. - This can occur when the following combination of conditions arises: -
- -For example, consider a save function that is available when the focus is in an editor. Most browsers use ... to be continued ...
-- To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the - grid pattern or table pattern, - assistive technologies need to be able to determine: -
-- Browsers automatically populate their accessibility tree with the number of rows and columns in a grid or table based on the rendered DOM. - However, there are many situations where the DOM does not contain the whole grid or table, such as when the data set is too large to fully render. - Additionally, some of this information, like skipped columns or rows and how data is sorted, cannot be derived from the DOM structure. -
-The below sections explain how to use the following properties that ARIA provides for grid and table accessibility.
-| Property | -Definition | -
|---|---|
aria-colcount |
- Defines the total number of columns in a table, grid, or treegrid. |
-
aria-rowcount |
- Defines the total number of rows in a table, grid, or treegrid. |
-
aria-colindex |
-
-
|
-
aria-rowindex |
-
-
|
-
aria-colspan |
- Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. |
-
aria-rowspan |
- Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. |
-
aria-sort |
- Indicates if items in a row or column are sorted in ascending or descending order. | -
aria-rowcount and aria-rowindex
- When the number of rows represented by the DOM structure is not the total number of rows available for a table, grid, or treegrid,
- the aria-rowcount property is used to communicate the total number of rows available,
- and it is accompanied by the aria-rowindex property to identify the row indices of the rows that are present in the DOM.
-
- The aria-rowcount is specified on the element with the table, grid, or treegrid role.
- Its value is an integer equal to the total number of rows available, including header rows.
- If the total number of rows is unknown, a value of -1 may be specified.
- Using a value of -1 indicates that more rows are available to include in the DOM without specifying the size of the available supply.
-
- When aria-rowcount is used on a table, grid, or treegrid,
- a value for aria-rowindex property is specified on each of its descendant rows, including any header rows.
- The value of aria-rowindex is an integer that is:
-
aria-rowindex on any previous rows.
- WARNING! Missing or inconsistent values of aria-rowindex could have devastating effects on assistive technology behavior.
- For example, specifying an invalid value for aria-rowindex or setting it on some but not all rows in a table, could cause screen reader table reading functions to skip rows or simply stop functioning.
-
- The following code demonstrates the use of aria-rowcount and aria-rowindex properties on a table containing a hypothetical class list.
-
-
- <!--
- aria-rowcount tells assistive technologies the actual size of the grid
- is 463 rows even though only 4 rows are present in the markup.
- -->
- <table role="grid" aria-rowcount="463">
- aria-label="Student roster for history 101"
- <thead>
- <tr aria-rowindex="1">
- <th>Last Name</th>
- <th>First Name</th>
- <th>E-mail</th>
- <th>Major</th>
- <th>Minor</th>
- <th>Standing</th>
- </tr>
- </thead>
- <tbody>
- <!--
- aria-rowindex tells assistive technologies that this
- row is row 51 in the grid of 463 rows.
- -->
- <tr aria-rowindex="51">
- <td>Henderson</td>
- <td>Alan</td>
- <td>ahederson56@myuniveristy.edu</td>
- <td>Business</td>
- <td>Spanish</td>
- <td>Junior</td>
- </tr>
- <!--
- aria-rowindex tells assistive technologies that this
- row is row 52 in the grid of 463 rows.
- -->
- <tr aria-rowindex="52">
- <td>Henderson</td>
- <td>Alice</td>
- <td>ahederson345@myuniveristy.edu</td>
- <td>Engineering</td>
- <td>none</td>
- <td>Sophomore</td>
- </tr>
- <!--
- aria-rowindex tells assistive technologies that this
- row is row 53 in the grid of 463 rows.
- -->
- <tr aria-rowindex="53">
- <td>Henderson</td>
- <td>Andrew</td>
- <td>ahederson75@myuniveristy.edu</td>
- <td>General Studies</td>
- <td>none</td>
- <td>Freshman</td>
- </tr>
- </tbody>
- </table>
-
-
- aria-colcount and aria-colindex
- When the number of columns represented by the DOM structure is not the total number of columns available for a table, grid, or treegrid,
- the aria-colcount property is used to communicate the total number of columns available,
- and it is accompanied by the aria-colindex property to identify the column indices of the columns that are present in the DOM.
-
- The aria-colcount is specified on the element with the table, grid, or treegrid role.
- Its value is an integer equal to the total number of columns available.
- If the total number of columns is unknown, a value of -1 may be specified.
- Using a value of -1 indicates that more columns are available to include in the DOM without specifying the size of the available supply.
-
- When aria-colcount is used on a table, grid, or treegrid,
- a value for aria-colindex property is either specified on each of its descendant rows or on every cell in each descendant row, depending on whether the columns are contiguous as described below.
- The value of aria-colindex is an integer that is:
-
- WARNING! Missing or inconsistent values of aria-colindex could have devastating effects on assistive technology behavior.
- For example, specifying an invalid value for aria-colindex or setting it on some but not all cells in a row, could cause screen reader table reading functions to skip cells or simply stop functioning.
-
aria-colindex When Column Indices Are Contiguous
- When all the cells in a row have column index numbers that are consecutive integers,
- aria-colindex can be set on the row element with a value equal to the index number of the first column in the set.
- Browsers will then compute a column number for each cell in the row.
-
- The following code shows a grid with 16 columns, of which columns 2 through 5 are displayed to the user.
- Because the set of columns is contiguous, aria-colindex can be placed on each row.
-
-
-<div role="grid" aria-colcount="16">
- <div role="rowgroup">
- <div role="row" aria-colindex="2">
- <span role="columnheader">First Name</span>
- <span role="columnheader">Last Name</span>
- <span role="columnheader">Company</span>
- <span role="columnheader">Address</span>
- </div>
- </div>
- <div role="rowgroup">
- <div role="row" aria-colindex="2">
- <span role="gridcell">Fred</span>
- <span role="gridcell">Jackson</span>
- <span role="gridcell">Acme, Inc.</span>
- <span role="gridcell">123 Broad St.</span>
- </div>
- <div role="row" aria-colindex="2">
- <span role="gridcell">Sara</span>
- <span role="gridcell">James</span>
- <span role="gridcell">Acme, Inc.</span>
- <span role="gridcell">123 Broad St.</span>
- </div>
- …
- </div>
-</div>
-
-
- aria-colindex When Column Indices Are Not Contiguous
- When the cells in a row have column index numbers that are not consecutive integers, aria-colindex needs to be set on each cell in the row.
- The following example shows a grid for an online grade book where the first two columns contain a student name and subsequent columns contain scores.
- In this example, the first two columns with the student name are shown, but the score columns have been scrolled to show columns 10 through 13.
- Columns 3 through 9 are not visible so are not in the DOM.
-
-
- <table role="grid" aria-rowcount="463" aria-colcount="13">
- aria-label="Student grades for history 101"
- <!--
- aria-rowcount and aria-colcount tell assistive technologies
- the actual size of the grid is 463 rows by 13 columns,
- which is not the number rows and columns found in the markup.
- -->
- <thead>
- <tr aria-rowindex="1">
- <!--
- aria-colindex tells assistive technologies that the
- following columns represent columns 1 and 2 of the total data set.
- -->
- <th aria-colindex="1">Last Name</th>
- <th aria-colindex="2">First Name</th>
- <!--
- aria-colindex tells users of assistive technologies that the
- following columns represent columns 10, 11, 12, and 13 of
- the overall data set of grades.
- -->
- <th aria-colindex="10">Homework 4</th>
- <th aria-colindex="11">Quiz 2</th>
- <th aria-colindex="12">Homework 5</th>
- <th aria-colindex="13">Homework 6</th>
- </tr>
- </thead>
- <tbody>
- <tr aria-rowindex="50">
- <!--
- every cell needs to define the aria-colindex attribute
- -->
- <td aria-colindex="1">Henderson</td>
- <td aria-colindex="2">Alan</td>
- <td aria-colindex="10">8</td>
- <td aria-colindex="11">25</td>
- <td aria-colindex="12">9</td>
- <td aria-colindex="13">9</td>
- </tr>
- <tr aria-rowindex="51">
- <td aria-colindex="1">Henderson</td>
- <td aria-colindex="2">Alice</td>
- <td aria-colindex="10">10</td>
- <td aria-colindex="11">27</td>
- <td aria-colindex="12">10</td>
- <td aria-colindex="13">8</td>
- </tr>
- <tr aria-rowindex="52">
- <td aria-colindex="1">Henderson</td>
- <td aria-colindex="2">Andrew</td>
- <td aria-colindex="10">9</td>
- <td aria-colindex="11">0</td>
- <td aria-colindex="12">29</td>
- <td aria-colindex="13">8</td>
- </tr>
- </tbody>
- </table>
-
-
- aria-colspan and aria-rowspan
- For tables, grids, and treegrids created using elements other than HTML table elements,
- row and column spans are defined with the aria-rowspan and aria-colspan properties.
-
The value of aria-colspan is an integer that is:
The value of aria-rowspan is an integer that is:
- The following example grid has a two row header. - The first two columns have headers that span both rows of the header. - The subsequent 6 columns are grouped into 3 pairs with headers in the first row that each span two columns. -
-
-
- <div role="grid" aria-rowcount="463">
- aria-label="Student grades for history 101"
- <div role="rowgroup">
- <div role="row" aria-rowindex="1">
- <!--
- aria-rowspan and aria-colspan provide
- assistive technologies with the correct data cell header information
- when header cells span more than one row or column.
- -->
- <span role="columnheader" aria-rowspan="2">Last Name</span>
- <span role="columnheader" aria-rowspan="2">First Name</span>
- <span role="columnheader" aria-colspan="2">Test 1</span>
- <span role="columnheader" aria-colspan="2">Test 2</span>
- <span role="columnheader" aria-colspan="2">Final</span>
- </div>
- <div role="row" aria-rowindex="2">
- <span role="columnheader">Score</span>
- <span role="columnheader">Grade</span>
- <span role="columnheader">Score</span>
- <span role="columnheader">Grade</span>
- <span role="columnheader">Total</span>
- <span role="columnheader">Grade</span>
- </div>
- </div>
- <div role="rowgroup">
- <div role="row" aria-rowindex="50">
- <span role="cell">Henderson</span>
- <span role="cell">Alan</span>
- <span role="cell">89</span>
- <span role="cell">B+</span>
- <span role="cell">72</span>
- <span role="cell">C</span>
- <span role="cell">161</span>
- <span role="cell">B-</span>
- </div>
- <div role="row" aria-rowindex="51">
- <span role="cell">Henderson</span>
- <span role="cell">Alice</span>
- <span role="cell">94</span>
- <span role="cell">A</span>
- <span role="cell">86</span>
- <span role="cell">B</span>
- <span role="cell">180</span>
- <span role="cell">A-</span>
- </div>
- <div role="row" aria-rowindex="52">
- <span role="cell">Henderson</span>
- <span role="cell">Andrew</span>
- <span role="cell">82</span>
- <span role="cell">B-</span>
- <span role="cell">95</span>
- <span role="cell">A</span>
- <span role="cell">177</span>
- <span role="cell">B+</span>
- </div>
- </div>
- </div>
-
-
-
- Note: When using HTML table elements,
- use the native semantics of the th and td elements to define row and column spans
- by using the rowspan and colspan attributes.
-
aria-sort
- When rows or columns are sorted, the aria-sort property can be applied to a column or row header to indicate the sorting method.
- The following table describes allowed values for aria-sort.
-
| Value | -Description | -
|---|---|
ascending |
- Data are sorted in ascending order. | -
descending |
- Data are sorted in descending order. | -
other |
- Data are sorted by an algorithm other than ascending or descending. | -
none |
- Default (no sort applied). | -
- It is important to note that ARIA does not provide a way to indicate levels of sort for data sets that have multiple sort keys.
- Thus, there is limited value to applying aria-sort with a value other than none to more than one column or row.
-
The following example grid uses aria-sort to indicate the rows are sorted from the highest "Quiz 2" score to the lowest "Quiz 2" score.
-
- <table role="grid" aria-rowcount="463" aria-colcount="13"
- aria-label="Student grades for history 101">
- <thead>
- <tr aria-colindex="10" aria-rowindex="1">
- <th>Homework 4</th>
- <!--
- aria-sort indicates the column with the heading
- "Quiz 2" has been used to sort the rows of the grid.
- -->
- <th aria-sort="descending">Quiz 2</th>
- <th>Homework 5</th>
- <th>Homework 6</th>
- </tr>
- </thead>
- <tbody>
- <tr aria-colindex="10" aria-rowindex="50">
- <td>8</td>
- <td>30</td>
- <td>9</td>
- <td>9</td>
- </tr>
- <tr aria-colindex="10" aria-rowindex="51">
- <td>10</td>
- <td>29</td>
- <td>10</td>
- <td>8</td>
- </tr>
- <tr aria-colindex="10" aria-rowindex="52">
- <td>9</td>
- <td>9</td>
- <td>27</td>
- <td>6</td>
- </tr>
- <tr aria-colindex="10" aria-rowindex="53">
- <td>9</td>
- <td>10</td>
- <td>26</td>
- <td>8</td>
- </tr>
- <tr aria-colindex="10" aria-rowindex="54">
- <td>9</td>
- <td>7</td>
- <td>24</td>
- <td>6</td>
- </tr>
- </tbody>
- </table>
-
-
-
-
- presentation Role
- While ARIA is primarily used to express semantics, there are some situations where hiding an
- element’s semantics from assistive technologies is helpful. This is done with the
- presentation
- role, which declares that an element is being used only for presentation and therefore does
- not have any accessibility semantics. The ARIA 1.1 specification also includes role
- none,
- which serves as a synonym for presentation.
-
- For example, consider a tabs widget built using an HTML ul element.
-
- <ul role="tablist"> - <li role="presentation"> - <a role="tab" href="#">Tab 1</a> - </li> - <li role="presentation"> - <a role="tab" href="#">Tab 2</a> - </li> - <li role="presentation"> - <a role="tab" href="#">Tab 3</a> - </li> - </ul> --
- Because the list is declared to be a tablist, the list items are not in a list context. It
- could confuse users if an assistive technology were to render those list items. Applying role
- presentation to the li elements tells browsers to leave those
- elements out of their accessibility tree. Assistive technologies will thus be unaware of the
- list item elements and see the tab elements as immediate children of the tablist.
-
- Three common uses of role presentation are:
-
presentation
-
- When role="presentation" is specified on an element, if a
- condition that requires a browser to ignore the presentation role
- does not exist, it has the following three effects.
-
display: none or has aria-hidden="true".
- presentation is applied to a ul or ol element, each child li element inherits the presentation role because ARIA requires the listitem elements to have the parent list element. So, the li elements are not exposed to assistive technologies, but elements contained inside of those li elements, including nested lists, are visible to assistive technologies. presentation is applied to a table element,
- the descendant caption, thead, tbody, tfoot,
- tr, th, and td
- elements inherit role presentation and are thus not exposed to assistive technologies.
- But, elements inside of the th and td elements, including nested tables, are exposed to assistive technologies.
- presentation to be Ignored
-
- Browsers ignore role="presentation", and it therefore has no effect, if either of the following are true about the element to which it is applied:
tabindex attribute.aria-label.
- presentation Role
- This code:
-- <ul role="presentation"> - <li>Date of birth:</li> - <li>January 1, 3456</li> - </ul> --
when parsed by a browser, is equivalent to the following from the perspective of a screen reader or other assistive technology that relies on the browser's accessibility tree: -
-- <div>Date of birth:</div> - <div>January 1, 3456</div> --
- There are some types of user interface components that, when represented in a platform
- accessibility API, can only contain text. For example, accessibility APIs do not have a way of
- representing semantic elements contained in a button. To deal with this limitation, WAI-ARIA
- requires browsers to automatically apply role presentation to all descendant
- elements of any element with a role that cannot support semantic children.
-
The roles that require all children to be presentational are:
-For instance, consider the following tab element, which contains a heading.
-- <li role="tab"><h3>Title of My Tab</h3></li> --
- Because WAI-ARIA requires descendants of tab to be presentational, - the following code is equivalent. -
-- <li role="tab"><h3 role="presentation">Title of My Tab</h3></li> --
- And, from the perspective of anyone using a technology that relies on an accessibility API, such as a screen reader, - the heading does not exist since the previous code is equivalent to the following. -
-- <li role="tab">Title of My Tab</li> --
- See the
-
- section about role presentation
-
- for a detailed explanation of what it does.
-
- ARIA provides a set of roles that convey the accessibility semantics of structures on a page. - These roles express the meaning that is conveyed by the layout and appearance of elements that organize and structure content, such as headings, lists, and tables. -
-
- some host languages, such as HTML, include elements that express the same semantics as an ARIA role.
- For instance, the HTML <p> element is mapped to accessibility APIs in exactly the same way as <div role="paragraph">.
- The ARIA and HTML specifications refer to this mapping of HTML elements to ARIA attributes as implied semantics, i.e., the implied ARIA role of the HTML <p> element is paragraph.
-
- When developing HTML, it is important to use native HTML elements where ever possible. - Do not use an ARIA role or property if it is possible to use an HTML element that has equivalent semantics. - Circumstances where it is appropriate to use ARIA attributes instead of equivalent HTML are: -
-The following table lists all structural roles defined in ARIA 1.2.
-| ARIA Role | -HTML Equivalent | -
|---|---|
| application | No equivalent element |
| article | article |
| blockquote | blockquote |
| caption | caption |
| cell | td |
| code | code |
| columnheader | th |
| definition | dd |
| deletion | del |
| directory | No equivalent element |
| document | No equivalent element |
| emphasis | em |
| feed | No equivalent element |
| figure | figure |
| generic | div, span |
| group | No equivalent element |
| heading with aria-level="N" where N is 1, 2, 3, 4, 5, or 6 | h1, h2, h3, h4, h5, h6 |
| insertion | ins |
| img | img |
| list | ul, ol |
| listitem | li |
| math | No equivalent element |
| none | No equivalent element |
| note | No equivalent element |
| presentation | No equivalent element |
| paragraph | p |
| row | tr |
| rowgroup | tbody, thead, tfoot |
| rowheader | th |
| separator (when not focusable) | hr |
| strong | strong |
| subscript | sub |
| superscript | sup |
| table | table |
| term | dfn |
| time | time |
| toolbar | No equivalent element |
| tooltip | No equivalent element |
+ To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the + grid pattern or table pattern, + assistive technologies need to be able to determine: +
++ Browsers automatically populate their accessibility tree with the number of rows and columns in a grid or table based on the rendered DOM. + However, there are many situations where the DOM does not contain the whole grid or table, such as when the data set is too large to fully render. + Additionally, some of this information, like skipped columns or rows and how data is sorted, cannot be derived from the DOM structure. +
+The below sections explain how to use the following properties that ARIA provides for grid and table accessibility.
+| Property | +Definition | +
|---|---|
aria-colcount |
+ Defines the total number of columns in a table, grid, or treegrid. |
+
aria-rowcount |
+ Defines the total number of rows in a table, grid, or treegrid. |
+
aria-colindex |
+
+
|
+
aria-rowindex |
+
+
|
+
aria-colspan |
+ Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. |
+
aria-rowspan |
+ Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. |
+
aria-sort |
+ Indicates if items in a row or column are sorted in ascending or descending order. | +
aria-rowcount and aria-rowindex
+ When the number of rows represented by the DOM structure is not the total number of rows available for a table, grid, or treegrid,
+ the aria-rowcount property is used to communicate the total number of rows available,
+ and it is accompanied by the aria-rowindex property to identify the row indices of the rows that are present in the DOM.
+
+ The aria-rowcount is specified on the element with the table, grid, or treegrid role.
+ Its value is an integer equal to the total number of rows available, including header rows.
+ If the total number of rows is unknown, a value of -1 may be specified.
+ Using a value of -1 indicates that more rows are available to include in the DOM without specifying the size of the available supply.
+
+ When aria-rowcount is used on a table, grid, or treegrid,
+ a value for aria-rowindex property is specified on each of its descendant rows, including any header rows.
+ The value of aria-rowindex is an integer that is:
+
aria-rowindex on any previous rows.
+ WARNING! Missing or inconsistent values of aria-rowindex could have devastating effects on assistive technology behavior.
+ For example, specifying an invalid value for aria-rowindex or setting it on some but not all rows in a table, could cause screen reader table reading functions to skip rows or simply stop functioning.
+
+ The following code demonstrates the use of aria-rowcount and aria-rowindex properties on a table containing a hypothetical class list.
+
+
+ <!--
+ aria-rowcount tells assistive technologies the actual size of the grid
+ is 463 rows even though only 4 rows are present in the markup.
+ -->
+ <table role="grid" aria-rowcount="463">
+ aria-label="Student roster for history 101"
+ <thead>
+ <tr aria-rowindex="1">
+ <th>Last Name</th>
+ <th>First Name</th>
+ <th>E-mail</th>
+ <th>Major</th>
+ <th>Minor</th>
+ <th>Standing</th>
+ </tr>
+ </thead>
+ <tbody>
+ <!--
+ aria-rowindex tells assistive technologies that this
+ row is row 51 in the grid of 463 rows.
+ -->
+ <tr aria-rowindex="51">
+ <td>Henderson</td>
+ <td>Alan</td>
+ <td>ahederson56@myuniveristy.edu</td>
+ <td>Business</td>
+ <td>Spanish</td>
+ <td>Junior</td>
+ </tr>
+ <!--
+ aria-rowindex tells assistive technologies that this
+ row is row 52 in the grid of 463 rows.
+ -->
+ <tr aria-rowindex="52">
+ <td>Henderson</td>
+ <td>Alice</td>
+ <td>ahederson345@myuniveristy.edu</td>
+ <td>Engineering</td>
+ <td>none</td>
+ <td>Sophomore</td>
+ </tr>
+ <!--
+ aria-rowindex tells assistive technologies that this
+ row is row 53 in the grid of 463 rows.
+ -->
+ <tr aria-rowindex="53">
+ <td>Henderson</td>
+ <td>Andrew</td>
+ <td>ahederson75@myuniveristy.edu</td>
+ <td>General Studies</td>
+ <td>none</td>
+ <td>Freshman</td>
+ </tr>
+ </tbody>
+ </table>
+
+
+aria-colcount and aria-colindex
+ When the number of columns represented by the DOM structure is not the total number of columns available for a table, grid, or treegrid,
+ the aria-colcount property is used to communicate the total number of columns available,
+ and it is accompanied by the aria-colindex property to identify the column indices of the columns that are present in the DOM.
+
+ The aria-colcount is specified on the element with the table, grid, or treegrid role.
+ Its value is an integer equal to the total number of columns available.
+ If the total number of columns is unknown, a value of -1 may be specified.
+ Using a value of -1 indicates that more columns are available to include in the DOM without specifying the size of the available supply.
+
+ When aria-colcount is used on a table, grid, or treegrid,
+ a value for aria-colindex property is either specified on each of its descendant rows or on every cell in each descendant row, depending on whether the columns are contiguous as described below.
+ The value of aria-colindex is an integer that is:
+
+ WARNING! Missing or inconsistent values of aria-colindex could have devastating effects on assistive technology behavior.
+ For example, specifying an invalid value for aria-colindex or setting it on some but not all cells in a row, could cause screen reader table reading functions to skip cells or simply stop functioning.
+
aria-colindex When Column Indices Are Contiguous
+ When all the cells in a row have column index numbers that are consecutive integers,
+ aria-colindex can be set on the row element with a value equal to the index number of the first column in the set.
+ Browsers will then compute a column number for each cell in the row.
+
+ The following code shows a grid with 16 columns, of which columns 2 through 5 are displayed to the user.
+ Because the set of columns is contiguous, aria-colindex can be placed on each row.
+
+
+<div role="grid" aria-colcount="16">
+ <div role="rowgroup">
+ <div role="row" aria-colindex="2">
+ <span role="columnheader">First Name</span>
+ <span role="columnheader">Last Name</span>
+ <span role="columnheader">Company</span>
+ <span role="columnheader">Address</span>
+ </div>
+ </div>
+ <div role="rowgroup">
+ <div role="row" aria-colindex="2">
+ <span role="gridcell">Fred</span>
+ <span role="gridcell">Jackson</span>
+ <span role="gridcell">Acme, Inc.</span>
+ <span role="gridcell">123 Broad St.</span>
+ </div>
+ <div role="row" aria-colindex="2">
+ <span role="gridcell">Sara</span>
+ <span role="gridcell">James</span>
+ <span role="gridcell">Acme, Inc.</span>
+ <span role="gridcell">123 Broad St.</span>
+ </div>
+ …
+ </div>
+</div>
+
+
+ aria-colindex When Column Indices Are Not Contiguous
+ When the cells in a row have column index numbers that are not consecutive integers, aria-colindex needs to be set on each cell in the row.
+ The following example shows a grid for an online grade book where the first two columns contain a student name and subsequent columns contain scores.
+ In this example, the first two columns with the student name are shown, but the score columns have been scrolled to show columns 10 through 13.
+ Columns 3 through 9 are not visible so are not in the DOM.
+
+
+<table role="grid" aria-rowcount="463" aria-colcount="13">
+ aria-label="Student grades for history 101"
+ <!--
+ aria-rowcount and aria-colcount tell assistive technologies
+ the actual size of the grid is 463 rows by 13 columns,
+ which is not the number rows and columns found in the markup.
+ -->
+ <thead>
+ <tr aria-rowindex="1">
+ <!--
+ aria-colindex tells assistive technologies that the
+ following columns represent columns 1 and 2 of the total data set.
+ -->
+ <th aria-colindex="1">Last Name</th>
+ <th aria-colindex="2">First Name</th>
+ <!--
+ aria-colindex tells users of assistive technologies that the
+ following columns represent columns 10, 11, 12, and 13 of
+ the overall data set of grades.
+ -->
+ <th aria-colindex="10">Homework 4</th>
+ <th aria-colindex="11">Quiz 2</th>
+ <th aria-colindex="12">Homework 5</th>
+ <th aria-colindex="13">Homework 6</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr aria-rowindex="50">
+ <!--
+ every cell needs to define the aria-colindex attribute
+ -->
+ <td aria-colindex="1">Henderson</td>
+ <td aria-colindex="2">Alan</td>
+ <td aria-colindex="10">8</td>
+ <td aria-colindex="11">25</td>
+ <td aria-colindex="12">9</td>
+ <td aria-colindex="13">9</td>
+ </tr>
+ <tr aria-rowindex="51">
+ <td aria-colindex="1">Henderson</td>
+ <td aria-colindex="2">Alice</td>
+ <td aria-colindex="10">10</td>
+ <td aria-colindex="11">27</td>
+ <td aria-colindex="12">10</td>
+ <td aria-colindex="13">8</td>
+ </tr>
+ <tr aria-rowindex="52">
+ <td aria-colindex="1">Henderson</td>
+ <td aria-colindex="2">Andrew</td>
+ <td aria-colindex="10">9</td>
+ <td aria-colindex="11">0</td>
+ <td aria-colindex="12">29</td>
+ <td aria-colindex="13">8</td>
+ </tr>
+ </tbody>
+</table>
+
+
+ aria-colspan and aria-rowspan
+ For tables, grids, and treegrids created using elements other than HTML table elements,
+ row and column spans are defined with the aria-rowspan and aria-colspan properties.
+
The value of aria-colspan is an integer that is:
The value of aria-rowspan is an integer that is:
+ The following example grid has a two row header. + The first two columns have headers that span both rows of the header. + The subsequent 6 columns are grouped into 3 pairs with headers in the first row that each span two columns. +
+
+
+ <div role="grid" aria-rowcount="463">
+ aria-label="Student grades for history 101"
+ <div role="rowgroup">
+ <div role="row" aria-rowindex="1">
+ <!--
+ aria-rowspan and aria-colspan provide
+ assistive technologies with the correct data cell header information
+ when header cells span more than one row or column.
+ -->
+ <span role="columnheader" aria-rowspan="2">Last Name</span>
+ <span role="columnheader" aria-rowspan="2">First Name</span>
+ <span role="columnheader" aria-colspan="2">Test 1</span>
+ <span role="columnheader" aria-colspan="2">Test 2</span>
+ <span role="columnheader" aria-colspan="2">Final</span>
+ </div>
+ <div role="row" aria-rowindex="2">
+ <span role="columnheader">Score</span>
+ <span role="columnheader">Grade</span>
+ <span role="columnheader">Score</span>
+ <span role="columnheader">Grade</span>
+ <span role="columnheader">Total</span>
+ <span role="columnheader">Grade</span>
+ </div>
+ </div>
+ <div role="rowgroup">
+ <div role="row" aria-rowindex="50">
+ <span role="cell">Henderson</span>
+ <span role="cell">Alan</span>
+ <span role="cell">89</span>
+ <span role="cell">B+</span>
+ <span role="cell">72</span>
+ <span role="cell">C</span>
+ <span role="cell">161</span>
+ <span role="cell">B-</span>
+ </div>
+ <div role="row" aria-rowindex="51">
+ <span role="cell">Henderson</span>
+ <span role="cell">Alice</span>
+ <span role="cell">94</span>
+ <span role="cell">A</span>
+ <span role="cell">86</span>
+ <span role="cell">B</span>
+ <span role="cell">180</span>
+ <span role="cell">A-</span>
+ </div>
+ <div role="row" aria-rowindex="52">
+ <span role="cell">Henderson</span>
+ <span role="cell">Andrew</span>
+ <span role="cell">82</span>
+ <span role="cell">B-</span>
+ <span role="cell">95</span>
+ <span role="cell">A</span>
+ <span role="cell">177</span>
+ <span role="cell">B+</span>
+ </div>
+ </div>
+ </div>
+
+
+
+ Note: When using HTML table elements,
+ use the native semantics of the th and td elements to define row and column spans
+ by using the rowspan and colspan attributes.
+
aria-sort
+ When rows or columns are sorted, the aria-sort property can be applied to a column or row header to indicate the sorting method.
+ The following table describes allowed values for aria-sort.
+
| Value | +Description | +
|---|---|
ascending |
+ Data are sorted in ascending order. | +
descending |
+ Data are sorted in descending order. | +
other |
+ Data are sorted by an algorithm other than ascending or descending. | +
none |
+ Default (no sort applied). | +
+ It is important to note that ARIA does not provide a way to indicate levels of sort for data sets that have multiple sort keys.
+ Thus, there is limited value to applying aria-sort with a value other than none to more than one column or row.
+
The following example grid uses aria-sort to indicate the rows are sorted from the highest "Quiz 2" score to the lowest "Quiz 2" score.
+
+<table role="grid" aria-rowcount="463" aria-colcount="13"
+ aria-label="Student grades for history 101">
+ <thead>
+ <tr aria-colindex="10" aria-rowindex="1">
+ <th>Homework 4</th>
+ <!--
+ aria-sort indicates the column with the heading
+ "Quiz 2" has been used to sort the rows of the grid.
+ -->
+ <th aria-sort="descending">Quiz 2</th>
+ <th>Homework 5</th>
+ <th>Homework 6</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr aria-colindex="10" aria-rowindex="50">
+ <td>8</td>
+ <td>30</td>
+ <td>9</td>
+ <td>9</td>
+ </tr>
+ <tr aria-colindex="10" aria-rowindex="51">
+ <td>10</td>
+ <td>29</td>
+ <td>10</td>
+ <td>8</td>
+ </tr>
+ <tr aria-colindex="10" aria-rowindex="52">
+ <td>9</td>
+ <td>9</td>
+ <td>27</td>
+ <td>6</td>
+ </tr>
+ <tr aria-colindex="10" aria-rowindex="53">
+ <td>9</td>
+ <td>10</td>
+ <td>26</td>
+ <td>8</td>
+ </tr>
+ <tr aria-colindex="10" aria-rowindex="54">
+ <td>9</td>
+ <td>7</td>
+ <td>24</td>
+ <td>6</td>
+ </tr>
+ </tbody>
+</table>
+
+
+
+ presentation Role
+ While ARIA is primarily used to express semantics, there are some situations where hiding an element’s semantics from assistive technologies is helpful.
+ This is done with the
+ presentation
+ role, which declares that an element is being used only for presentation and therefore does not have any accessibility semantics.
+ The ARIA 1.1 specification also includes role
+ none,
+ which serves as a synonym for presentation.
+
+ For example, consider a tabs widget built using an HTML ul element.
+
+ <ul role="tablist">
+ <li role="presentation">
+ <a role="tab" href="#">Tab 1</a>
+ </li>
+ <li role="presentation">
+ <a role="tab" href="#">Tab 2</a>
+ </li>
+ <li role="presentation">
+ <a role="tab" href="#">Tab 3</a>
+ </li>
+ </ul>
+
+ Because the list is declared to be a tablist, the list items are not in a list context.
+ It could confuse users if an assistive technology were to render those list items.
+ Applying role presentation to the li elements tells browsers to leave those elements out of their accessibility tree.
+ Assistive technologies will thus be unaware of the list item elements and see the tab elements as immediate children of the tablist.
+
presentation
+ Three common uses of role presentation are:
+
presentation
+ When role="presentation" is specified on an element, if a
+ condition that requires a browser to ignore the presentation role
+ does not exist, it has the following three effects.
+
display: none or has aria-hidden="true" is not visible to assistive technologies.
+ presentation is applied to a ul or ol element, each child li element inherits the presentation role because ARIA requires the listitem elements to have the parent list element.
+ So, the li elements are not exposed to assistive technologies, but elements contained inside of those li elements, including nested lists, are visible to assistive technologies.
+ presentation is applied to a table element,
+ the descendant caption, thead, tbody, tfoot,
+ tr, th, and td
+ elements inherit role presentation and are thus not exposed to assistive technologies.
+ But, elements inside of the th and td elements, including nested tables, are exposed to assistive technologies.
+ presentation to be IgnoredBrowsers ignore role="presentation", and it therefore has no effect, if either of the following are true about the element to which it is applied:
tabindex attribute.aria-label.
+ presentation RoleIn the following code, role presentation suppresses the list and list item semantics.
+ <ul role="presentation">
+ <li>Date of birth:</li>
+ <li>January 1, 3456</li>
+ </ul>
+ When the above code is parsed by a browser, it is semantically equivalent to the following code:
+
+ <div>Date of birth:</div>
+ <div>January 1, 3456</div>
+
+ There are some types of user interface components that, when represented in a platform accessibility API, can only contain text.
+ For example, accessibility APIs do not have a way of representing semantic elements contained in a button.
+ To deal with this limitation, WAI-ARIA requires browsers to automatically apply role presentation to all descendant elements of any element with a role that cannot support semantic children.
+
The roles that require all children to be presentational are:
+For instance, consider the following tab element, which contains a heading.
+
+ <li role="tab"><h2>Title of My Tab</h2></li>
+ + Because WAI-ARIA requires descendants of tab to be presentational, the heading semantic is not exposed to assistive technology users. + Thus, the following code is equivalent. +
+
+ <li role="tab"><h2 role="presentation">Title of My Tab</h2></li>
+
+ So, from the perspective of anyone using a technology that relies on an accessibility API, such as a screen reader, the heading does not exist.
+ As described above in the section on
+ Effects of Role presentation,
+ the previous code is equivalent to the following.
+
+ <li role="tab">Title of My Tab</li>
+ + Unlike native HTML form elements, browsers do not provide keyboard support for graphical user interface (GUI) components that are made accessible with ARIA; authors have to provide the keyboard support in their code. + This section describes the principles and methods for making the functionality of a web page that includes ARIA widgets, such as menus and grids, as well as interactive components, such as toolbars and dialogs, operable with a keyboard. + Along with the basics of focus management, this section offers guidance toward the objective of providing experiences to people who rely on a keyboard that are as efficient and enjoyable as the experiences available to others. +
+This section covers:
+Work to complete this section is tracked by issue 217.
++ When operating with a keyboard, two essentials of a good experience are the abilities to easily discern the location of the keyboard focus and to discover where focus landed after a navigation key has been pressed. + The following factors affect to what extent a web page affords users these capabilities. +
+ ++ Occasionally, it may appear as if two elements on the page have focus at the same time. + For example, in a multi-select list box, when an option is selected it may be greyed. + Yet, the focus indicator can still be moved to other options, which may also be selected. + Similarly, when a user activates a tab in a tablist, the selected state is set on the tab and its visual appearance changes. + However, the user can still navigate, moving the focus indicator elsewhere on the page while the tab retains its selected appearance and state. +
+ ++ Focus and selection are quite different. + From the keyboard user's perspective, focus is a pointer, like a mouse pointer; it tracks the path of navigation. + There is only one point of focus at any time and all operations take place at the point of focus. + On the other hand, selection is an operation that can be performed in some widgets, such as list boxes, trees, and tablists. + If a widget supports only single selection, then only one item can be selected and very often the selected state will simply follow the focus when focus is moved inside of the widget. + That is, in some widgets, moving focus may also perform the select operation. + However, if the widget supports multiple selection, then more than one item can be in a selected state, and keys for moving focus do not perform selection. + Some multi-select widgets do support key commands that both move focus and change selection, but those keys are different from the normal navigation keys. + Finally, when focus leaves a widget that includes a selected element, the selected state persists. +
+ +
+ From the developer's perspective, the difference is simple -- the focused element is the active element (document.activeElement).
+ Selected elements are elements that have aria-selected="true".
+
With respect to focus and the selected state, the most important considerations for designers and developers are:
+ +in composite widgets where only one element may be selected, such as a tablist or single-select listbox, moving the focus may also cause the focused element to become the selected element. This is called having selection follow focus. Having selection follow focus is often beneficial to users, but in some circumstances, it is extremely detrimental to accessibility.
++ For example, in a tablist, the selected state is used to indicate which panel is displayed. + So, when selection follows focus in a tablist, moving focus from one tab to another automatically changes which panel is displayed. + If the content of panels is present in the DOM, then displaying a new panel is nearly instantaneous. + A keyboard user who wishes to display the fourth of six tabs can do so with 3 quick presses of the right arrow. + And, a screen reader user who perceives the labels on tabs by navigating through them may efficiently read through the complete list without any latency. +
+However, if displaying a new panel causes a network request and possibly a page refresh, the effect of having selection automatically focus can be devastating to the experience for keyboard and screen reader users. In this case, displaying the fourth tab or reading through the list becomes a tedious and time-consuming task as the user experiences significant latency with each movement of focus. Further, if displaying a new tab refreshes the page, then the user not only has to wait for the new page to load but also return focus to the tab list.
++ When selection does not follow focus, the user changes which element is selected by pressing the Enter or Space key. +
+As explained in section Fundamental Keyboard Navigation Conventions, all interactive UI components need to be reachable via the keyboard. This is best achieved by either including them in the tab sequence or by making them accessible from a component that is in the tab sequence, e.g., as part of a composite component. This section addresses building and managing the tab sequence, and subsequent sections cover making focusable elements that are contained within components keyboard accessible.
+ ++ The HTML tabindex and SVG2 tabindex attributes can be used to add and remove elements from the tab sequence. + The value of tabindex can also influence the order of the tab sequence, although authors are strongly advised not to use tabindex for that purpose. +
+ ++ In HTML, the default tab sequence of a web page includes only links and HTML form elements, except In macOS, where it includes only form elements. + macOS system preferences include a keyboard setting that enables the tab key to move focus to all focusable elements. +
+ ++ The default order of elements in the tab sequence is the order of elements in the DOM. + The DOM order also determines screen reader reading order. + It is important to keep the keyboard tab sequence and the screen reader reading order aligned, logical, and predictable as described in Discernible and Predictable Keyboard Focus. + The most robust method of manipulating the order of the tab sequence while also maintaining alignment with the reading order that is currently available in all browsers is rearranging elements in the DOM. +
+ +The values of the tabindex attribute have the following effects.
+ ++ As described in section Fundamental Keyboard Navigation Conventions, the tab sequence should include only one focusable element of a composite UI component. + Once a composite contains focus, keys other than Tab and Shift + Tab enable the user to move focus among its focusable elements. + Authors are free to choose which keys move focus inside of a composite, but they are strongly advised to use the same key bindings as similar components in common GUI operating systems as demonstrated in APG Patterns. +
+ +The convention for where focus lands in a composite when it receives focus as a result of a Tab key event depends on the type of composite. It is typically one of the following.
+ ++ The following sections explain two strategies for managing focus inside composite elements: creating a roving tabindex and using the aria-activedescendant property. +
+ ++ When using roving tabindex to manage focus in a composite UI component, the element that is to be included in the tab sequence has tabindex of "0" and all other focusable elements contained in the composite have tabindex of "-1". + The algorithm for the roving tabindex strategy is as follows. +
+ +tabindex="0" on the element that will initially be included in the tab sequence and set tabindex="-1" on all other focusable elements it contains.tabindex="-1" on the element that has tabindex="0".tabindex="0" on the element that will become focused as a result of the key event.element.focus(), on the element that has tabindex="0".tabindex="0" when the composite loses focus.
+ If it does not, set tabindex="0" on the target element and set tabindex="-1" on the element that previously had tabindex="0".
+ + One benefit of using roving tabindex rather than aria-activedescendant to manage focus is that the user agent will scroll the newly focused element into view. +
++ If a component container has an ARIA role that supports the aria-activedescendant property, it is not necessary to manipulate the tabindex attribute and move DOM focus among focusable elements within the container. + Instead, only the container element needs to be included in the tab sequence. When the container has DOM focus, the value of aria-activedescendant on the container tells assistive technologies which element is active within the widget. + Assistive technologies will consider the element referred to as active to be the focused element even though DOM focus is on the element that has the aria-activedescendant property. + And, when the value of aria-activedescendant is changed, assistive technologies will receive focus change events equivalent to those received when DOM focus actually moves. +
+ +The steps for using the aria-activedescendant method of managing focus are as follows.
+ +aria-activedescendant="IDREF" where IDREF is the ID of the element within the container that should be identified as active when the widget receives focus.
+ The referenced element needs to meet the DOM relationship requirements described below.
+ + The specification for aria-activedescendant places important restrictions on the DOM relationship between the focused element that has the aria-activedescendant attribute and the element referenced as active by the value of the attribute. + One of the following three conditions must be met. +
++ By default, disabled HTML input elements are removed from the tab sequence. + In most contexts, the normal expectation is that disabled interactive elements are not focusable. + However, there are some contexts where it is common for disabled elements to be focusable, especially inside of composite widgets. + For example, as demonstrated in the menu and menubar pattern, disabled items are focusable when navigating through a menu with the arrow keys. +
+ ++ Removing focusability from disabled elements can offer users both advantages and disadvantages. + Allowing keyboard users to skip disabled elements usually reduces the number of key presses required to complete a task. + However, preventing focus from moving to disabled elements can hide their presence from screen reader users who "see" by moving the focus. +
+ ++ Authors are encouraged to adopt a consistent set of conventions for the focusability of disabled elements. + The examples in this guide adopt the following conventions, which both reflect common practice and attempt to balance competing concerns. +
+ +One design technique for mitigating the impact of including disabled elements in the path of keyboard focus is employing appropriate keyboard shortcuts as described in Keyboard Shortcuts.
++ The following key assignments can be used in any context where their conventionally associated functions are appropriate. + While the assignments associated with Windows and Linux platforms can be implemented and used in browsers running in macOS, + replacing them with macOS assignments in browsers running on a macOS device can make the keyboard interface more discoverable and intuitive for those users. + In some cases, it may also help avoid system or browser keyboard conflicts. +
+| Function | +Windows/Linux Key | +macOS Key | +
|---|---|---|
| open context menu | +Shift + F10 | ++ |
| Copy to clipboard | +Control + C | +Command + C | +
| Paste from clipboard | +Control + V | +Command + V | +
| Cut to clipboard | +Control + X | +Command + X | +
| undo last action | +Control + Z | +Command + Z | +
| Redo action | +Control + Y | +Command + Shift + Z | +
+ When effectively designed, keyboard shortcuts that focus an element, activate a widget, or both can dramatically enhance usability of frequently used features of a page or site. + This section addresses some of the keyboard shortcut design and implementation factors that most impact their effectiveness, including: +
+This section explains the following factors when determining which elements and features to assign keyboard shortcuts and what behavior to give each shortcut:
+ ++ Before assigning keyboard shortcuts, it is essential to ensure the features and functions to which shortcuts may be assigned are keyboard accessible without a keyboard shortcut. + In other words, all elements that could be targets for keyboard shortcuts need to be focusable via the keyboard using the methods described in: +
+ + + ++ Do not use keyboard shortcuts as a substitute for access via navigation. + This is essential to full keyboard access because: +
+ +The following conventions may help identify the most advantageous behavior for a keyboard shortcut.
+ +Work to draft content for this section is tracked in issue 219.
+The first goal when designing a keyboard interface is simple, efficient, and intuitive operation with only basic keyboard navigation support. If basic operation of a keyboard interface is inefficient, attempting to compensate for fundamental design issues, such as suboptimal layout or command structure, by implementing keyboard shortcuts will not likely reduce user frustration. The practical implication of this is that, in most well-designed user interfaces, the percentage of functionality that needs to be accessible via a keyboard shortcut in order to create optimal usability is not very high. In many simple user interfaces, keyboard shortcuts can be entirely superfluous. And, in user interfaces with too many keyboard shortcuts, the excess shortcuts create cognitive load that make the most useful ones more difficult to remember.
+Consider the following when deciding where to assign keyboard shortcuts:
+ +When choosing the keys to assign to a shortcut, there are many factors to consider.
++ Methods for designing a key shortcut scheme that supports learning and memory is beyond the scope of this guide. + Unless the key shortcut scheme is extensive, it is likely sufficient to mimic concepts that are familiar from common desktop software, such as browsers. + Similarly, while localization is important, describing how to address it is left to other resources that specialize in that topic. +
++ The remainder of this section provides guidance balancing requirements and concerns related to key assignment conflicts. + It is typically ideal if key assignments do not conflict with keys that are assigned to functions in the user's operating system, browser, or assistive technology. + Conflicts can block efficient access to functions that are essential to the user, and a perfect storm of conflicts can trap a user. + At the same time, there are some circumstances where intentional conflicts are useful. + And, given the vast array of operating system, browser, and assistive technology keys, it is almost impossible to be certain conflicts do not exist. + So it is also important to employ strategies that mitigate the impact of conflicts whether they are intentional or unknown. +
++ In the following sections, meta key refers to the Windows key on Windows-compatible keyboards and the Command key on MacOS-compatible keyboards. +
+It is essential to avoid conflicts with keys that perform system level functions, such as application and window management and display and sound control. In general, this can be achieved by refraining from the following types of assignments.
+ ++ In addition, there are some important application level features that most applications, including browsers, generally support. + These include: +
+ ++ Even though assistive technologies have collectively taken thousands of key assignments, avoiding conflicts is relatively easy. + This is because assistive technologies have had to develop key assignment schemes that avoid conflicts with both operating systems and applications. + They do this by hijacking specific keys as modifiers that uniquely define their key commands. + For example, many assistive technologies use the Caps Lock key as a modifier. +
+ +Deflect assistive technology key conflicts by steering clear of the following types of assignments.
+ +While there is considerable similarity among browser keyboard schemes, the patterns within the schemes are less homogenous. Consequently, it is more difficult to avoid conflicts with browser key assignments. While the impact of conflicts is sometimes mitigated by the availability of two paths to nearly every function -- keyboard accessible menus and keyboard shortcuts, avoiding conflicts with shortcuts to heavily used functions is nonetheless important. Pay special attention to avoiding conflicts with shortcuts to:
+ ++ While avoiding key conflicts is usually desirable, there are circumstances where intentionally conflicting with a browser function is acceptable or even desirable. + This can occur when the following combination of conditions arises: +
+ +For example, consider a save function that is available when the focus is in an editor. Most browsers use ... to be continued ...
++ ARIA landmark roles provide a powerful way to identify the organization and structure of a web page. + By classifying and labelling sections of a page, they enable structural information that is conveyed visually through layout to be represented programmatically. + Screen readers exploit landmark roles to provide keyboard navigation to important sections of a page. + Landmark regions can also be used as targets for "skip links" and by browser extensions to enhanced keyboard navigation. +
++ This section explains how HTML sectioning elements and ARIA landmark roles + are used to make it easy for assistive technology users to understand the meaning of the layout of a page. +
++ Several HTML sectioning elements automatically create ARIA landmark regions. + So, in order to provide assistive technology users with a logical view of a page, + it is important to understand the effects of using HTML sectioning elements. + [[HTML-ARIA]] contains more information on HTML element role mapping. +
+| HTML Element | + +Default Landmark Role | +
|---|---|
aside |
+
+ complementary |
+
footer |
+
+ contentinfo when in context of the body element |
+
header |
+
+ banner when in context of the body element |
+
main |
+
+ main |
+
nav |
+
+ navigation |
+
section |
+
+ region when it has an accessible name using aria-labelledby or aria-label |
+
+ Including all perceivable content on a page in one of its landmark regions + and giving each landmark region a semantically meaningful role + is one of the most effective ways of ensuring assistive technology users will not overlook information that is relevant to their needs. +
+Step 1: Identify the logical structure
+ +Step 2: Assign landmark roles to each area
+ +banner, main, complementary and contentinfo landmarks should be top level landmarks.Step 3: Label areas
+ +Search Results. + In this case, adding extra information to the label that distinguishes the two instances may be more distracting than helpful. +
h1-h6) it can be used as the label for the area using the aria-labelledby attribute.aria-label attribute.A complementary landmark is a supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful
+ when separated from the main content.
complementary landmarks should be top level landmarks (e.g. not contained within any other landmarks).region).complementary landmark, each should have a unique label (see Step 3 above).Use the HTML aside element to define a complementary landmark.
If the HTML aside element technique is not being used, use a role="complementary" attribute to define a complementary landmark.
A contentinfo landmark is a way to identify common information at the bottom of each page within a website, typically called the "footer" of the page, including information
+ such as copyrights and links to privacy and accessibility statements.
contentinfo landmark.contentinfo landmark should be a top-level landmark.document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have
+ one contentinfo landmark.contentinfo landmark, each should have a unique label (see Step 3 above).footer element defines a contentinfo landmark when its context is the body element.footer element is not considered a contentinfo landmark when it is descendant of any of following elements (see HTML Accessibility Mappings):
+ articleasidemainnavsectionIf the HTML footer element technique is not being used, a role="contentinfo" attribute should be used to define a contentinfo landmark.
A form landmark identifies a region that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. main
+ or search).
search landmark instead of the form landmark when the form is used for search functionality.form landmark should have a label to help users understand the purpose of the form.form landmark should be visible to all users (e.g. an h1-h6 element).form landmark, each should have a unique label (see Step 3 above).form landmark in an HTML document should use native host semantics:
+ buttoninputselecttextareaThe HTML form element defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).
Use the role="form" to identify a region of the page; do not use it to identify every form field.
A main landmark identifies the primary content of the page.
main landmark.main landmark should be a top-level landmark.document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have
+ one main landmark.main landmark, each should have a unique label (see Step 3 above).Use the HTML main element to define a main landmark.
If the HTML main element technique is not being used, use a role="main" attribute to define a main landmark.
A region landmark is a perceivable section of the page containing content that is sufficiently important for users to be able to navigate to the section.
region landmark must have a label.region landmark, each should have a unique label (see Step 3 above).region landmark can be used identify content that named landmarks do not appropriately describe.The HTML section element defines a region landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).
If the HTML section element technique is not being used, use a role="region" attribute to define a region landmark.
A search landmark contains a collection of items and objects that, as a whole, combine to create search functionality.
search landmark instead of the form landmark when the form is used for search functionality.search landmark, each should have a unique label (see Step 3 above).There is no HTML element that defines a search landmark.
The role="search" attribute defines a search landmark.
+ Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most important responsibilities authors have when developing accessible web experiences. + While doing so is straightforward for most elements, technical mistakes that can completely block users of assistive technologies are easy to make and unfortunately common. + To help authors effectively provide accessible names and descriptions, this section explains their purpose, when authors need to provide them, how browsers assemble them, and rules for coding and composing them. + It also guides authors in the use of the following naming and describing techniques and WAI-ARIA properties: +
+aria-label.aria-labelledby.aria-describedby.+ An accessible name is a short string, typically 1 to 3 words, that authors associate with an element to provide users of assistive technologies with a label for the element. + For example, an input field might have an accessible name of "User ID" or a button might be named "Submit". +
+An accessible name serves two primary purposes for users of assistive technologies, such as screen readers:
++ Both the WAI-ARIA specification and WCAG require all focusable, interactive elements to have an accessible name. + In addition dialogs and some structural containers, such as tables and regions, are required to have a name. + Many other elements can be named, but whether a name will enhance the accessible experience is determined by various characteristics of the surrounding context. + Finally, there are some elements where providing an accessible name is technically possible but not advisable. + The Accessible Name Guidance by Role section lists naming requirements and guidelines for every ARIA role. +
++ An accessible description is also an author-provided string that is rendered by assistive technologies. + Authors supply a description when there is a need to associate additional information with an element, such as instructions or format requirements for an input field. +
+
+ Assistive technologies present names differently from descriptions.
+ For instance, screen readers typically announce the name and role of an element first, e.g., a button named Mute Conversation
could be spoken as Mute Conversation button
.
+ If an element has a state, it could be announced either before or after the name and role; after name and role is the typical default.
+ For example, a switch button named Mute Conversation
in the off
state could be announced as Mute Conversation switch button off
.
+ Because descriptions are optional strings that are usually significantly longer than names, they are presented last, sometimes after a slight delay.
+ For example, Mute Conversation Switch button off, Silences alerts and notifications about activity in this conversation.
+ To reduce verbosity, some screen readers do not announce descriptions by default but instead inform users of their presence so that users can press a key that will announce the description.
+
+ Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because authors can combine them in a practically endless number of ways, browsers implement fairly complex algorithms for assembling the strings. + The sections on accessible name calculation and accessible description calculation explain the algorithms and how they implement precedence. + However, most authors do not need such detailed understanding of the algorithms since nearly all circumstances where a name or description is useful are supported by the coding patterns described in the naming techniques and describing techniques sections. +
++ Several of the naming techniques below include notes that warn against specific coding patterns that are either prohibited by the ARIA specification or fall into gray space that is not yet fully specified. + Some of these prohibited or ambiguous patterns may appear logical and even yield desired names in some browsers. + However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses. +
++ In addition to heeding the warnings provided in the naming techniques, it is difficult to over emphasize the importance of testing to ensure that names browsers calculate match expectations. +
++ When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. + When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names will not be updated when the user interface design or content are changed. +
++ If an interactive element, such as an input field or button, does not have a visually persistent text label, consider adjusting the design to include one. + In addition to serving as a more robust source for an accessible name, visible text labels enhance accessibility for many people with disabilities who do not use assistive technologies that present invisible accessible names. + In most circumstances, visible text labels also make the user interface easier to understand for all users. +
+
+ In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element for form elements and caption element for tables.
+ While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences.
+ Several of the naming techniques highlight specific accessibility advantages of using HTML features instead of ARIA attributes.
+
+ When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fallback methods for generating a name.
+ For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names.
+ Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective.
+
+ Similar to how visually crowded screens and ambiguous icons reduce usability, excessively long, insufficiently distinct, or unclear accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. + In other words, for a web experience to be accessible, its accessible names must be effective. + The section on Composing Effective and User-friendly Accessible Names provides guidance for balancing brevity and clarity. +
++ Certain elements get their name from the content they contain. + For example, the following link is named "Home". +
+ +<a href="/">Home</a>+ When assistive technologies render an element that gets its accessible name from its content, such as a link or button, the accessible name is the only content the user can perceive for that element. + This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented in addition to the value or content of the element. + For instance, the accessible name of a table can be derived from a caption element, and assistive technologies render both the caption and all other content contained inside the table. +
+Elements having one of the following roles are, by default, named by a string calculated from their descendant content:
+menu element is excluded.)group element is excluded.)
+ When calculating a name from content for an element, user agents recursively walk through each of its descendant elements, calculate a name string for each descendant, and concatenate the resulting strings.
+ In two special cases, certain descendants are ignored: group descendants of treeitem elements and menu descendants of menuitem elements are omitted from the calculation.
+ For example, in the following tree, the name of the first tree item is Fruits
; Apples
, Bananas
, and Oranges
are omitted.
+
+<ul role="tree">
+ <li role="treeitem">Fruits
+ <ul role="group">
+ <li role="treeitem">Apples</li>
+ <li role="treeitem">Bananas</li>
+ <li role="treeitem">Oranges</li>
+ </ul>
+ </li>
+</ul>
+
+ If an element with one of the above roles that supports naming from child content is named by using aria-label or aria-labelledby, content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby.
+ It is strongly recommended to avoid using either of these attributes to override content of one of the above elements except in rare circumstances where hiding content from assistive technology users is beneficial.
+ In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important.
+
aria-label+ The aria-label property enables authors to name an element with a string that is not visually rendered. + For example, the name of the following button is "Close". +
+<button type="button" aria-label="Close">X</button>
+ The aria-label property is useful when there is no visible text content that will serve as an appropriate accessible name.
+
+ The aria-label property affects assistive technology users in one of two different ways, depending on the role of the element to which it is applied.
+ When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces it with the value of aria-label.
+ However, when applied to nearly any other type of element, assistive technologies will render both the value of aria-label and the content of the element.
+ For example, the name of the following navigation region is "Product".
+
+<nav aria-label="Product">
+ <!-- list of navigation links to product pages -->
+</nav>+ When encountering this navigation region, a screen reader user will hear the name and role of the element, e.g., "Product navigation region", and then be able to read through the links contained in the region. +
+aria-label is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users.
+ It is strongly recommended to avoid using aria-label to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial.
+ aria-label. They are identified in the table in the Accessible Name Guidance by Role section.aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.aria-label values are translated.aria-labelledby+ The aria-labelledby property enables authors to reference other elements on the page to define an accessible name. + For example, the following switch is named by the text content of a previous sibling element. +
+
+<span id="night-mode-label">Night mode</span>
+<span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
+ Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the labeling element activate the labeled element; that is an author responsibility.
+ However, HTML label cannot be used to label a span element.
+ Fortunately, an HTML input with type="checkbox" allows the ARIA switch role, so when feasible, using the following approach creates a more robust solution.
+
+<label for="night-mode">Night mode</label>
+<input type="checkbox" role="switch" id="night-mode">The aria-labelledby property is useful in a wide variety of situations because:
aria-label.hidden attribute, CSS display: none, or CSS visibility: hidden in the calculated name string.An example of referencing a hidden element with aria-labelledby could be a label for a night switch control:
+<span id="night-mode-label" hidden>Night mode</span>
+<input type="checkbox" role="switch" aria-labelledby="night-mode-label">
+ In some cases, the most effective name for an element is its own content combined with the content of another element.
+ Because aria-labelledby has highest precedence in name calculation, in those situations, it is possible to use aria-labelledby to reference both the element itself and the other element.
+ In the following example, the "Read more..." link is named by the element itself and the article’s heading, resulting in a name for the link of "Read more... 7 ways you can help save the bees".
+
+<h2 id="bees-heading">7 ways you can help save the bees</h2>
+<p>Bees are disappearing rapidly. Here are seven things you can do to help.</p>
+<p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
+ When multiple elements are referenced by aria-labelledby, text content from each referenced element is concatenated in the order specified in the aria-labelledby value.
+ If an element is referenced more than one time, only the first reference is processed.
+ When concatenating content from multiple elements, browsers trim leading and trailing white space and separate content from each element with a single space.
+
+<button id="download-button" aria-labelledby="download-button download-details">Download</button>
+<span id="download-details">PDF, 2.4 MB</span>In the above example, the accessible name of the button will be "Download PDF, 2.4 MB", with a space between "Download" and "PDF", and not "DownloadPDF, 2.4 MB".
+aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.aria-labelledby. They are identified in the table in the Accessible Name Guidance by Role section.aria-labelledby is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby.
+ It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial.
+ aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
+ The HTML label element enables authors to identify content that serves as a label and associate it with a form control.
+ When a label element is associated with a form control, browsers calculate an accessible name for the form control from the label content.
+
+ For example, text displayed adjacent to a checkbox may be visually associated with the checkbox, so it is understood as the checkbox label by users who can perceive that visual association.
+ However, unless the text is programmatically associated with the checkbox, assistive technology users will experience a checkbox without a label.
+ Wrapping the checkbox and the labeling text in a label element as follows gives the checkbox an accessible name.
+
+<label>
+ <input type="checkbox" name="subscribe">
+ subscribe to our newsletter
+</label>
+ A form control can also be associated with a label by using the for attribute on the label element.
+ This allows the label and the form control to be siblings or have different parents in the DOM, but requires adding an id attribute to the form control, which can be error-prone.
+ When possible, use the above encapsulation technique for association instead of the following for attribute technique.
+
+<input type="checkbox" name="subscribe" id="subscribe_checkbox">
+<label for="subscribe_checkbox">subscribe to our newsletter</label>
+ Using the label element is an effective technique for satisfying Rule 2: Prefer Visible Text.
+ It also satisfies Rule 3: Prefer Native Techniques.
+ Native HTML labels offer an important usability and accessibility advantage over ARIA labeling techniques: browsers automatically make clicking the label equivalent to clicking the form control.
+ This increases the hit area of the form control.
+
+ The HTML fieldset element can be used to group form controls, and the legend element can be used to give the group a name.
+ For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons.
+
+<fieldset>
+ <legend>Select your starter class</legend>
+ <label><input type="radio" name="starter-class" value="green">Green</label>
+ <label><input type="radio" name="starter-class" value="red">Red</label>
+ <label><input type="radio" name="starter-class" value="blue">Blue</label>
+</fieldset>+ This grouping technique is particularly useful for presenting multiple choice questions. + It enables authors to associate a question with a group of answers. + If a question is not programmatically associated with its answer options, assistive technology users may access the answers without being aware of the question. +
+
+ Similar benefits can be gained from grouping and naming other types of related form fields using fieldset and legend.
+
+<fieldset>
+ <legend>Shipping address</legend>
+ <p><label>Full name <input name="name" required></label></p>
+ <p><label>Address line 1 <input name="address-1" required></label></p>
+ <p><label>Address line 2 <input name="address-2"></label></p>
+ ...
+</fieldset>
+<fieldset>
+ <legend>Billing address</legend>
+ ...
+</fieldset>Using the legend element to name a fieldset element satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.
+ The accessible name for HTML table and figure elements can be derived from a child caption or figcaption element, respectively.
+ Tables and figures often have a caption to explain what they are about, how to read them, and sometimes giving them numbers used to refer to them in surrounding prose.
+ Captions can help all users better understand content, but are especially helpful to users of assistive technologies.
+
+ In HTML, the table element marks up a data table, and can be provided with a caption using the caption element.
+ If the table element does not have aria-label or aria-labelledby, then the caption will be used as the accessible name.
+ For example, the accessible name of the following table is Special opening hours
.
+
+<table>
+ <caption>Special opening hours</caption>
+ <tr><td>30 May</td><td>Closed</td></tr>
+ <tr><td>6 June</td><td>11:00-16:00</td></tr>
+</table>The following example gives the table a number (Table 1
) so it can be referenced.
+<table>
+ <caption>Table 1. Traditional dietary intake of Okinawans and other Japanese circa 1950</caption>
+ <thead>
+ <tr>
+ <th></th>
+ <th>Okinawa, 1949</th>
+ <th>Japan, 1950</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th>Total calories</th>
+ <td>1785</td>
+ <td>2068</td>
+
+ [...]
+
+</table>Note: Above table content is from Caloric restriction, the traditional Okinawan diet, and healthy aging: the diet of the world's longest-lived people and its potential impact on morbidity and life span.
+
+ If a table is named using aria-label or aria-labelledby, then a caption element, if present, will become an accessible description.
+ For an example, see Describing Tables and Figures with Captions.
+
+ Similarly, an HTML figure element can be given a caption using the figcaption element.
+ The caption can appear before or after the figure, but it is more common for figures to have the caption after.
+
+<figure>
+ <img alt="Painting of a person walking in a desert." src="Hole_JesusalDesierto.jpg">
+ <figcaption>Jesus entering the desert as imagined by William Hole, 1908</figcaption>
+</figure>
+ Like with table elements, if a figure is not named using aria-label or aria-labelledby, the content of the figcaption element will be used as the accessible name.
+ However unlike table elements, if the figcaption element is not used for the name, it does not become an accessible description unless it is referenced by aria-describedby.
+ Nevertheless, assistive technologies will render the content of a figcaption regardless of whether it is used as a name, description, or neither.
+
Using the caption element to name a table element, or a figcaption element to name a figure element, satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.
+ When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), browsers calculate an accessible name from other attributes as a fallback mechanism.
+ Because the attributes used in fallback name calculation are not intended for naming, they typically yield low quality accessible names that are not effective.
+ So, As advised by Rule 4: Avoid Browser Fallback, prefer the explicit labeling techniques described above over fallback techniques described in this section.
+
+ Any HTML element can have a title attribute specified.
+ The title attribute may be used as the element's fallback accessible name.
+ The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device.
+
For example, a fieldset element without a legend element child, but with a title attribute, gets its accessible name from the title attribute.
+<fieldset title="Select your starter class">
+ <label><input type="radio" name="starter-class" value="green">Green</label>
+ <label><input type="radio" name="starter-class" value="red">Red</label>
+ <label><input type="radio" name="starter-class" value="blue">Blue</label>
+</fieldset>
+ For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label.
+ It is better to use a label element, since it does not disappear visually when the user focuses the form control.
+
+<!-- Using a <label> is recommended -->
+<label>Search <input type=search name=q></label>
+
+<!-- A placeholder is used as fallback -->
+<input type=search name=q placeholder="Search">+ For assistive technology users, especially screen reader users, the quality of accessible names is one of the most significant contributors to usability. + Names that do not provide enough information reduce users' effectiveness while names that are too long reduce efficiency. + And, names that are difficult to understand reduce effectiveness, efficiency, and enjoyment. +
+The following guidelines provide a starting point for crafting user friendly names.
+Xcloses a dialog, name it
Close, not
X. + Similarly, if a set of navigation links in the left side bar navigate among the product pages in a shopping site, name the navigation region
Product, not
Left. +
Edit,
Delete, and
Actionsbuttons for each contact, + then
Edit John Doe,
Delete John Doe, and
Actions for John Doewould be better accessible names than
John Doe edit,
John Doe delete, and
John Doe actions. + By placing the verb first in the name, screen reader users can more easily and quickly distinguish the buttons from one another as well as from the element that opens the contact card for John Doe. +
buttonin the name of a button, the word
imagein the name of an image, or the word
navigationin the name of a navigation region. + Doing so would create duplicate screen reader output since screen readers convey the role of an element in addition to its name. +
+ Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. + The table below lists all ARIA roles and provides the following information for each : +
+aria-label or aria-labelledby is applied, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby.
+ Avoid hiding descendant content except in the rare circumstances where doing so benefits assistive technology users.
+ | role | +Necessity of Naming | +Guidance | +
|---|---|---|
alert |
+ Discretionary | +
+ Some screen readers announce the name of an alert before announcing the content of the alert.
+ Thus, aria-label provides a method for prefacing the visible content of an alert with text that is not displayed as part of the alert.
+ Using aria-label is functionally equivalent to providing off-screen text in the contents of the alert, except off-screen text would be announced by screen readers that do not support aria-label on alert elements.
+ |
+
alertdialog |
+ Required | +Use aria-labelledby if a visible label is present, otherwise use aria-label. |
+
application |
+ Required | +Use aria-labelledby if a visible label is present, otherwise use aria-label. |
+
article |
+ Recommended | +
+
|
+
banner |
+ Discretionary | +
+
|
+
blockquote |
+ Discretionary | +
+ If a visible label is present, associating it with the blockquote by using aria-labelledby could benefit some assistive technology users.
+ |
+
button |
+ Required Only If Content Insufficient | +
+
|
+
caption |
+ Prohibited | ++ |
cell |
+ Required Only If Content Insufficient | +
+
|
+
checkbox |
+ Required Only If Content Insufficient | +
+
|
+
code |
+ Prohibited | ++ |
columnheader |
+ Required Only If Content Insufficient | +
+
|
+
combobox |
+ Required | +
+
|
+
complementary |
+ Recommended | +
+
|
+
contentinfo |
+ Discretionary | +
+
|
+
definition |
+ Recommended | +Reference the term being defined with role="term", using aria-labelledby. |
+
deletion |
+ Prohibited | ++ |
dialog |
+ Required | +Use aria-labelledby if a visible label is present, otherwise use aria-label. |
+
directory |
+ Discretionary | +
+
|
+
document |
+ Discretionary | +
+ Elements with the document role are contained within an element with the application role, which is required to have a name.
+ Typically, the name of the application element will provide sufficient context and identity for the document element.
+ Because the application element is used only to create unusual, custom widgets, careful assessment is necessary to determine whether or not adding an accessible name is beneficial.
+ |
+
emphasis |
+ Prohibited | ++ |
feed |
+ Recommended | +
+
|
+
figure |
+ Recommended | +
+
|
+
form |
+ Recommended | +
+
|
+
generic |
+ Prohibited | ++ |
grid |
+ Required | +
+
|
+
gridcell |
+ Required Only If Content Insufficient | +
+
|
+
group |
+ Discretionary | +
+
|
+
heading |
+ Required Only If Content Insufficient | +
+
|
+
insertion |
+ Prohibited | ++ |
img |
+ Required | +For the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label. |
+
link |
+ Required Only If Content Insufficient | +
+
|
+
list |
+ Discretionary | +
+
|
+
listbox |
+ Required | +
+
|
+
listitem |
+ Do Not Name | +Naming is not supported by assistive technologies; it is necessary to include relevant content within the list item. | +
log |
+ Discretionary | +
+ Some screen readers announce the name of a log element before announcing the content of the log element.
+ Thus, aria-label provides a method for prefacing the visible content of a log element with text that is not displayed as part of the log element.
+ Using aria-label is functionally equivalent to providing off-screen text in the contents of the log element, except off-screen text would be announced by screen readers that do not support aria-label on log elements.
+ |
+
main |
+ Discretionary | +
+
|
+
marquee |
+ Discretionary | +Use aria-labelledby if a visible label is present, otherwise use aria-label. |
+
math |
+ Recommended | +
+
|
+
menu |
+ Recommended | +
+
|
+
menubar |
+ Recommended | +
+
|
+
menuitem |
+ Required Only If Content Insufficient | +
+
|
+
menuitemcheckbox |
+ Required Only If Content Insufficient | +
+
|
+
menuitemradio |
+ Required Only If Content Insufficient | +
+
|
+
meter |
+ Required | +
+
|
+
navigation |
+ Recommended | +
+
|
+
none |
+ Prohibited | +An element with role="none" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label. |
+
note |
+ Discretionary | +
+
|
+
option |
+ Required Only If Content Insufficient | +
+
|
+
paragraph |
+ Prohibited | ++ |
presentation |
+ Prohibited | +An element with role="presentation" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label. |
+
progressbar |
+ Required | +
+
|
+
radio |
+ Required Only If Content Insufficient | +
+
|
+
radiogroup |
+ Required | +
+
|
+
region |
+ Required | +
+
|
+
row |
+
+ Required Only If Content Insufficient
+ AND descendant of a treegrid
+ AND the row is focusable
+ |
+
+ When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row.
+ This is typically the most appropriate behavior.
+ However, in some circumstances, it could be beneficial to change the order in which cells are announced or exclude announcement of certain cells by using aria-labelledby to specify which cells to announce.
+ |
+
rowgroup |
+ Do Not Name | +Naming is not supported by assistive technologies. | +
rowheader |
+ Required Only If Content Insufficient | +
+
|
+
scrollbar |
+ Discretionary | +
+
|
+
search |
+ Recommended | +
+
|
+
searchbox |
+ Required | +
+
|
+
separator |
+ Discretionary | +
+
|
+
slider |
+ Required | +
+
|
+
spinbutton |
+ Required | +
+
|
+
status |
+ Discretionary | +
+ Some screen readers announce the name of a status element before announcing the content of the status element.
+ Thus, aria-label provides a method for prefacing the visible content of a status element with text that is not displayed as part of the status element.
+ Using aria-label is functionally equivalent to providing off-screen text in the contents of the status element, except off-screen text would be announced by screen readers that do not support aria-label on status elements.
+ |
+
strong |
+ Prohibited | ++ |
subscript |
+ Prohibited | ++ |
superscript |
+ Prohibited | ++ |
switch |
+ Required Only If Content Insufficient | +
+
|
+
tab |
+ Required Only If Content Insufficient | +
+
|
+
table |
+ Required | +
+
|
+
tablist |
+ Recommended | +
+
|
+
tabpanel |
+ Required | +
+
|
+
term |
+ Do Not Name | +Since a term is usually the name for the role="definition" element, it could be confusing if the term itself also has a name. |
+
textbox |
+ Required | +
+
|
+
time |
+ Do Not Name | +Naming is not supported by assistive technologies. | +
timer |
+ Discretionary | +
+ Some screen readers announce the name of a timer element before announcing the content of the timer element.
+ Thus, aria-label provides a method for prefacing the visible content of a timer element with text that is not displayed as part of the timer element.
+ Using aria-label is functionally equivalent to providing off-screen text in the contents of the timer element, except off-screen text would be announced by screen readers that do not support aria-label on timer elements.
+ |
+
toolbar |
+ Recommended | +
+
|
+
tooltip |
+ Required Only If Content Insufficient | +
+
|
+
tree |
+ Required | +
+
|
+
treegrid |
+ Required | +
+
|
+
treeitem |
+ Required Only If Content Insufficient | +
+
|
+
+ User agents construct an accessible name string for an element by walking through a list of potential naming methods and using the first that generates a name. + The algorithm they follow is defined in the accessible name specification. + It is roughly like the following: +
+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 host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:
+input whose type attribute is in the Button, Submit Button, or Reset Button statevalue attribute.input whose type attribute is in the Image Button stateimgareaalt attribute. fieldsetlegend element.label element(s).figurefigcaption element.tablecaption element.If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.
Finally, if the name is still empty, then other fallback host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:
+input whose type attribute is in the Text, Password, Search, Telephone, or URL statestextareatitle attribute. Otherwise, the placeholder attribute.input whose type attribute is in the Submit Button stateinput whose type attribute is in the Reset Button stateinput whose type attribute is in the Image Button statetitle attribute. Otherwise, a localized string of the phrase "Submit Query".summarytitle attribute.+ The final step is a fallback mechanism. Generally when labeling an element, use one of the non-fallback mechanisms. +
+
+ When calculating a name from content, the user agent walks through all descendant nodes except in the cases of treeitem and menuitem as described below.
+ And, when following references in an aria-labelledby attribute, it similarly walks the tree of each referenced element.
+ Thus, the naming algorithm is recursive.
+ The following two sections explain non-recursive and recursive examples of how the algorithm works.
+
+ When calculating a name from content for the treeitem role, descendant content of child group elements are not included.
+ For example, in the following tree, the name of the first tree item is Fruits
; Apples
, Bananas
, and Oranges
are automatically omitted.
+
+<ul role="tree">
+ <li role="treeitem">Fruits
+ <ul role="group">
+ <li role="treeitem">Apples</li>
+ <li role="treeitem">Bananas</li>
+ <li role="treeitem">Oranges</li>
+ </ul>
+ </li>
+</ul>
+ Similarly, when calculating a name from content for the menuitem role, descendant content of child menu elements are not included.
+ So, the name of the first parent menuitem in the following menu is Fruits
.
+
+<ul role="menu">
+ <li role="menuitem">Fruits
+ <ul role="menu">
+ <li role="menuitem">Apples</li>
+ <li role="menuitem">Bananas</li>
+ <li role="menuitem">Oranges</li>
+ </ul>
+ </li>
+</ul>Consider an input element that has no associated label element and only a name attribute and so does not have an accessible name (do not do this):
<input name="code">If there is a placeholder attribute, then it serves as a naming fallback mechanism (avoid doing this):
+<input name="code"
+ placeholder="One-time code">If there is also a title attribute, then it is used as the accessible name instead of placeholder, but it is still a fallback (avoid doing this):
+<input name="code"
+ placeholder="123456"
+ title="One-time code">If there is also a label element (recommended), then that is used as the accessible name, and the title attribute is instead used as the accessible description:
+<label>One-time code
+ <input name="code"
+ placeholder="123456"
+ title="Get your code from the app.">
+</label>If there is also an aria-label attribute (not recommended unless it adds clarity for assistive technology users), then that becomes the accessible name, overriding the label element:
+<label>Code
+ <input name="code"
+ aria-label="One-time code"
+ placeholder="123456"
+ title="Get your code from the app.">
+</label>If there is also an aria-labelledby attribute, that wins over the other elements and attributes (the aria-label attribute ought to be removed if it is not used):
+<p>Please fill in your <span id="code-label">one-time code</span> to log in.</p>
+<p>
+ <label>Code
+ <input name="code"
+ aria-labelledby="code-label"
+ aria-label="This is ignored"
+ placeholder="123456"
+ title="Get your code from the app.">
+ </label>
+</p>
+ The accessible name calculation algorithm will be invoked recursively when necessary.
+ An aria-labelledby reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.
+
In this example, the label for the button is computed by recursing into each child node, resulting in Move to trash
.
<button>Move to <img src="bin.svg" alt="trash"></button>When following an aria-labelledby reference, the algorithm avoids following the same reference twice to avoid infinite loops.
+ In this example, the label for the button is computed by first following the aria-labelledby reference to the parent element, and then computing the label for that element from the child nodes, first visiting the button element again but ignoring the aria-labelledby reference and instead using the aria-label, and then visiting the next child (the text node).
+ The resulting label is Remove meeting: Daily status report
.
+
+<div id="meeting-1">
+ <button aria-labelledby="meeting-1" aria-label="Remove meeting:">X</button>
+ Daily status report
+</div>aria-describedby
+ The aria-describedby property works similarly to the aria-labelledby property.
+ For example, a button could be described by a sibling paragraph.
+
+<button aria-describedby="trash-desc">Move to trash</button>
+...
+<p id="trash-desc">Items in the trash will be permanently removed after 30 days.</p>
+ Descriptions are reduced to text strings.
+ For example, if the description contains an HTML img element, a text equivalent of the image is computed.
+
+<button aria-describedby="trash-desc">Move to <img src="bin.svg" alt="trash"></button>
+...
+<p id="trash-desc">Items in <img src="bin.svg" alt="the trash"> will be permanently removed after 30 days.</p>
+ As with aria-labelledby, it is possible to reference an element using aria-describedby even if that element is hidden.
+ For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget.
+ The description could also be referenced from the text field directly with aria-describedby.
+ In the following example, the accessible description for the input element is Your username is the name that you use to log in to this service.
+
+<label for="username">Username</label>
+<input id="username" name="username" aria-describedby="username-desc">
+<button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
+<p id="username-desc" hidden>
+ Your username is the name that you use to log in to this service.
+</p>
+ In HTML, if the table is named using aria-label or aria-labelledby, a child caption element becomes an accessible description.
+ For example, a preceding heading might serve as an appropriate accessible name, and the caption element might contain a longer description.
+ In such a situation, aria-labelledby could be used on the table to set the accessible name to the heading content and the caption would become the accessible description.
+
+<h2 id="events-heading">Upcoming events</h2>
+<table aria-labelledby="events-heading">
+ <caption>
+ Calendar of upcoming events, weeks 27 through 31, with each week starting with
+ Monday. The first column is the week number.
+ </caption>
+ <tr><th>Week</th><th>Monday</th><th>Tuesday</th><th>Wednesday</th><th>Thursday</th><th>Friday</th><th>Saturday</th><th>Sunday</th></tr>
+ <tr><td>27</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
+ <tr><td>28</td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/events/9856">Crown Princess's birthday</a></td></tr>
+ <tr><td>29</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
+ <tr><td>30</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
+ <tr><td>31</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
+</table>
+ The HTML figure element can get its accessible name from its figcaption element, but it will not be used as the accessible description, even if it was not used as the accessible name.
+ If the figcaption element is appropriate as an accessible description, and the accessible name is set using aria-labelledby or aria-label, then the figcaption can be explicitly set as the accessible description using the aria-describedby attribute.
+
+<h2 id="neutron">Neutron</h2>
+<figure aria-labelledby="neutron" aria-describedby="neutron-caption">
+ <img src="neutron.svg" alt="Within the neutron are three quarks (blue 'u', red 'd', green 'd') that are interconnected.">
+ <figcaption id="neutron-caption">
+ The quark content of the neutron. The color assignment of individual quarks is
+ arbitrary, but all three colors must be present. Forces between quarks are
+ mediated by gluons.
+ </figcaption>
+</figure>If an accessible description was not provided using the aria-describedby attribute or one of the primary host-language-specific attributes or elements (e.g., the caption element for table), then, for HTML, if the element has a title attribute, that is used as the accessible description.
+ A visible description together with aria-describedby is generally recommended.
+ If a description that is not visible is desired, then the title attribute can be used, for any HTML element that can have an accessible description.
+
Note that the title attribute might not be accessible to some users, in particular sighted users not using a screen reader and not using a pointing device that supports hover (e.g., a mouse).
For example, an input element with input constrained using the pattern attribute can use the title attribute to describe what the expected input is.
+<label> Part number:
+ <input pattern="[0-9][A-Z]{3}" name="part"
+ title="A part number is a digit followed by three uppercase letters."/>
+</label>The title attribute in this case can be shown to the user as a tooltip when the user hovers or focuses the control, but also as part of the error message when the user agent validates the form, if the input element's value doesn't match the pattern.
As another example, a link can use the title attribute to describe the link in more detail.
+<a href="http://twitter.com/W3C"
+ title="Follow W3C on Twitter">
+ <img src="/2008/site/images/Twitter_bird_logo_2012.svg"
+ alt="Twitter" class="social-icon" height="40" />
+</a>+ Like the accessible name calculation, the accessible description calculation produces a text string. +
+
+ The accessible description calculation algorithm is the same as the accessible name calculation algorithm except for a few branch points that depend on whether a name or description is being calculated.
+ In particular, when accumulating text for an accessible description, the algorithm uses aria-describedby instead of aria-labelledby.
+
+ User agents construct an accessible description string for an element by walking through a list of potential description methods and using the first that generates a description. + The algorithm they follow is defined in the accessible name specification. + It is roughly like the following: +
+The aria-describedby property is used if present.
If the description is still empty, then host-language-specific attributes or elements are used if present, if it wasn't already used as the accessible name. For HTML, these are, depending on the element:
+input whose type attribute is in the Button, Submit Button, or Reset Button statevalue attribute.summarytablecaption element.Finally, if the description is still empty, then other host-language-specific attributes or elements are used if present, if it wasn't already used for the accessible name. For HTML, this is the title attribute.
+ ARIA defines the following roles as range widgets, which means they communicate a value that is typically numeric and constrained to defined limits. +
+meterprogressbarscrollbarseparator (if focusable)sliderspinbutton+ For example, a spin button for choosing a day within the month of January would allow integer values that range from 1 to 31. + In some cases, the value is represented numerically, but is not presented as a number to users. + For instance, a spin button for choosing a day of the week could support values from 1 to 7 but they could be presented to the user as day names, e.g., "Monday", "Tuesday", etc. +
++ This section describes considerations for using the following four properties that communicate characteristics of a range widget: +
+| Property | +Definition | +
|---|---|
aria-valuemin |
+ Defines the minimum value allowed by a range widget. | +
aria-valuemax |
+ Defines the maximum value allowed by a range widget. | +
aria-valuenow |
+ Defines the current value of a range widget. This value is a number greater than or equal to aria-valuemin and less than or equal to aria-valuemax (if they are specified). |
+
aria-valuetext |
+ If a numeric value is not sufficiently descriptive, this property can define a text description of the current value of a range widget. | +
+ ARIA provides a set of roles that convey the accessibility semantics of structures on a page. + These roles express the meaning that is conveyed by the layout and appearance of elements that organize and structure content, such as headings, lists, and tables. +
+
+ some host languages, such as HTML, include elements that express the same semantics as an ARIA role.
+ For instance, the HTML <p> element is mapped to accessibility APIs in exactly the same way as <div role="paragraph">.
+ The ARIA and HTML specifications refer to this mapping of HTML elements to ARIA attributes as implied semantics, i.e., the implied ARIA role of the HTML <p> element is paragraph.
+
+ When developing HTML, it is important to use native HTML elements where ever possible. + Do not use an ARIA role or property if it is possible to use an HTML element that has equivalent semantics. +
+Circumstances where it is appropriate to use ARIA attributes instead of equivalent HTML are:
++ The following table lists all structural roles defined in ARIA 1.2. + As described above in the section on + When to Use Structural Roles, + use an equivalent HTML element instead of an ARIA structural role unless the ARIA role does not have an HTML equivalent or one of the four circumstances that makes using ARIA necessary exists. +
+| ARIA Role | +HTML Equivalent | +
|---|---|
| application | No equivalent element |
| article | article |
| blockquote | blockquote |
| caption | caption |
| cell | td |
| code | code |
| columnheader | th |
| definition | dd |
| deletion | del |
| directory | No equivalent element |
| document | No equivalent element |
| emphasis | em |
| feed | No equivalent element |
| figure | figure |
| generic | div, span |
| group | No equivalent element |
| heading with aria-level="N" where N is 1, 2, 3, 4, 5, or 6 | h1, h2, h3, h4, h5, h6 |
| insertion | ins |
| img | img |
| list | ul, ol |
| listitem | li |
| math | No equivalent element |
| none | No equivalent element |
| note | No equivalent element |
| presentation | No equivalent element |
| paragraph | p |
| row | tr |
| rowgroup | tbody, thead, tfoot |
| rowheader | th |
| separator (when not focusable) | hr |
| strong | strong |
| subscript | sub |
| superscript | sup |
| table | table |
| term | dfn |
| time | time |
| toolbar | No equivalent element |
| tooltip | No equivalent element |