Accessible Rich Internet Applications (WAI-ARIA) 1.3

A type of live region with important, and usually time-sensitive, information. See related alertdialog and status.

Alerts are used to convey messages that will be immediately important to users. In the case of audio warnings, visibly displayed alerts provide an accessible alternative to audible alerts for Deaf or hard-of-hearing users. Likewise, alerts can provide an accessible alternative to the visible alerts for blind, deaf-blind, or low-vision users, and others with certain developmental disabilities. The alert role is applied to the element containing the alert message.

Alert is a special type of assertive live region that is intended to cause immediate notification for assistive technology users. If the operating system allows, the user agent SHOULD fire a system alert event through the accessibility API when the alert is rendered.

Neither authors nor user agents are required to set or manage focus to an alert in order for it to be processed. Since alerts are not required to receive focus, authors SHOULD NOT require users to close an alert. If an author desires focus to move to a message when it is conveyed, the author SHOULD use alertdialog instead of alert.

Elements with the role alert have an implicit aria-live value of assertive, and an implicit aria-atomic value of true.

A type of dialog that contains an alert message, where initial focus goes to an element within the dialog. See related alert and dialog.

Alert dialogs are used to convey messages to alert the user. The alertdialog role goes on the node containing both the alert message and the rest of the dialog. Authors SHOULD make alert dialogs modal by ensuring that, while the alertdialog is shown, keyboard and mouse interactions only operate within the dialog. See aria-modal.

Alertdialog is a special type of dialog that is intended to cause an immediate, alert-level notification for assistive technology users. If the operating system allows, the user agent SHOULD fire a system alert event through the accessibility API when the alert dialog is rendered.

Unlike alert, alertdialog can receive a response from the user. For example, to confirm that the user understands the alert being generated. When the alert dialog is displayed, authors SHOULD set focus to an active element within the alert dialog, such as a form control or confirmation button. The user agent SHOULD fire a system alert event through the accessibility API when the alert is created, provided one is specified by the intended accessibility API.

Authors SHOULD provide an accessible name for an alertdialog, which can be done with the aria-label or aria-labelledby attribute.

Authors SHOULD use aria-describedby on an alertdialog to reference the alert message element in the dialog. If they do not, an assistive technology can resort to its internal recovery mechanism to determine the contents of the alert message.

A structure containing one or more focusable elements requiring user input, such as keyboard or gesture events, that do not follow a standard interaction pattern supported by a widget role.

Some user agents and assistive technologies have a browse mode where standard input events, such as up and down arrow key events, are intercepted and used to control a reading cursor. This browse mode behavior prevents elements that do not have a widget role from receiving and using such keyboard and gesture events to provide interactive functionality.

When there is a need to create an element with an interaction model that is not supported by any of the WAI-ARIA widget roles, authors MAY give that element role application. And, when a user navigates into an element with role application, assistive technologies that intercept standard input events SHOULD switch to a mode that passes most or all standard input events through to the web application.

For example, a presentation slide editor uses arrow keys to change the positions of textbox and image elements on the slide. There are not any WAI-ARIA widget roles that correspond to such an interaction model so an author could give the slide container role application, an aria-roledescription of "Slide Editor", and use aria-describedby to provide instructions.

Because only the focusable elements contained in an application element are accessible to users of some assistive technologies, authors MUST use one of the following techniques to ensure all non-decorative static text or image content inside an application is accessible:

1. Associate the content with a focusable element using aria-labelledby or aria-describedby.
2. Place the content in a focusable element that has role document or article.
3. Manage focus of accessibility descendants as described in Managing Focus, updating the value of aria-activedescendant to reference the element containing the focused content.

A section of a page that consists of a composition that forms an independent part of a document, page, or site.

