aria-expanded attribute is set on an element to indicate if a control is expanded or collapsed, and whether or not its child elements are displayed or hidden.
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.
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-owns combined with
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.
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.
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.
<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.
<button aria-expanded="true" aria-controls="widget1">Hide widget</button>
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
aria-expanded. It should be set to
true when the child menu is visible.
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
false. When a combobox popup is not visible, the element with role
aria-expanded set to
false. This is the default state. When the popup element is visible,
aria-expanded should be set to
<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.
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.
A parent row 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.
The grouping element this element owns or controls is collapsed.
The grouping element this element owns or controls is expanded.
The element does not own or control a grouping element that is expandable.
Used in roles:
Inherits into roles:
|Accessible Rich Internet Applications (WAI-ARIA) 1.1
The definition of 'ARIA: aria-expanded Attribute' in that specification.