HTML Guides for aria-expanded

The aria-expanded attribute communicates to assistive technologies whether a related grouping element (such as a dropdown menu, accordion panel, or collapsible section) is currently expanded or collapsed. It accepts only three valid values:

• "true" — the controlled element is expanded and visible.
• "false" — the controlled element is collapsed and hidden.
• "undefined" — the element has no expandable relationship (this is also the implicit default when the attribute is omitted entirely).

This validation error typically occurs when the attribute is accidentally set to a non-boolean value. A common mistake is writing aria-expanded="aria-expanded", which mimics the old HTML4 pattern for boolean attributes like checked="checked". However, aria-expanded is not a standard HTML boolean attribute — it is an ARIA state attribute that requires an explicit string value of "true" or "false".

Setting an invalid value means assistive technologies like screen readers cannot correctly interpret the state of the control. A screen reader user may not know whether a menu is open or closed, leading to a confusing and inaccessible experience. Browsers may also handle the invalid value unpredictably, potentially treating it as truthy or ignoring it altogether.

How to fix it

1. Identify the element with the invalid aria-expanded value.
2. Replace the value with "true" if the associated content is currently expanded, or "false" if it is collapsed.
3. If the button has no expand/collapse relationship at all, remove the aria-expanded attribute entirely.
4. Ensure that JavaScript toggling logic updates the attribute to "true" or "false" — never to any other string.

Examples

❌ Invalid: attribute set to a non-boolean string

<button aria-expanded="aria-expanded" aria-controls="menu">
  Toggle Menu
</button>
<ul id="menu">
  <li>Option 1</li>
  <li>Option 2</li>
</ul>

The value "aria-expanded" is not a recognized value and triggers the validation error.

✅ Fixed: attribute set to "false" (collapsed state)

<button aria-expanded="false" aria-controls="menu">
  Toggle Menu
</button>
<ul id="menu" hidden>
  <li>Option 1</li>
  <li>Option 2</li>
</ul>

✅ Fixed: attribute set to "true" (expanded state)

<button aria-expanded="true" aria-controls="menu">
  Toggle Menu
</button>
<ul id="menu">
  <li>Option 1</li>
  <li>Option 2</li>
</ul>

❌ Invalid: other common incorrect values

<!-- Using "yes" instead of "true" -->

<button aria-expanded="yes">Details</button>

<!-- Using "1" instead of "true" -->

<button aria-expanded="1">Details</button>

<!-- Empty value -->

<button aria-expanded="">Details</button>

All of these are invalid. The only accepted values are "true", "false", and "undefined".

✅ Toggling with JavaScript

When toggling aria-expanded dynamically, make sure the value is always set to the correct string:

<button aria-expanded="false" aria-controls="panel" onclick="togglePanel(this)">
  Show details
</button>
<div id="panel" hidden>
  <p>Additional details here.</p>
</div>

<script>
  function togglePanel(button) {
    const expanded = button.getAttribute("aria-expanded") === "true";
    button.setAttribute("aria-expanded", String(!expanded));
    const panel = document.getElementById(button.getAttribute("aria-controls"));
    panel.hidden = expanded;
  }
</script>

This ensures the attribute always toggles between "true" and "false", keeping the markup valid and the experience accessible for all users.

The aria-required attribute tells assistive technologies that a form field must be filled in before the form can be submitted. However, this attribute is only valid on elements that function as interactive widgets. A bare div has no implicit ARIA role, so assistive technologies have no context for what kind of input is expected. The validator flags this because an aria-required attribute on a generic div is effectively meaningless without additional ARIA attributes that define the element’s role and behavior.

This matters for several reasons:

• Accessibility: Screen readers and other assistive technologies rely on roles to understand how to present an element to users. Without a role, aria-required provides incomplete information.
• Standards compliance: The WAI-ARIA specification defines which attributes are allowed on which roles. Using aria-required without an established role violates these constraints.
• Browser behavior: Browsers may ignore or misinterpret ARIA attributes when they appear on elements that lack the proper role context.

How to fix it

Option 1: Use native semantic HTML (preferred)

Whenever possible, use native HTML form elements. They come with built-in accessibility semantics, keyboard interaction, and validation — no ARIA needed.

Replace a div with aria-required="true" with an appropriate form control using the native required attribute:

<input type="text" required>
<select required>
  <option value="">Choose one</option>
  <option value="1">Option 1</option>
</select>
<textarea required></textarea>

Option 2: Add an appropriate role attribute

When you must use a div as a custom widget (styled and enhanced with CSS and JavaScript), add the correct role attribute to give it semantic meaning. Choose the role that matches the widget’s actual behavior — don’t just pick one arbitrarily.

Common roles that support aria-required:

• combobox — a custom dropdown with text input
• listbox — a custom selection list
• radiogroup — a group of radio-like options
• spinbutton — a numeric stepper (also requires aria-valuemax, aria-valuemin, and aria-valuenow)
• textbox — a custom text input

Option 3: Add other qualifying ARIA attributes

