useControlLabel

JSX and TSX

Caution

This rule is part of the nursery group. This means that it is experimental and the behavior can change at any time.

Summary

• Rule available since: v2.5.9
• Diagnostic Category: lint/nursery/useControlLabel
• This rule doesn’t have a fix.
• The default severity of this rule is error.
• Sources:
  • Inspired from jsx-a11y/control-has-associated-label

How to configure

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useControlLabel": "error"
      }
    }
  }
}

Description

Enforce that interactive control elements have an accessible label.

A control with no accessible label is announced by assistive technology as an anonymous control (e.g. just “button”), leaving its purpose unclear. A label can come from text content anywhere inside the control, aria-label, aria-labelledby, or title attribute.

This rule checks native controls whose accessible name is expected to come from their own content or attributes (button, menuitem). Elements hidden from assistive technology with aria-hidden are skipped, as are elements that already require a text alternative under a dedicated rule (e.g. area, img, checked by useAltText).

The search through the content of a control is permissive: anything whose rendered output cannot be determined statically, such as an expression, a spread, or a custom component, is assumed to provide a label.

Examples

Invalid

<button />;

code-block.jsx:1:1 lint/nursery/useControlLabel ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ This control element has no accessible label.
  
  > 1 │ <button />;
      │ ^^^^^^^^^^
    2 │ 
  
  ℹ Assistive technology announces it as an anonymous control, so its purpose is unclear to screen-reader users.
  
  ℹ Add text content, or an aria-label, aria-labelledby, or title attribute.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

<button></button>;

code-block.jsx:1:1 lint/nursery/useControlLabel ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ This control element has no accessible label.
  
  > 1 │ <button></button>;
      │ ^^^^^^^^
    2 │ 
  
  ℹ Assistive technology announces it as an anonymous control, so its purpose is unclear to screen-reader users.
  
  ℹ Add text content, or an aria-label, aria-labelledby, or title attribute.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

An icon button whose content renders nothing announceable:

<button><i className="icon-save" /></button>;

code-block.jsx:1:1 lint/nursery/useControlLabel ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ This control element has no accessible label.
  
  > 1 │ <button><i className=“icon-save” /></button>;
      │ ^^^^^^^^
    2 │ 
  
  ℹ Assistive technology announces it as an anonymous control, so its purpose is unclear to screen-reader users.
  
  ℹ Add text content, or an aria-label, aria-labelledby, or title attribute.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

Valid

<button>Submit</button>;

<button aria-label="Close" />;

<button><Icon /><span>Delete</span></button>;

<button><img src="save.png" alt="Save" /></button>;

Accessibility guidelines

• WCAG 1.3.1
• WCAG 3.3.2
• WCAG 4.1.2

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code (Edit this Page)
• Test Cases

HTML

Caution

This rule is part of the nursery group. This means that it is experimental and the behavior can change at any time.

Summary

• Rule available since: v2.5.9
• Diagnostic Category: lint/nursery/useControlLabel
• This rule doesn’t have a fix.
• The default severity of this rule is error.
• Sources:
  • Inspired from jsx-a11y/control-has-associated-label

How to configure

biome.json

{
  "linter": {
    "rules": {
      "nursery": {
        "useControlLabel": "error"
      }
    }
  }
}

Description

Enforce that interactive control elements have an accessible label.

A control with no accessible label is announced by assistive technology as an anonymous control (e.g. just “button”), leaving its purpose unclear. A label can come from text content, aria-label, aria-labelledby, or title attribute.

This rule checks native controls whose accessible name is expected to come from their own content or attributes (button, menuitem). Elements hidden from assistive technology with aria-hidden are skipped, as are elements that already require a text alternative under a dedicated rule (e.g. area, img, checked by useAltText).

Note

In .html files, this rule matches element names case-insensitively (e.g., <BUTTON>, <Button>).

In component-based frameworks (Vue, Svelte, Astro), only lowercase element names are checked. PascalCase variants like <Button> are assumed to be custom components and are ignored.

Examples

Invalid

<button></button>

code-block.html:1:1 lint/nursery/useControlLabel ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ This control element has no accessible label.
  
  > 1 │ <button></button>
      │ ^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Assistive technology announces it as an anonymous control, so its purpose is unclear to screen-reader users.
  
  ℹ Add text content, or an aria-label, aria-labelledby, or title attribute.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

<button>   </button>

code-block.html:1:1 lint/nursery/useControlLabel ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ This control element has no accessible label.
  
  > 1 │ <button>   </button>
      │ ^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Assistive technology announces it as an anonymous control, so its purpose is unclear to screen-reader users.
  
  ℹ Add text content, or an aria-label, aria-labelledby, or title attribute.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  

Valid

<button>Submit</button>

<button aria-label="Close"></button>

<button><span>Delete</span></button>

Accessibility guidelines

• WCAG 1.3.1
• WCAG 3.3.2
• WCAG 4.1.2

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code (Edit this Page)
• Test Cases