An article is not a navigational landmark, but can be nested to form a discussion where assistive technologies could pay attention to article nesting to assist the user in following the discussion. An article could be a forum post, a magazine or newspaper article, a web log entry, a user-submitted comment, or any other independent item of content. It is independent in that its contents could stand alone, for example in syndication. However, the element is still associated with its ancestors; for instance, contact information that applies to a parent body element still covers the article as well. When nesting articles, the child articles represent content that is related to the content of the parent article. For instance, a web log entry on a site that accepts user-submitted comments could represent the comments as articles nested within the article for the web log entry. Author, heading, date, or other information associated with an article does not apply to nested articles.

When the user navigates to an element assigned the role of article, assistive technologies that typically intercept standard keyboard events SHOULD switch to document browsing mode, as opposed to passing keyboard events through to the web application. Some assistive technologies provide a feature allowing the user to navigate the hierarchy of any nested article elements.

When an article is in the context of a feed, the author MAY specify values for aria-posinset and aria-setsize.

A landmark that contains mostly site-oriented content, rather than page-specific content.

Site-oriented content typically includes things such as the logo or identity of the site sponsor, and a site-specific search tool. A banner usually appears at the top of the page and typically spans the full width.

Assistive technologies SHOULD enable users to quickly navigate to elements with role banner. user agents SHOULD treat elements with role banner as navigational landmarks. user agents MAY enable users to quickly navigate to elements with role banner.

The author SHOULD mark no more than one element on a page with the banner role.

A section of content that is quoted from another source.

An input that allows for user-triggered actions when clicked or pressed. See related link.

Buttons are mostly used for discrete actions. Standardizing the appearance of buttons enhances the user's recognition of the widgets as buttons and allows for a more compact display in toolbars.

Buttons support the optional attribute aria-pressed. Buttons with a non-empty aria-pressed attribute are toggle buttons. When aria-pressed is true the button is in a "pressed" state, when aria-pressed is false it is not pressed. If the attribute is not present, the button is a simple command button.

Visible content that names, or describes a figure, grid, group, radiogroup, table or treegrid.

When using caption authors SHOULD ensure:

• The caption is a descendant of a figure, grid, group, radiogroup, table, or treegrid.
• The caption is the first non-generic descendant of a grid, group, radiogroup, table or treegrid.
• The caption is the first or last non-generic descendant of a figure.

If the caption represents an accessible name for its containing element, authors SHOULD specify aria-labelledby on the containing element to reference the element with role caption.

<div role="radiogroup" aria-labelledby="cap">
   <div role="caption" id="cap">
     Choose your favorite fruit
   </div>
   <!-- ... -->

If a caption contains content that serves as both a name and description for its containing element, authors MAY instead specify aria-labelledby to reference an element within the caption that represents the "name" of the containing element, and specify aria-describedby to reference an element within the caption that represents the descriptive content.

<div role="table" aria-labelledby="name" aria-describedby="desc">
   <div role="caption">
     <div id="name">Contest Entrants</div>
     <div id="desc">
       This table shows the total number of entrants (500) the
       contest accepted over the past four weeks.
     </div>
   </div>
   <!-- ... -->

If the caption represents a long-form description, or if the description contains semantic elements which are important in understanding the description, authors MAY instead specify aria-labelledby to reference an element within the caption that represents the "name" of the containing element, and specify aria-details to reference an element within the caption that represents the descriptive content.

<div role="figure" aria-labelledby="name" aria-details="details">
  <!-- figure content here, such as a complex data viz SVG -->
   <div role="caption">
     <div id="name">Sales information for 20XX</div>
     <div id="details">
       This barchart represents the total amount of sales over the course
       of five years. <a href="...">Sales information for last year</a> can
       be reviewed, or you can overlay <button aria-pressed="false">previous year</button>
       information in this graphic.
     </div>
   </div>
   <!-- ... -->

If a caption contains only a description, without a suitable text string to serve as the accessible name for its containing element, then aria-label or aria-labelledby MAY be used to provide an accessible name, and the caption MAY be treated solely as descriptive content, referenced via aria-details.

