Disallow aria-label misuse

Rule ID:
aria-label-misuse
Category:
Accessibility
Standards:
  • WCAG 2.2 (A)
  • WCAG 2.1 (A)
  • WCAG 2.0 (A)

aria-label is used to set the label of an element when no native text is present or non-descriptive. The attribute can only be used on the following elements:

Additionally, this rule ignores elements which explicitly declare an aria-label attribute. See the section on custom components below.

Rule details

Examples of incorrect code for this rule:

<input type="hidden" aria-label="foobar">
error: "aria-label" cannot be used on this element (aria-label-misuse) at inline:1:22:
> 1 | <input type="hidden" aria-label="foobar">
    |                      ^^^^^^^^^^


1 error found.

Examples of correct code for this rule:

<input type="text" aria-label="foobar">

Other namable elements

While some other elements (such as <h1>) allows naming with aria-label it is generally recommended to avoid it:

The ARIA Authoring Practices Guide (APG) strongly recommends to avoid such usage.

To allow aria-label on any element which allows naming see the [allowAnyNamable][#allow-any-namable] option below.

Custom components

When using custom components and you expect consumers to set aria-label on your component you need to explicitly declare the aria-label attribute:

import { defineMetadata } from "html-validate";

export default defineMetadata({
  "awesome-component": {
    attributes: {
      "aria-label": {},
    },
  },
});

The mere presence of aria-label declaration ensures this rule will allow aria-label to be specified.

Options

This rule takes an optional object:

{
  "allowAnyNamable": false
}

allowAnyNamable

By default this rule disallows aria-label on elements which allows naming but for which it is not recommended to do so.

With this option enabled the following is valid despite not recommended:

<h1 aria-label="Lorem ipsum">dolor sit amet</h1>

This option is disabled by default and html-validate:recommended but enabled by html-validate:standard.

Version history