document
Characteristics
Superclass Role:
- structure
Subclass Roles:
- article
Related Concepts:
- Device Independence Delivery Unit
Supported States and Properties:
- aria-expanded (state)
Inherited States and Properties:
- aria-atomic
- aria-busy (state)
- aria-controls
- aria-describedby
- aria-disabled (state)
- aria-dropeffect
- aria-flowto
- aria-grabbed (state)
- aria-haspopup
- aria-hidden (state)
- aria-invalid (state)
- aria-label
- aria-labelledby
- aria-live
- aria-owns
- aria-relevant
Name From:
- author
Accessible Name Required:
- True
A region containing related information that is declared as document content, as opposed to a web application.
The document role is used when the web page contains a portion or entire page that is declared to be a document. Assistive technologies should find this information and change the browse mode to a more appropriate mode that helps to interact more comfortably.
An email form is an example of document role.
When the user navigates an element assigned the role of document, 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. The document role informs user agents of the need to augment browser keyboard support in order to allow users to visit and read any content within the document region. In contrast, additional commands are not necessary for screen reader users to read text within a region with the application role where, if coded in an accessible manner, all text will be semantically associated with focusable elements. An important trait of documents is that they have text which is not associated with widgets or groups thereof.
For example, an email application has a document and an application in it. The author would want to use typical application navigation mode to cycle through the list of emails, and much of this navigation would be defined by the application author. However, when reading an email message, the content will appear in a region with a document role in order to use browsing navigation.
Authors should provide a title or label for documents. Authors should use label text that is suitable for use as a navigation preview or table-of-contents entry for the page section. Content authors should provide the label through one of the following methods:
- If the document includes the entire contents of the web page, use the host language feature for title or label, such as the title element in both HTML and SVG. This has the effect of labeling the entire document.
- Otherwise, provide a visible label referenced by the document using aria-labelledby.
Currently there is not much support by screen readers for document role in any of the browsers.
Microsoft Active Accessibility accRole Property:
- ROLE_SYSTEM_CLIENT
UI Automation ControlType Property:
- Document
UI Automation AriaRole Property:
- document