<div role="figure" aria-label="Sales information" aria-details="details">
  <!-- figure content here, such as a complex data viz SVG -->
   <div role="caption" id="details">
     This barchart represents the total amount of sales over the course
     of five years. <a href="...">Sales information for last year</a> can
     be reviewed, or you can overlay <button aria-pressed="false">previous year</button>
     information in this graphic.
   </div>
   <!-- ... -->

A cell in a tabular container. See related gridcell.

Authors MUST ensure elements with role cell are the accessibility children of an element with the role row.

A checkable input that has three possible values: true, false, or mixed.

The aria-checked attribute of a checkbox indicates whether the input is checked (true), unchecked (false), or represents a group of elements that have a mixture of checked and unchecked values (mixed). Many checkboxes do not use the mixed value, and thus are effectively boolean checkboxes.

A section whose content represents a fragment of computer code.

The primary purpose of the code role is to inform assistive technologies that the content is computer code and thus might require special presentation, in particular with respect to synthesized speech. More specifically, screen readers and other tools which provide text-to-speech presentation of content SHOULD prefer full punctuation verbosity to ensure common symbols (e.g., "-") are spoken.

A cell containing header information for a column.

columnheader can be used as a column header in a table or grid. It could also be used in a pie chart to show a similar relationship in the data.

The columnheader establishes a relationship between it and all cells in the corresponding column. It is the structural equivalent to an HTML th element with a column scope.

Authors MUST ensure elements with role columnheader are the accessibility children of an element with the role row.

Applying the aria-selected state on a columnheader MUST not cause the user agent to automatically propagate the aria-selected state to all the cells in the corresponding column. An author MAY choose to propagate selection in this manner depending on the specific application.

While the columnheader role can be used in both interactive grids and non-interactive tables, the use of aria-readonly and aria-required is only applicable to interactive elements. Therefore, authors SHOULD NOT use aria-required or aria-readonly in a columnheader that descends from a table, and user agents SHOULD NOT expose either property to assistive technologies unless the columnheader descends from a grid.

An input that controls another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of the input.

A combobox functionally combines a named input field with the ability to assist value selection via a supplementary popup element. A combobox input MAY be either a single-line text field that supports editing and typing or an element that only displays the current value of the combobox. If the combobox supports text input and provides autocompletion behavior as described in aria-autocomplete, authors MUST set aria-autocomplete on the combobox element to the value that corresponds to the provided behavior.

Typically, the initial state of a combobox is collapsed. In the collapsed state, only the combobox element and a separate, optional popup control button are visible. A combobox is said to be expanded when both the combobox element showing its current value and its associated popup element are visible. Authors MUST set aria-expanded to true on an element with role combobox when it is expanded and false when it is collapsed.

Elements with the role combobox have an implicit aria-haspopup value of listbox. If the combobox popup element has a role other than listbox, authors MUST specify an aria-haspopup value of tree, grid, or dialog that corresponds to the role of its popup.

If the user interface includes an additional icon that allows the visibility of the popup to be controlled via pointer and touch events, authors SHOULD ensure that element has role button, that it is focusable but not included in the page Tab sequence, and that it is not a descendant of the element with role combobox. In addition, to be keyboard accessible, authors SHOULD provide keyboard mechanisms for moving focus between the combobox element and elements contained in the popup. For example, one common convention is that Down Arrow moves focus from the input to the first focusable descendant of the popup element. If the popup element supports aria-activedescendant, in lieu of moving focus, such keyboard mechanisms can control the value of aria-activedescendant on the combobox element. When a descendant of the popup element is active, authors MAY set aria-activedescendant on the combobox to a value that refers to the active element within the popup while focus remains on the combobox element.

User agents MUST expose the value of elements with role combobox to assistive technologies. The value of a combobox is represented by one of the following:

• If the combobox element is a host language element that provides a value, such as an HTML input element, the value of the combobox is the value of that element.
• Otherwise, the value of the combobox is represented by its descendant elements and can be determined using the same method used to compute the name of a button from its descendant content.

<label id="tag_label" for="tag_combo">Tag</label>
  <input type="text" id="tag_combo"
      role="combobox" aria-autocomplete="list"
      aria-haspopup="listbox" aria-expanded="true"
      aria-controls="popup_listbox" aria-activedescendant="selected_option">
