noDisabledButton (HTML)

Summary

Diagnostic Category: lint/nursery/noDisabledButton
This rule has an unsafe fix.
The default severity of this rule is warning.

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "noDisabledButton": "error"
6
      }
7
    }
8
  }
9
}

Description

Discourages disabled on elements that act as buttons.

This is an opinionated usability rule, not a Web Content Accessibility Guidelines (WCAG) requirement. Native disabled controls are removed from sequential focus navigation and suppress activation. Keeping an unavailable button focusable can make it easier to discover with a keyboard or assistive technology.

The rule reports native button elements, input elements with the button, submit, reset, or image type, and built-in elements whose first valid explicit role is button. A native button is still reported when another role is assigned because disabled continues to change its native behavior.

The unsafe fix replaces disabled with aria-disabled. The ARIA attribute only exposes the disabled state to assistive technology. It does not prevent pointer or keyboard activation, change form submission or validation, omit values from submitted data, or add disabled styling. Implement those behaviors and provide disabled styling, including for forced-colors mode.

Examples

Invalid

1
<button disabled>Save</button>

code-block.html:1:9 lint/nursery/noDisabledButton  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Avoid the native disabled attribute on this button.
  
  > 1 │ <button disabled>Save</button>
      │         ^^^^^^^^
    2 │ 
  
  ℹ The native disabled state removes the button from sequential focus navigation, suppresses activation, and changes form behavior.
  
  ℹ aria-disabled only exposes the disabled state to assistive technology. It does not suppress pointer or keyboard activation, form submission or validation, or apply disabled styling. Implement those behaviors, including forced-colors styling.
  
  ℹ 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.
  
  ℹ Unsafe fix: Use aria-disabled instead.
  
    1 │ <button·aria-disabled="true">Save</button>
      │         +++++        +++++++

1
<div role="button" disabled>Save</div>

code-block.html:1:20 lint/nursery/noDisabledButton  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ The disabled attribute has no effect on this element.
  
  > 1 │ <div role="button" disabled>Save</div>
      │                    ^^^^^^^^
    2 │ 
  
  ℹ The button role changes accessibility semantics but does not add native button behavior.
  
  ℹ aria-disabled only exposes the disabled state to assistive technology. It does not suppress pointer or keyboard activation, form submission or validation, or apply disabled styling. Implement those behaviors, including forced-colors styling.
  
  ℹ 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.
  
  ℹ Unsafe fix: Use aria-disabled instead.
  
    1 │ <div·role="button"·aria-disabled="true">Save</div>
      │                    +++++        +++++++

Valid

1
<button aria-disabled="true">Save</button>