aria-expanded

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.

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>

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.

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.

<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>

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 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.

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.

Element.ariaExpanded

The ariaExpanded property, part of the Element interface, reflects the value of the aria-expanded attribute.

ElementInternals.ariaExpanded

The ariaExpanded property, part of the ElementInternals interface, reflects the value of the aria-expanded attribute.

Used in roles:

• application
• button
• checkbox
• combobox
• gridcell
• link
• listbox
• menuitem
• row
• rowheader
• tab
• treeitem

Inherits into roles:

• columnheader
• menuitemcheckbox
• menuitemradio
• rowheader
• switch

• aria-controls
• aria-owns
• aria-hidden
• HTML hidden attribute