aria-expanded
The aria-expanded
attribute is set on an element to indicate if a control is expanded or collapsed, and whether or not the controlled elements are displayed or hidden.
Description
There are several widgets that can be expanded and collapsed, including menus, dialogs, and accordion panels. Each of these objects, in turn, has an interactive element that controls their opening and closing. The aria-expanded
attribute is applied to this focusable, interactive control that toggles the visibility of the object.
For example, aria-expanded
is applied to the parent item in a DOM tree to indicate whether its child branch is shown. The parent controls the visibility of the associated child branch, as well.
There are two declarations that can be applied to objects that control the visibility of another object: aria-controls
, or aria-owns
combined with aria-expanded
. The aria-controls
and aria-owns
indicate the relationship between the controlling element and the controlled element. The aria-expanded
indicates to assistive technology whether the controlled element is expanded or collapsed.
Use the aria-owns
property on the elements that own expandable grouping containers. If the expandable and collapsible grouping container is not owned by the element that has the aria-expanded
attribute, use the aria-controls
property to reference the grouping container instead.
Buttons
A button that opens a widget should have aria-controls
set to the id
of the expandable widget and aria-expanded
set to the current state of the widget.
html
<button aria-expanded="false" aria-controls="widget1">Show widget</button>
When the widget is visible, the controlling object relays that information via having aria-expanded="true"
set on it. The accessible name of the controlling object should reflect this change.
html
<button aria-expanded="true" aria-controls="widget1">Hide widget</button>
Menu
When a menu
is displayed, the button object that toggles the visibility of that menu has aria-expanded="true"
set. When the menu is hidden, aria-expanded can be omitted. If specified when the menu is hidden, it should be set as aria-expanded="false"
. When a child menu is not visible, its parent menuitem
has aria-expanded
. It should be set to true
when the child menu is visible.
Combobox
By default, some roles are hidden or collapsed and other roles are open or expanded by default. Elements with role combobox
have a default value for aria-expanded
of false
. When a combobox popup is not visible, the element with role combobox
has aria-expanded
set to false
. This is the default state. When the popup element is visible, aria-expanded
should be set to true
.
html
<label for="username">Username</label>
<input id="username" name="username" aria-describedby="username-desc" />
<button
aria-expanded="false"
aria-controls="username-desc"
aria-label="Help about username"
type="button">
<span aria-hidden="true">?</span>
</button>
<p id="username-desc" hidden>
Your username is the name that you use to log in to this service.
</p>
Note: The presence of the aria-expanded
attribute indicates control. Avoid including it on elements that do not control the expanded state of other elements.
Treeitems
Each element with role treeitem
that serves as a parent node has aria-expanded="false"
when the node is in a closed state and aria-expanded="true"
when the node is in an open state. End nodes, nodes with no descendant nodes, should not have the aria-expanded
attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent nodes.
Rows
A parent row in a treegrid
is a row that can be expanded or collapsed to show or hide a set of child rows in a table or grid. Each parent row has the aria-expanded
state set on either the row element or on a cell contained in the row. When the child rows are hidden, aria-expanded="false"
is set. aria-expanded="true"
is set when the child rows are displayed. Rows that do not control the display of child rows should not include the aria-expanded
attribute at all because including the attribute defines the rows as parent rows.
Values
false
-
The grouping element this element owns or controls is collapsed.
true
-
The grouping element this element owns or controls is expanded.
undefined
(default)-
The element does not own or control a grouping element that is expandable.
ARIAMixin API
Element.ariaExpanded
-
The
ariaExpanded
property, part of theElement
interface, reflects the value of thearia-expanded
attribute. ElementInternals.ariaExpanded
-
The
ariaExpanded
property, part of theElementInternals
interface, reflects the value of thearia-expanded
attribute.
Associated roles
Used in roles:
Inherits into roles:
Specifications
Specification |
---|
Accessible Rich Internet Applications (WAI-ARIA) # aria-expanded |
See Also
aria-controls
aria-owns
aria-hidden
- HTML
hidden
attribute