Landmark Roles

The following roles are regions of the page intended as navigational landmarks. All of these roles inherit from the landmark base type and, with the exception of application, all are imported from the Role Attribute.

JAWS announces the type and text of ARIA landmarks, and provides navigation to the next and previous landmark on the page using the SEMICOLON and SHIFT+SEMICOLON quick navigation keys. In addition, pressing INSERT+CONTROL+SEMICOLON should bring up a list of landmarks. (source: Freedom Scientific)

Role Description Analogous To
application A region declared as a web application, as opposed to a web document.  
article A section of a page that consists of a composition that forms an independent part of a document, page, or site. <article>
banner A region that contains mostly site-oriented content, rather than page-specific content. <header>, <div id="header">
complementary 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. <aside>
contentinfo A large perceivable region that contains information about the parent document. <footer>
directory A list of references to members of a group, such as a static table of contents.  
document A region containing related information that is declared as document content, as opposed to a web application. <body>
form A landmark region that contains a collection of items and objects that, as a whole, combine to create a form. See related search <form>
log

A type of live region where new information is added in meaningful order and old information may disappear. See related marquee.

Note: Elements with the role log have an implicit aria-live value of polite.

 
main The main content of a document. <div id="content">
<main>
navigation A collection of navigational elements (usually links) for navigating the document or related documents. <nav>
note A section whose content is parenthetic or ancillary to the main content of the resource.  
region A large perceivable section of a web page or document, that the author feels is important enough to be included in a page summary or table of contents, for example, an area of the page containing live sporting event statistics. <div>, <frame>, <section>
search A landmark region that contains a collection of items and objects that, as a whole, combine to create a search facility. See related form.  
status

A container whose content is advisory information for the user but is not important enough to justify an alert, often but not necessarily presented as a status bar. See related alert.

Note: Elements with the role status have an implicit aria-live value of polite.

<output>
Back to top

Widget Roles

The following roles act as standalone user interface widgets or as part of larger, composite widgets.

Role Description Analogous To
alert

A message with important, and usually time-sensitive, information. See related alertdialog and status.

Note: Elements with the role alert have an implicit aria-live value of assertive.

alert()
alertdialog A type of dialog that contains an alert message, where initial focus goes to an element within the dialog. See related alert and dialog.  
button An input that allows for user-triggered actions when clicked or pressed. See related link. <button>, <input type="submit">, <input type="reset">, <input type="image">
checkbox A checkable input that has three possible values: true, false, or mixed <input type="checkbox">
columnheader A cell containing header information for a column. <th scope="col">
combobox A presentation of a select; usually similar to a textbox where users can type ahead to select an option, or type to enter arbitrary text as a new item in the list. See related listbox. <select>, HTML5<input> types which provide suggestions
definition A definition of a term or concept.  
dialog A dialog is an application window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. See related alertdialog.  
directory A list of references to members of a group, such as a static table of contents.  
grid A grid is an interactive control which contains cells of tabular data arranged in rows and columns, like a table. <table>
gridcell A cell in a grid or treegrid. <td>
group A set of user interface objects which are not intended to be included in a page summary or table of contents by assistive technologies. <fieldset>, <optgroup>
heading A heading for a section of the page. <h1>, <h2>, etc. (aria-level must be set appropriately)
img A container for a collection of elements that form an image. <img>
link An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See related button. <a href...>, <area>
list A group of non-interactive list items. See related listbox. <ul>, <ol>
listbox A widget that allows the user to select one or more items from a list of choices. See related combobox and list. <select>, <datalist> (when aria-multiselectable set to false on listbox)
listitem A single item in a list or directory. <li>
marquee

A type of live region where non-essential information changes frequently. See related log.

Note: Elements with the role marquee maintain the default aria-live value of off.

 
math Content that represents a mathematical expression.  
menu A type of widget that offers a list of choices to the user. <menu type="list">
menubar A presentation of menu that usually remains visible and is usually presented horizontally.  
menuitem An option in a group of choices contained by a menu or menubar.  
menuitemcheckbox A checkable menuitem that has three possible values: true, false, or mixed.  
menuitemradio A checkable menuitem in a group of menuitemradio roles, only one of which can be checked at a time.  
option A selectable item in a select list. <option>
presentation An element whose implicit native role semantics will not be mapped to the accessibility API. alt=""
progressbar