For certain widgets like sliders or spinbuttons, you may need aria-valuemax, aria-valuemin, and aria-valuenow in addition to (or as part of) defining the role. These attributes inherently establish a widget context.

Examples

❌ Invalid: aria-required on a plain div

<div aria-required="true">
  <div data-value="One">1</div>
  <div data-value="Two">2</div>
  <div data-value="Three">3</div>
</div>

This triggers the validation error because the div has no role or other ARIA attributes to define what kind of widget it is.

✅ Fixed: Adding the appropriate role

<div aria-required="true" role="radiogroup" aria-label="Pick a number">
  <div role="radio" aria-checked="false" tabindex="0">1</div>
  <div role="radio" aria-checked="false" tabindex="0">2</div>
  <div role="radio" aria-checked="false" tabindex="0">3</div>
</div>

Adding role="radiogroup" gives the div a semantic identity. Note that child elements also need appropriate roles and attributes for the widget to be fully accessible.

✅ Fixed: Using native HTML instead

<fieldset>
  <legend>Pick a number</legend>
  <label><input type="radio" name="number" value="1" required> 1</label>
  <label><input type="radio" name="number" value="2"> 2</label>
  <label><input type="radio" name="number" value="3"> 3</label>
</fieldset>

This approach uses native radio buttons with the required attribute, eliminating the need for ARIA entirely. The browser handles accessibility, keyboard navigation, and form validation automatically.

✅ Fixed: A custom spinbutton with value attributes

<div role="spinbutton"
  aria-required="true"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-valuenow="50"
  aria-label="Quantity"
  tabindex="0">
  50
</div>

For a spinbutton role, you must also provide aria-valuemin, aria-valuemax, and aria-valuenow to fully describe the widget’s state.

The span element is a generic inline container with no inherent semantics. On its own, it carries no meaning for assistive technologies. When you add ARIA attributes like aria-expanded or aria-valuenow to a span, you are signaling that the element represents an interactive widget — but the validator (and assistive technologies) need more context. Many ARIA attributes are only permitted on elements that have certain roles, and some roles require a specific set of attributes to function correctly.

For example, aria-valuenow is designed for range widgets like sliders and progress bars. According to the WAI-ARIA specification, if you use aria-valuenow, the element must also have aria-valuemin, aria-valuemax, and a role such as progressbar, slider, meter, or scrollbar. Similarly, aria-expanded is meant for elements with roles like button, combobox, link, or treeitem. Placing these attributes on a bare span without the corresponding role violates the ARIA rules and triggers this validation error.

This matters for several reasons:

• Accessibility: Screen readers rely on the role to determine how to present a widget to users. Without it, ARIA state attributes become meaningless or confusing.
• Standards compliance: The HTML specification integrates ARIA rules, and validators enforce that ARIA attributes are used in valid combinations.
• Browser behavior: Browsers use the role to build the accessibility tree. A span with aria-valuenow but no role may be ignored or misrepresented to assistive technology users.

How to fix it

1. Add the correct role to the span, along with all attributes required by that role.
2. Use a semantic HTML element instead of a span when one exists (e.g., <progress> or <button>).
3. Remove unnecessary ARIA attributes if the span is purely decorative or the attributes were added by mistake.

If your span is purely visual (e.g., a decorative asterisk for required fields), don’t add state-related ARIA attributes to it. Instead, use aria-hidden="true" to hide it from assistive technologies, and place ARIA attributes on the actual form control.

Examples

Incorrect: aria-expanded on a span without a role

<span aria-expanded="false">Menu</span>

The validator reports the missing role because aria-expanded isn’t valid on a generic span.

Correct: Add a role (or use a button)

<span role="button" tabindex="0" aria-expanded="false">Menu</span>

Or, better yet, use a real button element:

<button aria-expanded="false">Menu</button>

Incorrect: aria-valuenow without the full set of range attributes and role

<span class="progress-indicator" aria-valuenow="50">50%</span>

Correct: Include the role and all required range attributes

<span role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
  50%
</span>

Or use the native <progress> element, which has built-in semantics:

<progress value="50" max="100">50%</progress>

Incorrect: aria-required on a decorative span

<label for="email">
  Email
  <span class="required" aria-required="true">*</span>
</label>
<input id="email" name="email" type="email">

The aria-required attribute belongs on the form control, not on the decorative asterisk.

Correct: Hide the decorative indicator and mark the input as required

<label for="email">
  Email
  <span class="required" aria-hidden="true">*</span>
</label>
<input id="email" name="email" type="email" aria-required="true">

If you also want screen readers to announce “required” as part of the label text, add visually hidden text:

<label for="email">
  Email
  <span aria-hidden="true">*</span>
  <span class="visually-hidden">required</span>
</label>
<input id="email" name="email" type="email" required>

The key takeaway: whenever you use ARIA state or property attributes on a span, make sure the element also has the correct role and all companion attributes required by that role. When a native HTML element already provides the semantics you need — such as <button>, <progress>, or <meter> — prefer it over a span with ARIA, as native elements are more robust and require less additional markup.