html-eslint
no-aria-hidden-on-focusable
This rule disallows the use of aria-hidden="true" on focusable elements.
Why?
The aria-hidden="true" attribute is used to hide purely decorative content from screen reader users. When this attribute is applied to focusable elements (elements that can receive keyboard focus), it creates a confusing experience for screen reader users because:
- The element is still reachable via keyboard navigation
- But the screen reader won't announce it when focused
- This can lead to a situation where users can focus on an element but don't know what it is
This creates an inconsistent and potentially confusing user experience for people relying on screen readers.
How to use
.eslintrc.js
module.exports = {
rules: {
"@html-eslint/no-aria-hidden-on-focusable": "error",
},
};
Rule Details
This rule considers an element focusable if any of these conditions are met:
- It has a
tabindexattribute with a value other than-1 - It has a
contenteditableattribute that is empty,"true", or"plaintext-only" - It is one of the inherently focusable elements (like
button,input, etc.) - It is an
<a>element with anhrefattribute - It is an
<audio>or<video>element with acontrolsattribute
Examples of incorrect code for this rule:
<div aria-hidden="true" tabindex="0"></div>
<input aria-hidden="true">
<a href="/" aria-hidden="true"></a>
<button aria-hidden="true"></button>
<textarea aria-hidden="true"></textarea>
<div aria-hidden="true" contenteditable></div>
<div aria-hidden="true" contenteditable="true"></div>
<summary aria-hidden="true"></summary>
Examples of correct code for this rule:
<div aria-hidden="true"></div>
<img aria-hidden="true">
<a aria-hidden="false" href="#"></a>
<button aria-hidden="true" tabindex="-1"></button>
<a href="/"></a>
<div aria-hidden="true"><a href="#"></a></div>
<div aria-hidden="true" contenteditable="false"></div>