An element that displays the progress status for tasks that take a long time.

Note: Elements with the role progressbar have an implicit aria-readonly value of true.

<progress>
radio A checkable input in a group of radio roles, only one of which can be checked at a time. <input type="radio">
radiogroup A group of radio buttons.  
row A row of cells in a grid. <tr>
rowgroup A group containing one or more row elements in a grid. <thead>, <tfoot>, <tbody>
rowheader A cell containing header information for a row in a grid. <th scope="row">
scrollbar

A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.

Note: Elements with the role scrollbar have an implicit aria-orientation value of vertical.

 
separator A divider that separates and distinguishes sections of content or groups of menuitems. <hr>
slider A user input where the user selects a value from within a given range. <input type="range">
spinbutton A form of range that expects the user to select from among discrete choices. input element with a type attribute in the Number state
tab A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user.  
tablist A list of tab elements, which are references to tabpanel elements.  
tabpanel A container for the resources associated with a tab, where each tab is contained in a tablist.  
textbox Input that allows free-form text as its value. <input type="text"> (and other text-like inputs, such as 'password', 'email', etc.). <textarea>
timer A type of live region containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.  
toolbar A collection of commonly used function buttons represented in compact visual form. <menu type="toolbar">
tooltip A contextual popup that displays a description for an element.  
tree A type of list that may contain sub-level nested groups that can be collapsed and expanded.  
treegrid A grid whose rows can be expanded and collapsed in the same manner as for a tree.  
treeitem An option item of a tree. This is an element within a tree that may be expanded or collapsed if it contains a sub-level group of treeitems.  
Back to top

States & Properties

Potential Value Types

Value Description
true/false Value representing either true or false, with a default "false" value.
tristate Value representing true or false, with an intermediate "mixed" value. Default value is "false" unless otherwise specified.
true/false/undefined Value representing true or false, with a default "undefined" value indicating the state or property is not relevant.
ID reference Reference to the ID of another element in the same document
ID reference list A list of one or more ID references.
integer A numerical value without a fractional component.
number Any real numerical value.
string Unconstrained value type.
token token list
Back to top

Global States & Properties

Some states and properties are applicable to all host language elements regardless of whether a role is applied. The following global states and properties are supported by all roles and by all base markup elements. They are marked as such below.

Widget Attributes

Attribute Description Value Applicable Role(s) Analogous To
aria-autocomplete Indicates whether user input completion suggestions are provided.

token:

  • inline
  • list
  • both
  • none
  • combobox
  • textbox
 
aria-checked (state) Indicates the current "checked" state of checkboxes, radio buttons, and other widgets. See related aria-pressed and aria-selected.

tristate:

  • true
  • false
  • mixed
  • undefined
  • option
'checked' attribute on <command>, <input>
aria-disabled (state) (global) Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. See related aria-hidden and aria-readonly. true/false   <input disabled>
aria-expanded (state) Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. true/false/undefined
  • button
  • document
  • link
  • section
  • sectionhead
  • separator
  • window
'open' attribute on <details>
aria-haspopup (global) Indicates that the element has a popup context menu or sub-level menu. true/false   'contextmenu' attribute
aria-hidden (state) (global) Indicates that the element and all of its descendants are not visible or perceivable to any user as implemented by the author. See related aria-disabled. true/false   'hidden' value on type attribute for <input>
aria-invalid (state) (global) Indicates the entered value does not conform to the format expected by the application.

token

  • grammar
  • false
  • spelling
  • true
   
aria-label (global) Defines a string value that labels the current element. See related aria-labelledby. string   <label>, 'title' attribute, 'alt' attribute
aria-level Defines the hierarchical level of an element within a structure. integer
  • grid
  • heading
  • listitem
  • row
  • tablist
 
aria-multiline Indicates whether a text box accepts multiple lines of input or only a single line. true/false
  • textbox
 
aria-multiselectable Indicates that the user may select more than one item from the current selectable descendants. true/false
  • grid
  • listbox
  • tree
