Skip to main content

Accessibility issue guide · ARIA attributes

Use valid ARIA only where HTML needs help.

Invalid or misspelled ARIA can be ignored by browsers and assistive technology, leaving a control without the intended name, role, state or relationship. ClearSite can flag machine-detectable errors; a person still needs to prove the interaction makes sense.

Scan a page for ARIA issues No signup. Then test the repaired control.

The first rule of ARIA

Do not add ARIA when native HTML already carries the meaning.

ARIA supplies roles, states and properties to accessibility APIs. It does not automatically add keyboard behaviour, focus management or a working interaction. A native <button> therefore starts with more dependable semantics and behaviour than a generic element labelled as a button.

WCAG 2.2 Name, Role, Value requires user-interface components to expose their name and role programmatically, with states, properties and values available to assistive technology and changes notified where users can alter them.

Primary guidance: W3C's ARIA in HTML requirements and Name, Role, Value explanation.

Controlled fixture · axe-core 4.11.1

The invented attribute failed. The specification-backed state passed.

We ran axe-core's aria-valid-attr rule against a button carrying aria-bogus. It returned one critical finding. Replacing that invented name with the valid aria-pressed="false" state returned zero violations for the rule.

Invalid · one critical finding

The name is not part of ARIA

<button aria-bogus="true">
  Save changes
</button>

Valid name · rule clear

The state has a defined meaning

<button aria-pressed="false">
  Save changes
</button>

This is a controlled fixture, not customer evidence or a conformance claim. A passing name check does not prove that the chosen state is appropriate or stays accurate. See Deque's aria-valid-attr rule documentation.

Four source-level repairs

Repair the semantics, not merely the scanner message.

Remove misspelled or invented names

Check the reported attribute against the WAI-ARIA specification. Delete attributes that do not exist rather than leaving browsers to ignore them.

<button aria-bogus="true">Save</button>
<!-- remove aria-bogus -->

Prefer native HTML

Use a real button, heading, input or landmark when HTML already provides the role and behaviour. Add ARIA only when the native element cannot express the needed state or relationship.

<button type="button">Save changes</button>

Use valid state values

A valid attribute name can still have an invalid value. Bind state to an allowed token and keep it synchronised with the interface.

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

Reference elements that exist

For relationships such as aria-labelledby and aria-describedby, make sure each referenced ID exists and describes the right control.

<p id="email-help">Use your work email.</p>
<input aria-describedby="email-help" />

From finding to verified fix

Trace the attribute to its source, then operate the result.

  1. 01

    Locate the rendered element

    Use the reported selector and HTML snippet to find the exact element carrying the invalid attribute.

  2. 02

    Trace the shared source

    Identify the component, theme template, app block or CMS field that emitted it. Repeated findings usually share one source.

  3. 03

    Choose native HTML first

    Before replacing one ARIA attribute with another, ask whether a semantic HTML element already provides the correct role and behaviour.

  4. 04

    Repair the name, value or relationship

    Remove the invalid attribute or replace it with a specification-backed state or property whose value stays accurate.

  5. 05

    Re-scan, then operate it

    Confirm the machine-detectable finding clears, then test the control with keyboard and assistive technology in its real journey.

What ClearSite can detect

Invalid ARIA names and other machine-detectable role, state, property or relationship problems reported by axe-core on the rendered page.

What a re-scan can prove

Whether the same automated ARIA finding clears after the component, theme or content source is repaired.

What still needs a person

Whether the semantics are appropriate, dynamic state stays truthful, keyboard behaviour works and assistive technology announces the control usefully.

Browse the website accessibility issue library, compare the form-label and accessible-name guide and link-purpose guide, or read the automated testing workflow and limits.

Find invalid ARIA. Repair the interface behind it.

Use automation to narrow the queue, prefer native HTML and finish with a real interaction review.

Run the free scan