New in ARIA 1.1Identifies the element that provides a detailed, extended description for the object. See related aria-describedby.
The aria-details attribute references a single element that provides more detailed information than would normally be provided by aria-describedby. It enables assistive technologies to make users aware of the availability of an extended description as well as navigate to it. Authors SHOULD ensure the element referenced by aria-details is visible to all users.
Unlike elements referenced by aria-describedby, the element referenced by aria-details is not used in either the Accessible Name Computation or the Accessible Description Computation as defined in the Accessible Name and Description specification [accname-aam-1.1]. Thus, the content of an element referenced by aria-details is not flattened to a string when presented to assistive technology users. This makes aria-details particularly useful when converting the information to a string would cause a loss of information or make the extended description more difficult to understand.
In some user agents, multiple reference relationships for descriptive information are not supported by the accessibility API. In such cases, if both aria-describedby and aria-details are provided on an element, aria-details takes precedence.
Screen Reader For aria-details
|Expectation||JAWS||Narrator||NVDA||Orca||TalkBack||VoiceOver (iOS)||VoiceOver (macOS)|
|MUST convey the presence of aria-details||supported||supported||supported||none||none||none||none||none||none||none||none|
|SHOULD allow the user to jump to the referenced element||none||none||none||none||none||none||none||none||none||none||none|
|SHOULD allow the user to jump back to the referencing element||none||none||none||none||none||none||none||none||none||none||none|
|MAY convey the boundaries of the details||supported||supported||supported||none||none||none||none||none||none||none||none|
A common use for aria-details is in digital publishing where an extended description needs to be conveyed in a book that requires structural markup or the embedding of other technology to provide illustrative content. The following example demonstrates this scenario.
Provision of an extended description
<img src="/pythagorean.jpg" alt="Pythagorean Theorem" aria-details="det"> <details id="det"> <summary> Example </summary> <p>The Pythagorean Theorem is a relationship in Euclidean Geometry between the three sides of a right triangle, where the square of the hypotenuse is the sum of the squares of the two opposing sides.</p> <p>The following drawing illustrates an application of the Pythagorean Theorem when used to construct a skateboard ramp.</p><object data="skatebd-ramp.svg" type="image/svg+xml"> </object> <p>In this example you will notice a skateboard with a base and vertical board whose width is the width of the ramp. To compute how long the ramp must be, simply calculate the base length, square it, sum it with the square of the height of the ramp, and take the square root of the sum.</p> </details>
Alternatively, aria-details may refer to a link to a web page having the extended description, as shown in the following example.
<img src="/pythagorean.jpg" alt="Pythagorean Theorem"> <p>See an <a href="http://foo.com/pt.html" id="det">Application of the Pythagorean Theorem</a>.</p>
Used in Roles
- All elements of the base markup
- ID reference
- Reference to the ID of another element in the same document
No HTML element equivalent.
The aria-details attribute takes an ID reference in the same manner as aria-describedby, and is meant to provide access to a more comprehensive description (when available) that may include additional active elements.
As such, aria-details takes precedence over aria-describedby if both are present on the same element. However, it is necessary for the user to navigate to the container referenced by aria-details to view and interact with the content of that description. This differs from aria-describedby, which is part of the naming calculation for the element that has focus, and where it is not necessary to move focus away from that element to hear the description. In contrast, aria-details is not included in the naming calculation for setting the Description property, and the user must instead navigate away from the focused element to view the detailed description.