<select multiple>
aria-orientation Indicates whether the element and orientation is horizontal or vertical.

token

  • vertical
  • horizontal
  • scrollbar
  • separator
  • slider
 
aria-pressed (state) Indicates the current "pressed" state of toggle buttons. See related aria-checked and aria-selected.

tristate

  • true
  • false
  • mixed
  • undefined
  • button
 
aria-readonly Indicates that the element is not editable, but is otherwise operable. See related aria-disabled. true/false
  • grid
  • gridcell
  • textbox
<input readonly>
aria-required Indicates that user input is required on the element before a form may be submitted. true/false
  • combobox
  • gridcell
  • listbox
  • radiogroup
  • spinbutton
  • textbox
  • tree
'required' attribute on <input>, <select>, <textarea>
aria-selected (state) Indicates the current "selected" state of various widgets. See related aria-checked and aria-pressed. true/false/undefined
  • gridcell
  • option
  • row
  • tab
<option selected>
aria-sort Indicates if items in a table or grid are sorted in ascending or descending order.

token

  • ascending
  • descending
  • none
  • other
  • columnheader
  • rowheader
 
aria-valuemax Defines the maximum allowed value for a range widget. number
  • range
 
aria-valuemin Defines the minimum allowed value for a range widget. number
  • range
 
aria-valuenow Defines the current value for a range widget. See related aria-valuetext. number
  • range
 
aria-valuetext Defines the human readable text alternative of aria-valuenow for a range widget. string
  • range
 
Back to top

Live Region Attributes

Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus may be elsewhere. These regions are not always updated as result of a user interaction. This practices has become common place with the growing use of Ajax. Examples of live regions are a chat log, stock ticker, or a sport scoring section that updates periodically to reflect game statistics. Since these asynchronous areas are expected to update outside the user's area of focus, assistive technologies such as screen readers have either been unaware of their existence or unable to process them for the user. WAI-ARIA has provided a collection of properties that allow the author to identify these live regions and how to process them: aria-live, aria-relevant, aria-atomic, and aria-busy.

Attribute Description Value Applicable Role(s)
aria-atomic (global) Indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute. See related aria-relevant. true/false  
aria-busy (state) (global) Indicates whether an element, and its subtree, are currently being updated true/false  
aria-live (global) Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

token

  • off
  • polite
  • assertive
 
aria-relevant (global) Indicates what user agent change notifications (additions, removals, etc.) assistive technologies will receive within a live region. See related aria-atomic.

token list

  • additions
  • removals
  • text
  • all
  • additions text
 
Back to top

Drag and Drop Attributes

Attribute Description Value Applicable Role(s)
aria-dropeffect (global) Indicates what functions can be performed when the dragged object is released on the drop target. This allows assistive technologies to convey the possible drag options available to users, including whether a pop-up menu of choices is provided by the application. Typically, drop effect functions can only be provided once an object has been grabbed for a drag operation as the drop effect functions available are dependent on the object being dragged.

token list:

  • copy
  • move
  • link
  • execute
  • popup
  • none
 
aria-grabbed (state) (global) Indicates an element's "grabbed" state in a drag-and-drop operation. true/false/undefined  
Back to top

Relationship Attributes

Attribute Description Value Applicable Role(s) Analogous To
aria-activedescendant Identifies the currently active descendant of a composite widget. Used to deal with multiple focusable children, ie. in a tree menu ID Reference
  • composite
  • group
  • textbox
 
aria-controls (global) Identifies the element (or elements) whose contents or presence are controlled by the current element. See related aria-owns. Announced for form controls ID Reference List    
aria-describedby (global) Identifies the element (or elements) that describes the object. See related aria-labelledby. ID Reference List  
  • <label>
  • <th>
aria-flowto (global) Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. ID Reference List    
aria-labelledby (global) Identifies the element (or elements) that labels the current element. See related aria-label and aria-describedby. ID Reference List    
aria-owns (global) Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship. See related aria-controls. ID Reference List    
aria-posinset Defines an element's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. See related aria-setsize. integer    
aria-setsize Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. See related aria-posinset. integer
  • listitem
  • option
 
Back to top