aria-expanded - Accessibility | MDN (2024)

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>

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>

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.

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