<ul role="listbox" id="popup_listbox" aria-labelledby="tag_label">
   <li role="option">Zebra</li>
   <li role="option" id="selected_option">Zoom</li>
</ul>

The features and behaviors of combobox implementations vary widely. Consequently, there are many important authoring considerations. See the ARIA Authoring Practices Guide for additional details on implementing combobox design patterns.

A form of widget that performs an action but does not receive input data.

command is an abstract role used for the ontology. Authors MUST NOT use command role in content.

A comment contains content expressing reaction to other content.

Comments can annotate any visible content, from small spans of text, to other comments, to entire articles. Authors SHOULD identify the relationships between comments and the commented content, as follows:

1. If the comment is a reply to another comment:
   • If all ancestor comments are available in the DOM, make each reply comment a semantic descendant of the comment to which it is replying, either by making it a DOM descendant element or by using aria-owns.
   • Alternatively, if all ancestor comments are not in the DOM, such as when comments are paginated, the hierarchical level MAY be indicated via aria-level. Additional group positional information MAY be indicated via aria-posinset and aria-setsize.
2. Otherwise, if the comment relates to other content in the page:
   • Provide aria-details on the element containing the commented content with a value refering to the element with role comment.
   • If there are multiple comments related to the same commented content, either provide a value for aria-details on the commented content that refers to each individual comment, or use aria-details to refer to a parent container of the comments. If aria-details refers to an element containing comments rather than comment elements, authors SHOULD assign a role of group or region to the referenced container.

If the author has not explicitly declared aria-level, aria-posinset, or aria-setsize for a comment element, user agents MUST automatically compute the missing values and expose them to assistive technologies.

A landmark that is designed to be complementary to the main content that it is a sibling to, or a direct descendant of. The contents of a complementary landmark would be expected to remain meaningful if it were to be separated from the main content it is relevant to.

There are various types of content that would appropriately have this role. For example, in the case of a portal, this can include but not be limited to show times, current weather, related articles, or stocks to watch. If the complementary content is completely separable from the main content, it might be appropriate to use a more general role.

Assistive technologies SHOULD enable users to quickly navigate to elements with role complementary. user agents SHOULD treat elements with role complementary as navigational landmarks. user agents MAY enable users to quickly navigate to elements with role complementary.

A widget that can contain navigable accessibility descendants.

Authors SHOULD ensure that a composite widget exists as a single navigation stop within the larger navigation system of the web page. Once the composite widget has focus, authors SHOULD provide a separate navigation mechanism for users to navigate to elements that are accessibility descendants of the composite element.

composite is an abstract role used for the ontology. Authors MUST NOT use composite role in content.

A landmark that contains information about the parent document.

Examples of information included in this region of the page are copyrights and links to privacy statements.

Assistive technologies SHOULD enable users to quickly navigate to elements with role contentinfo. user agents SHOULD treat elements with role contentinfo as navigational landmarks. user agents MAY enable users to quickly navigate to elements with role contentinfo.

The author SHOULD mark no more than one element on a page with the contentinfo role.

A definition of a term or concept. See related term.

Authors MUST identify the element being defined and assign that element a role of term.

Authors SHOULD NOT use the definition role on interactive elements such as form controls because doing so could prevent users of assistive technologies from interacting with those elements.

A deletion represents content that is marked as removed, content that is being suggested for removal, or content that is no longer relevant in the context of its accompanying content. See related insertion.

Deletions are typically used to either mark differences between two versions of content or to designate content suggested for removal in scenarios where multiple people are revising content.

A dialog is a descendant window of the primary window of a web application. For HTML pages, the primary application window is the entire web document.

