Generally used in complex composite widgets or applications, the
document role can inform assistive technologies to switch context to a reading mode: The
document role tells assistive technologies with reading or browse modes to use the document mode to read the content contained within this element.
<div role="dialog"> ... <div id="InfoText" role="document" tabindex="0"> <p>Some informational text goes here.</p> </div> ... <button>Close</button> </div>
This example shows a dialog widget with some controls and a section with some informational text that the assistive technology user can read when tabbing to it.
By default, web pages are treated as documents; assistive technologies (AT) enter browse or read mode when entering a new web page. This mode can be altered through various roles, including the widget and application roles. The
document role brings the AT back into browse or read mode.
Generally placed within an application role or other interactive widget role, the
document role is used to indicate a section of a complex composit widget that an assistive technology user should read using its browse or virtual reading mode, if available.
Because ATs with reading mode default to that mode for all elements except for those with a widget or application role set, document role is only useful for focusable elements within a widget or application that should be read as static rich text. Adding
tabindex="0" to the element containing the text within a widget enables the screen reader user to press the Tab key to place focus on the document element and read the text with the screen reader's reading cursor.
Assistive technologies should switch context back to document mode, possibly intercepting from controls rewired for the parent's dynamic context, re-enabling the standard input events, such as Up or Down arrow keyboard events, to control the reading cursor.
In contrast to the
article role, the
document role does not have any relation to other elements with a document role, it merely has a relationship to the containing composit widget. An article can have associated articles.
Associated WAI-ARIA roles, states, and properties
- Include with a value of
falseif the document element is collapsible, to indicate if the document is currently expanded or collapsed. Other values include the default
undefinedwhich means the document is not collapsible.
- Used to make it focusable so the assistive technology user can tab to it and start reading right away.
The element should be made focusable by setting the
tabindex="0" attribute / value pair on it. This way, the user can tab to it, reading mode is invoked automatically, and the content can be read right away.
None, except as required by any attributes. For example, if the
document is collapsible, then the state and the value of
aria-expanded must be maintained.
An example is Gmail and the single conversation view. GMail is a web application. When in GMail, most user agent interactions are usurped by the application. However, when the Keyboard focus is set on the starting heading on a single conversation that contains the subject of the conversation, the screen reader user can use the reading mode commands to read through the messages, expand or collapse them, and manipulate them. Once focus returns to the message list either by activating the Back button or pressing an asociated keystroke, direct application interaction mode is invoked again, and the user can move to a different conversation in the list with the arrow keys.
Always make sure an item with the document role is focusable, by setting the
tabindex attribute with a value of 0. That will also include it in the tab order.
The document role is an easy way to indirectly control assistive technology behavior by unambiguously stating that this is content the user should read with standard screen reader commands.
|Accessible Rich Internet Applications (WAI-ARIA) 1.1
The definition of 'document' in that specification.
Screen reader support