useAltText

JSX and TSX

Summary

• Rule available since: v1.0.0
• Diagnostic Category: lint/a11y/useAltText
• This rule is recommended, meaning it is enabled by default.
• This rule doesn’t have a fix.
• The default severity of this rule is error.
• Sources:
  • Same as jsx-a11y/alt-text

How to configure

biome.json

{
  "linter": {
    "rules": {
      "a11y": {
        "useAltText": "error"
      }
    }
  }
}

Description

Enforce that all elements that require alternative text have meaningful information to relay back to the end user.

This is a critical component of accessibility for screen reader users in order for them to understand the content’s purpose on the page. This rule checks for alternative text on the following elements: <img>, <area>, <input type="image">, and <object>.

Examples

Invalid

<img src="image.png" />

code-block.jsx:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label or aria-labelledby attribute
  
  > 1 │ <img src=“image.png” />
      │ ^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content’s purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.
  

<input type="image" src="image.png" />

code-block.jsx:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label or aria-labelledby attribute
  
  > 1 │ <input type=“image” src=“image.png” />
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content’s purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.
  

Valid

<img src="image.png" alt="image alt" />

<input type="image" src="image.png" alt="alt text" />

<input type="image" src="image.png" aria-label="alt text" />

<input type="image" src="image.png" aria-labelledby="someId" />

Accessibility guidelines

• WCAG 1.1.1

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code
• Test Cases

HTML

Summary

• Rule available since: v2.4.0
• Diagnostic Category: lint/a11y/useAltText
• This rule is recommended, meaning it is enabled by default.
• This rule doesn’t have a fix.
• The default severity of this rule is error.
• Sources:
  • Same as jsx-a11y/alt-text
  • Same as @html-eslint/require-img-alt

How to configure

biome.json

{
  "linter": {
    "rules": {
      "a11y": {
        "useAltText": "error"
      }
    }
  }
}

Description

Enforce that all elements that require alternative text have meaningful information to relay back to the end user.

This is a critical component of accessibility for screen reader users in order for them to understand the content’s purpose on the page. By default, this rule checks for alternative text on the following elements: <img>, <area>, <input type="image">, and <object>.

Note

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

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

Examples

Invalid

<img src="image.png" />

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label, or aria-labelledby attribute.
  
  > 1 │ <img src=“image.png” />
      │ ^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content’s purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.
  

<input type="image" src="image.png" />

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label, or aria-labelledby attribute.
  
  > 1 │ <input type=“image” src=“image.png” />
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content’s purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.
  

<area href="foo" />

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label, or aria-labelledby attribute.
  
  > 1 │ <area href=“foo” />
      │ ^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content’s purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.
  

<object data="foo"></object>

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the title, aria-label, or aria-labelledby attribute.
  
  > 1 │ <object data=“foo”></object>
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content’s purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.
  

Valid

<img src="image.png" alt="A beautiful landscape" />

<input type="image" src="image.png" alt="Submit" />

<img src="image.png" aria-label="A beautiful landscape" />

<img src="image.png" aria-labelledby="image-description" />

<object data="foo" title="Embedded content"></object>

<!-- Decorative images can be hidden from assistive technologies -->
<img src="decorative.png" alt="" />

<img src="decorative.png" aria-hidden="true" />

Accessibility guidelines

• WCAG 1.1.1

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code
• Test Cases