Dialogs are often used to prompt the user to enter or respond to information, or can represent content related to understanding or modifying the content of the primary application window. A dialog that is designed to interrupt workflow and prevent users from interacting with the primary web application is usually modal. See related alertdialog. A dialog that allows for the user to switch between interacting with the content of the primary web application and the content the dialog is usually modeless (i.e., non-modal). In lieu of using robust host language features for marking content of the primary web application as inert, authors SHOULD use the aria-modal attribute, and constrain focus to dialogs. See the WAI-ARIA Authoring Practices: Dialog (modal) pattern for additional details on implementing modal dialog design patterns.

Authors SHOULD provide an accessible name for a dialog, which can be done with the aria-label or aria-labelledby attribute.

Authors SHOULD ensure that all dialogs (both modal and non-modal) have at least one focusable descendant element. Authors SHOULD focus an element in the modal dialog when it is displayed, and authors SHOULD constrain keyboard focus to focusable elements within a modal dialog, until dismissed.

Authors SHOULD provide a dialog an accessible description, with the aria-describedby attribute, for instances where authors have set initial keyboard focus on an element that follows content that outlines the purpose of the dialog. Assistive technology SHOULD give precedence to exposing author defined dialog accessible descriptions when a dialog is invoked and user focus is moved to a descendant of the dialog element.

[Deprecated in ARIA 1.2] A list of references to members of a group, such as a static table of contents.

A directory is a static table of contents, whether linked or unlinked. This includes tables of contents built with lists, including nested lists. Dynamic tables of contents, however, might use a tree role instead.

An element containing content that assistive technology users might want to browse in a reading mode.

When user agent focus moves to an element assigned the role of document, assistive technologies having a reading mode for browsing static content MAY switch to that reading mode and intercept standard input events, such as Up or Down arrow keyboard events, to control the reading cursor.

Because assistive technologies that have a reading mode default to that mode for all elements except for those with either a widget or application role, the only circumstance where the document role is useful for changing assistive technology behavior is when the element with role document is a focusable child element of a widget or application. For example, given an application element which contains some static rich text, the author can apply role document to the element containing the text and give it a tabindex of 0. When a screen reader user presses the Tab key and places focus on the document element, the user will be able to read the text with the screen reader's reading cursor.

One or more emphasized characters. See related strong.

The purpose of the emphasis role is to stress or emphasize content. It is not for communicating changes in typographical presentation that do not impact the meaning of the content. Authors SHOULD use the emphasis role only if its absence would change the meaning of the content.

The emphasis role is not intended to convey importance; for that purpose, the strong role is more appropriate.

A scrollable list of articles where scrolling might cause articles to be added to or removed from either end of the list.

A feed enables users of assistive technologies that have a document browse mode, such as screen readers, to use the browse mode reading cursor to both read and scroll through a stream of rich content that might continue scrolling infinitely by loading more content as the user reads. In a feed, assistive technologies provide a web application with signals of the user's reading cursor movement by moving user agent focus, enabling the application to both add new content and visually position content as the user browses the page. The feed also lets authors inform assistive technologies when additions and removals are occurring so assistive technologies can more reliably update their reading view without disrupting reading or degrading performance.

For example, a feed could be used to present a stream of news stories where each article contains a story with text, links, images, and comments as well as widgets for sharing and commenting. As a screen reader user reads and interacts with each story and moves the screen reader reading cursor from story to story, each story scrolls into view and, as needed, new stories are loaded.

A feed is a container element whose children have role article. When articles are added or removed from either or both ends of a feed, authors SHOULD set aria-busy to true on the feed element before the changes are made and set it to false after the changes are complete. Authors SHOULD avoid inserting or removing articles in the middle of a feed. These requirements help assistive technologies gracefully respond to changes in the feed content that occur simultaneously with user commands to move the reading cursor within the feed.

Authors SHOULD make each article in a feed focusable and ensure that the application scrolls an article into view when user agent focus is set on the article or one of its descendant elements. For example, in HTML, each article element should have a tabindex value of either -1 or 0.

When an assistive technology reading cursor moves from one article to another, assistive technologies SHOULD set user agent focus on the article that contains the reading cursor. If the reading cursor lands on a focusable element inside the article, the assistive technology MAY set focus on that element in lieu of setting focus on the containing article.

