useSemanticElements (HTML)

Summary

Rule available since: v2.5.0
Diagnostic Category: lint/a11y/useSemanticElements
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:
- Inspired from jsx-a11y/prefer-tag-over-role

How to configure

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

Description

Enforces using semantic DOM elements over the ARIA role property.

The role attribute is used to define the purpose of an element, but it should be used as a last resort. Using semantic elements like <button>, <nav> and others are more accessible and provide better semantics.

Examples

Invalid

1
<div role="checkbox"></div>

code-block.html:1:6 lint/a11y/useSemanticElements ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ The elements with this role can be changed to semantic elements.
  
  > 1 │ <div role="checkbox"></div>
      │      ^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ For examples and more information, see WAI-ARIA Roles
  
  ℹ Replace with one of these elements:
  
  - <input type="checkbox">

1
<div role="separator"></div>

code-block.html:1:6 lint/a11y/useSemanticElements ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ The elements with this role can be changed to semantic elements.
  
  > 1 │ <div role="separator"></div>
      │      ^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ For examples and more information, see WAI-ARIA Roles
  
  ℹ Replace with one of these elements:
  
  - <hr>

Valid

1
<input type="checkbox" />
2
<hr />
3
<div role="status"></div>

All elements with role="img" are ignored:

1
<div role="img" aria-label="That cat is so cute">
2
  <p>&#x1F408; &#x1F602;</p>
3
</div>

Semantic elements with a matching role are not flagged (see noRedundantRoles):

1
<nav role="navigation"></nav>
2
<footer role="contentinfo"></footer>