Because the ability to scroll to another article with an assistive technology reading cursor depends on the presence of another article in the page, authors SHOULD attempt to load additional articles before user agent focus reaches an article at either end of the set of articles that has been loaded. Alternatively, authors MAY include an article at either or both ends of the loaded set of articles that includes an element, such as a button, that lets the user request more articles to be loaded.

In addition to providing a brief label, authors MAY apply aria-describedby to article elements in a feed to suggest to screen readers which elements to speak after the label when users navigate by article. Screen readers MAY provide users with a way to quickly scan feed content by speaking both the label and accessible description when navigating by article, enabling the user to ignore repetitive or less important elements, such as embedded interaction widgets, that the author has left out of the description.

Authors SHOULD provide keyboard commands for moving focus among articles in a feed so users who do not utilize an assistive technology that provides article navigation features can use the keyboard to navigate the feed.

If the number of articles available in a feed supply is static, authors MAY specify aria-setsize on article elements in that feed. However, if the total number is extremely large, indefinite, or changes often, authors MAY set aria-setsize to -1 to communicate the unknown size of the set.

See the ARIA Authoring Practices Guide for additional details on implementing a feed design pattern.

A perceivable section of content that typically contains a graphical document, images, media player, code snippets, or example text. The parts of a figure MAY be user-navigable.

Authors SHOULD provide a reference to the figure from the main text, but the figure need not be displayed at the same location as the referencing element. Authors MAY provide a figure a caption which can include its name, descriptive text, or both. If a caption is provided, and it serves as a description to the contents of the figure, authors SHOULD associate it to the figure element using aria-details.

Authors MAY provide a figure an accessible name using aria-label or use aria-labelledby to reference other text in the page to serve as the element's label and accessible name.

Please refer to the caption role for more information on how to associate a figure with its caption.

Assistive technologies SHOULD enable users to quickly navigate to figures. User agents MAY enable users to quickly navigate to figures.

A landmark region that contains a collection of items and objects that, as a whole, combine to create a form. See related search.

A form can contain a mix of host language form controls, scripted controls, and hyperlinks. Authors are reminded to use native host language semantics to create form controls whenever possible. If the purpose of a form is to submit search criteria, authors SHOULD use the search role instead of the generic form role.

Authors SHOULD give each element with role form a brief label that describes the purpose of the form. Authors SHOULD reference a visible label with aria-labelledby if a visible label is present. Authors SHOULD include the label inside of a heading whenever possible. The heading MAY be an instance of the standard host language heading element or an instance of an element with role heading.

If an author uses a script to submit a form based on a user action that would otherwise not trigger an onsubmit event (for example, a form submission triggered by the user changing a form element's value), the author SHOULD provide the user with advance notification of the behavior.

Assistive technologies SHOULD enable users to quickly navigate to elements with role form. User agents SHOULD treat elements with role form and an accessible name as navigational landmarks. User agents MAY enable users to quickly navigate to elements with role form.

A nameless container element that has no semantic meaning on its own.

The generic role is intended for use as the implicit role of generic elements in host languages (such as HTML div or span), so is primarily for implementors of user agents. Authors SHOULD NOT use this role in content. Authors MAY use presentation or none to remove implicit accessibility semantics, or a semantic container role such as group to semantically group descendants in a named container.

Like an element with role presentation, an element with role generic can provide a limited number of accessible states and properties for its descendants, such as aria-live attributes.

However, unlike elements with role presentation, user agents expose generic elements in accessibility APIs when permitted accessibility attributes have been specified. User agents MAY otherwise ignore generic elements if such permitted attributes have not been specified.

A composite widget containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys.

The grid role does not imply a specific visual, e.g., tabular, presentation. It describes relationships among elements. It can be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application.

The cell elements of a grid have role gridcell. Authors MAY designate a cell as a row or column header by using either the rowheader or columnheader role in lieu of the gridcell role. Authors MUST ensure elements with role gridcell, columnheader, or rowheader are accessibility children of elements with role row, which are in turn are accessibility children of an element with role rowgroup, or grid.

To be keyboard accessible, authors SHOULD manage focus of descendants of a grid as described in Managing Focus. When a user is navigating the grid content with a keyboard, authors SHOULD set focus as follows:

• If a gridcell contains a single interactive widget that will not consume arrow key presses when it receives focus, such as a checkbox, button, or link, authors MAY set focus on the interactive element contained in that cell. This allows the contained widget to be directly operable.
• Otherwise, authors SHOULD ensure the element that receives focus is a gridcell, rowheader, or columnheader element.

Authors SHOULD provide a mechanism for changing to an interaction or edit mode that allows users to navigate and interact with content contained inside a focusable cell if that focusable cell contains any of the following:

• a widget that requires arrow keys to operate, e.g., a combobox or radiogroup
• multiple interactive elements
• editable content

For example, if a cell in a spreadsheet contains a combobox or editable text, the Enter key might be used to activate a cell interaction or editing mode when that cell has focus so the directional arrow keys can be used to operate the contained combobox or textbox. Depending on the implementation, pressing Enter again, Tab, Escape, or another key might switch the application back to the grid navigation mode.

Authors MAY use a gridcell to display the result of a formula, which could be editable by the user. In a spreadsheet application, for example, a gridcell might show a value calculated from a formula until the user activates the gridcell for editing when a textbox appears in the gridcell containing the formula in an editable state.

If aria-readonly is set on an element with role grid, user agents MUST propagate the value to all gridcell elements that are accessibility descendants of that grid and expose the value in the accessibility API. An author MAY override the propagated value of aria-readonly for an individual gridcell element.

In a grid that provides cell content editing functions, if the content of a focusable gridcell element is not editable, authors MAY set aria-readonly to true on the gridcell element. However, the value of aria-readonly, whether specified for a grid or individual cells, only indicates whether the content contained in cells is editable. It does not represent availability of functions for navigating or manipulating the grid itself.

An unspecified value for aria-readonly does not imply that a grid or a gridcell contains editable content. For example, if a grid presents a collection of elements that are not editable, such as a collection of link elements representing dates in a datepicker, it is not necessary for the author to specify a value for aria-readonly.

Authors MAY indicate that a focusable gridcell is selectable as the object of an action with the aria-selected attribute. If the grid allows multiple gridcells to be selected, the author SHOULD set aria-multiselectable to true on the element with role grid.

Since WAI-ARIA can augment an element of the host language, a grid can reuse the elements and attributes of a native table, such as an HTML table element. For example, if an author applies the grid role to an HTML table element, the author does not need to apply the row and gridcell roles to the descendant HTML tr and td elements because the user agent will automatically make the appropriate translations. When the author is reusing a native host language table element and needs a gridcell element to span multiple rows or columns, the author SHOULD apply the appropriate host language attributes instead of WAI-ARIA aria-rowspan or aria-colspan properties.

Authors SHOULD provide an accessible name for a grid, which can be done with the aria-label or aria-labelledby attribute. Authors SHOULD reference a visible label with aria-labelledby if a visible label is present for the grid.

See the ARIA Authoring Practices Guide for additional details on implementing grid design patterns.

A cell in a grid or treegrid.

A gridcell can be focusable, editable, and selectable. A gridcell can have relationships such as aria-controls to address the application of functional relationships.

If an author intends a gridcell to have a row header, column header, or both, and if the relevant headers cannot be determined from the DOM structure, authors SHOULD explicitly indicate which header cells are relevant to the gridcell by applying aria-describedby on the gridcell and referencing elements with role rowheader or columnheader.

In a treegrid, authors MAY define a gridcell as expandable by using the aria-expanded attribute. If the aria-expanded attribute is provided, it applies only to the individual cell. It is not a proxy for the container row, which also can be expanded. The main use case for providing this attribute on a gridcell is pivot table behavior.

Authors MUST ensure elements with role gridcell are accessibility children of an element with the role row.