accessible-emoji
Enforce emojis are wrapped in <span>
and provide screenreader access.
Ensures emojis are accessible to screen reader users by enforcing that emojis are contained within a <span>
element with appropriate aria
attributes, making web content more inclusive for visually impaired users.
Promotes the use of the role="img"
attribute alongside aria-label
or aria-labelledby
for emojis, which provides semantic meaning and a textual alternative, crucial for understanding the content’s context in screen reader scenarios.
Prevents the incorrect assumption that emojis are universally understood or visually accessible, recognizing the need for explicit descriptive text for emojis to convey the intended message or emotion in a text alternative form.
Encourages best practices for accessible web development specifically tailored for emoji usage in JSX, ensuring that decorative emojis are marked as such (not requiring screen reader access) while informative emojis are made accessible.
alt-text
Enforce all elements that require alternative text have meaningful information to relay back to end user.
This rule ensures that images and other media elements in JSX, such as <img>
, <object>
, <area>
, <input type="image">
, and custom components simulating these behaviors, have alternative text, enhancing web accessibility for users relying on screen readers to understand the content. Non-text content must have text alternatives that present the equivalent information to ensure that it can be accessed by people with various disabilities.
It helps in identifying missing alt attributes on media elements which is crucial for SEO as search engines use the alt attributes to understand and index an image’s content. Without alt text, the chances of images being found in search results diminish.
The rule promotes best practices in web development by enforcing the inclusion of meaningful alternative text rather than allowing empty or generic descriptions that do not serve a purpose, thereby improving the user experience for those utilizing assistive technologies.
By customizing the elements and their custom components to be validated through options, it offers flexibility and ensures the rule’s relevance across different projects with varying requirements, making it a versatile tool in maintaining accessibility standards.
anchor-ambiguous-text
Enforce <a>
text to not exactly match “click here”, “here”, “link”, or “a link”.
Improves accessibility: By enforcing specific, context-rich text for <a>
elements rather than generic phrases like “click here,” the rule helps ensure that users, especially those using screen readers, have a clearer understanding of the link’s destination. This makes navigation and comprehension of web content more accessible.
Enhances user experience: Links with descriptive text provide a better user experience by supplying more information on what to expect before clicking. This clarity can reduce user frustration and increase engagement with the website content.
Increases SEO performance: Search engines use link text to understand the content of the linked page, so descriptive links contribute to better SEO. Ambiguous link text, on the other hand, might be missed or undervalued by search engines, potentially harming the site’s search ranking.
Encourages best coding practices: The rule promotes attention to detail and thoughtful web design by requiring developers to consider the purpose and destination of each link. This mindfulness can carry over into other aspects of coding and design, leading to higher overall quality in web development projects.
anchor-has-content
Enforce all anchors to contain accessible content.
<a>
) elements in JSX have accessible content, which is critical for users who rely on screen readers to navigate content on the web. Without accessible content, these users may encounter anchor elements that provide no context or indication of their function or destination.title
, aria-label
) that can describe the purpose or destination of the link to assistive technologies. This caters to a variety of use cases, including those where visual design constraints might discourage visible text.<a>
tag, the rule acknowledges and adapts to the common practice in modern web development frameworks and libraries (like React) of creating reusable component libraries. This ensures that accessibility considerations are extended to these custom components as well.anchor-is-valid
Enforce all anchors are valid, navigable elements.
This rule specifically addresses the distinction between hyperlinks and buttons, encouraging correct semantic HTML by guiding developers to use links (<a>
tags) only for navigation purposes and buttons for clickable actions. This distinction is crucial for accessibility as it helps screen readers and other assistive technologies interpret the purpose of elements correctly.
It includes validation against common pitfalls, such as using anchors without a valid href
attribute or improperly using JavaScript URLs. These practices can undermine the navigability and security of a web application, leading to a poor user experience, especially for those relying on assistive technologies.
By recognizing the usage of the JSX spread operator and ensuring that it does not falsely report errors when props are correctly spread across an anchor element, the rule demonstrates consideration for React’s component-based architecture, ensuring that developers do not have to compromise on code reusability and readability to adhere to accessibility standards.
The rule’s configurable aspects (noHref
, preferButton
, invalidHref
) allow teams to tailor the rule to their specific project needs, making it a versatile tool for maintaining both code quality and accessibility standards. This flexibility ensures that the rule can adapt to various coding styles and project requirements without enforcing overly strict guidelines that might not fit every scenario.
aria-activedescendant-has-tabindex
Enforce elements with aria-activedescendant are tabbable.
Ensures that elements with the aria-activedescendant
attribute are also interactive or focusable by requiring a tabIndex
. This is crucial because aria-activedescendant
is used to manage focus among child elements when the container receives focus. Without tabIndex
, keyboard users might not be able to interact with these elements as intended.
Improves accessibility by making elements with aria-activedescendant
accessible to keyboard navigation. This rule enforces that such elements must be tabbable (by setting a valid tabIndex
), which is essential for users who rely on keyboard navigation to access content on the web.
Helps in aligning with WCAG (Web Content Accessibility Guidelines) and ARIA (Accessible Rich Internet Applications) best practices by enforcing correct use of ARIA attributes together with focusable elements. This alignment is important for creating web content that is accessible to people with disabilities.
Aids in avoiding common mistakes in accessibility implementation by automatically catching elements that have aria-activedescendant
but lack a tabIndex
. This preemptive checking saves developers time and ensures a smoother, more accessible user experience without needing extensive manual review or user feedback to identify these issues.
aria-props
Enforce all aria-*
props are valid.
aria-*
props are valid aids screen readers and assistive technologies in interpreting the web content correctly.aria-proptypes
Enforce ARIA state and property values are valid.
aria-checked
instead of Boolean), this rule aids developers in adhering to ARIA specifications and best practices, reducing the likelihood of accessibility issues caused by incorrect attribute values.aria-role
Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.
This rule ensures that ARIA roles are valid and not abstract, which directly contributes to making web content more accessible to users with disabilities. Specifically, by enforcing the use of valid, non-abstract ARIA roles, it helps screen readers and other assistive technologies provide meaningful interaction cues to users.
The rule includes an option (ignoreNonDOM
) to skip validation for non-DOM elements. This flexibility allows developers to focus on validating roles in contexts where it matters most, such as in actual rendered HTML, while avoiding unnecessary checks in situations where an element might not directly correlate to a DOM element, thus optimizing development efficiency without compromising on accessibility.
It allows for customization through allowedInvalidRoles
, where developers can specify exceptions. This makes the rule adaptable to unique project requirements or when integrating with libraries or frameworks that might use roles in non-standard ways but are still accessible. This adaptability ensures that teams can enforce accessibility standards while also accommodating valid exceptions specific to their project’s context.
The rule performs checks only if the attribute’s name is role
and its value isn’t undefined
or null
. This precision prevents false positives and ensures that developers are alerted only in cases where an invalid ARIA role could genuinely affect accessibility. It focuses on actual issues rather than potential syntactic anomalies, thereby streamlining the debugging process and ensuring that efforts are concentrated on making meaningful improvements to accessibility.
aria-unsupported-elements
Enforce that elements that do not support ARIA roles, states, and properties do not have those attributes.
This rule helps ensure accessibility by preventing the use of ARIA roles, states, and properties on HTML elements that do not support them, reducing confusion for users of assistive technologies. For instance, adding role="presentation"
to a <meta>
tag, which does not support ARIA roles, can mislead screen readers and other assistive devices.
It promotes best practices in web development by enforcing a cleaner separation of concerns, where ARIA attributes are used only where they are intended and supported, enhancing the overall quality of code and making it easier to maintain and debug.
By reporting the use of ARIA attributes on unsupported elements, it aids developers in catching potential accessibility issues early in the development process. This proactive approach can save time and resources that might otherwise be spent on revising code to address accessibility concerns identified at later stages.
The rule specifically targets a common misunderstanding among developers about how ARIA roles, states, and properties should be applied to HTML content. By providing clear feedback when such attributes are misapplied, it serves an educational purpose, increasing awareness and understanding of ARIA guidelines within the developer community.
autocomplete-valid
Enforce that autocomplete attributes are used correctly.
This ESLint rule ensures proper use of the autocomplete
attribute in JSX components, which directly contributes to improving the user experience by allowing browsers to predict the user’s input, thereby speeding up the form-filling process.
By enforcing correct autocomplete
values, the rule aids in enhancing form accessibility, making it easier for people with disabilities to fill out forms. Autocomplete hints assist in reducing the amount of typing required, which is particularly beneficial for users with motor disabilities.
The rule helps in maintaining security best practices by ensuring that fields expecting sensitive information, like passwords, are correctly marked. This prevents browsers from inappropriately storing and autofilling sensitive details, thereby safeguarding user data.
It fosters a standardized way of defining form inputs across the project or organization. By stipulating correct autocomplete
attributes, the rule ensures that developers follow a consistent pattern, reducing bugs related to incorrect form behavior and improving code maintainability.
click-events-have-key-events
Enforce a clickable non-interactive element has at least one keyboard event listener.
control-has-associated-label
Enforce that a control (an interactive element) has a text label.
heading-has-content
Enforce heading (h1
, h2
, etc) elements contain accessible content.
The rule specifically targets ensuring that headings (such as h1
, h2
, etc.) in JSX elements contain accessible content, which is critical for users who rely on screen readers to navigate web content. By enforcing this rule, developers are prompted to include meaningful text within headings, improving the site’s accessibility.
It includes flexibility for checking custom component types that act as headings, not just standard HTML heading elements. This is particularly useful in React applications where custom components are used extensively. By including an option for custom components, the rule can be adapted to various development practices, ensuring accessibility considerations are not overlooked in non-standard implementations.
The rule proactively prevents the common accessibility issue of empty headings, which can cause confusion for users navigating with screen readers. Empty headings can lead to an inconsistent and frustrating experience, as users might expect content that does not exist. This rule directly addresses and eliminates this potential barrier.
By leveraging the context.report
method when a violation is detected, it provides direct feedback to developers about where and why a violation occurs. This immediate feedback loop helps in educating developers about accessibility best practices and encourages the correction of issues at the source. The rule not only identifies the problem but guides towards a solution, thereby fostering an environment of continuous improvement and learning regarding accessibility.
html-has-lang
Enforce <html>
element has lang
prop.
lang
attribute in <html>
elements, which is crucial for screen readers to provide accurate language support, enhancing the experience for users who rely on assistive technologies.iframe-has-title
Enforce iframe elements have a title attribute.
img-redundant-alt
Enforce <img>
alt prop does not contain the word “image”, “picture”, or “photo”.
interactive-supports-focus
Enforce that elements with interactive handlers like onClick
must be focusable.
onClick
, must also be focusable. This is crucial because it allows users who rely on keyboard navigation to interact with all interactive elements.divs
used as buttons) to be explicitly made focusable through attributes like tabIndex
. This directly benefits users who use assistive technologies.div
with an onClick
handler should have an appropriate role (e.g., role="button"
) if it is acting as a button. This semantic clarity helps assistive technologies interpret and interact with web content effectively.label-has-associated-control
Enforce that a label
tag has a text label and an associated control.
input
, textarea
, etc.), either by nesting the control within the label or using the htmlFor
attribute. This practice improves form accessibility for users relying on assistive technologies to navigate and interact with your website or application.htmlFor
, nesting
, both
, or either
), giving developers control over how strict their accessibility checks are. This can be adjusted to match project-specific accessibility standards or to progressively improve accessibility in large codebases.label-has-for
Enforce that <label>
elements have the htmlFor
prop.
<label>
elements are properly associated with their corresponding input elements through the htmlFor
prop. This association is crucial for screen reader users to understand the form structure and interact with it effectively.htmlFor
prop is missing or improperly used, this rule helps to streamline the development process, reduce human error, and ensure that accessibility considerations are systematically integrated into the codebase from the very beginning.lang
Enforce lang attribute has a valid value.
Ensures Web Accessibility: The rule is designed to promote accessibility by enforcing the presence of a valid lang
attribute in JSX elements. This is crucial because the language attribute helps assistive technologies like screen readers pronounce text correctly, improving the experience for users with disabilities.
Promotes Internationalization: By enforcing a valid lang
attribute, this rule indirectly supports internationalization efforts. A correctly specified language tag enables browsers and search engines to properly classify and process the content, thereby improving global user reach and engagement.
Improves SEO: Search engines use the lang
attribute to offer language-specific search results. Pages with accurately defined lang
attributes are better indexed, which can lead to improved search engine visibility and rankings for content in the specified language.
Enhances Code Quality: By requiring a valid lang
attribute, the rule encourages developers to pay attention to important but often overlooked aspects of HTML element attributes. This focus on detail leads to overall better code quality and adherence to best practices in web development.
media-has-caption
Enforces that <audio>
and <video>
elements must have a <track>
for captions.
<audio>
and <video>
elements include captions for the deaf or hard of hearing, enhancing web inclusivity and complying with various accessibility standards and laws.<audio>
or <video>
elements are missing <track>
tags designated for captions, thus helping developers catch and resolve potential accessibility issues early in the development process.<track>
elements, this rule indirectly encourages content creators to provide translations, fostering an environment where content is accessible to non-native speakers or to audiences with different language preferences.mouse-events-have-key-events
Enforce that onMouseOver
/onMouseOut
are accompanied by onFocus
/onBlur
for keyboard-only users.
onMouseOver
and onMouseOut
have corresponding keyboard events onFocus
and onBlur
. This makes sure elements interactive with a mouse are also accessible through the keyboard.no-access-key
Enforce that the accessKey
prop is not used on any element to avoid complications with keyboard commands used by a screenreader.
Prevents using the accessKey
attribute which can interfere with screen reader shortcuts, ensuring that users relying on assistive technologies have a consistent and accessible experience when navigating web applications.
Encourages developers to find alternative, more universally accessible means to achieve the same functionality, such as ensuring tab navigability or using ARIA roles, thus promoting best practices in web accessibility.
Helps in maintaining a cleaner and more semantic HTML by avoiding attributes that are not widely supported or could lead to unpredictable behaviour across different screen readers and assistive technologies.
Facilitates codebases to be more aligned with accessibility guidelines like WCAG (Web Content Accessibility Guidelines), potentially improving a website’s legal compliance with accessibility standards and enhancing its usability for all users.
no-aria-hidden-on-focusable
no-autofocus
Enforce autoFocus prop is not used.
This ESLint rule helps in promoting accessible web development practices by discouraging the use of the autoFocus
prop on elements. The autoFocus prop can negatively impact users with disabilities, as it might lead to an unexpected change in the focus, making navigation confusing for screen reader users and those with cognitive disabilities.
By enforcing developers to not use the autoFocus
prop directly and instead consider alternative, more accessible solutions, such as conditionally focusing an element based on user actions or component states, it encourages a more thoughtful approach to setting focus that respects the user’s intention and control.
This rule includes an option to ignore non-DOM elements, acknowledging that not all elements using the autoFocus prop might have an impact on accessibility or be relevant. This distinction ensures that the rule is applied only where it can genuinely improve accessibility, avoiding unnecessary reports in cases where autoFocus usage does not affect the accessibility of web components.
The suggested fix using useRef
and useEffect
in React for focusing elements programmatically demonstrates an accessible alternative to autoFocus. It provides developers with a practical, accessible method to set focus when necessary, such as focusing on an input field when a form is shown, without automatically moving focus as soon as the component mounts. This approach offers a balance between usability and accessibility, ensuring that focus management is done in a user-friendly and A11Y-compliant manner.
no-distracting-elements
Enforce distracting elements are not used.
Enhances Accessibility: By discouraging the use of elements that can be distracting, such as <marquee>
or <blink>
, it makes web content more accessible to users with attention disorders or visual impairments, adhering to Web Content Accessibility Guidelines (WCAG).
Improves User Experience: Distracting elements can negatively affect the user’s ability to focus on the main content. By enforcing this rule, developers create a smoother, less disruptive web experience, which is beneficial for all users, but especially critical for maintaining the attention of those with cognitive limitations.
Ensures Modern Web Practices: The rule encourages the use of modern, standard-compliant HTML and CSS techniques for animations or highlighting important information instead of outdated and obsolete elements, leading to more maintainable and future-proof codebases.
Customizable Enforcement: Given that the rule allows for configuration through options, it provides flexibility. Teams can tailor the rule to suit their specific needs or accessibility standards, ensuring that enforcement aligns with their web development practices and objectives, thus fostering a more inclusive web environment without sacrificing brand or creative goals.
no-interactive-element-to-noninteractive-role
Interactive elements should not be assigned non-interactive roles.
no-noninteractive-element-interactions
Non-interactive elements should not be assigned mouse or keyboard event listeners.
<div>
s, do not have mouse or keyboard event listeners, pushing for the use of semantically correct interactive elements like <button>
.<div>
or <span>
which are not traditionally clickable do not perform interactive roles without proper roles and attributes.no-noninteractive-element-to-interactive-role
Non-interactive elements should not be assigned interactive roles.
<li>
tags, from being assigned interactive roles, such as button
, which can confuse assistive technologies and users about the element’s functionality.<button>
, rather than repurposing non-interactive elements through roles and event listeners, leading to cleaner and more maintainable code.no-noninteractive-tabindex
tabIndex
should only be declared on interactive elements.
tabIndex
are indeed interactive, as non-interactive elements with a focusable state can confuse users navigating a site with assistive technologies.tabIndex
, helping developers catch and correct potential mistakes that could lead to a poor user experience for people relying on keyboard navigation.<button>
over <div>
with a tabIndex
for clickable elements), which is a key principle of web accessibility.no-onchange
Enforce usage of onBlur
over onChange
on select menus for accessibility.
onBlur
instead of onChange
for select elements, which can prevent unexpected behavior for keyboard and screen reader users. This adaptation aims to enhance the interaction experience for users relying on assistive technologies.onChange
can cause issues in certain assistive technologies by triggering changes as soon as the selection is changed, which might not be the user’s intent. onBlur
, on the other hand, waits until the element loses focus, aligning actions more closely with user intentions.onChange
without a corresponding onBlur
handler on select elements, thereby aiding in the swift correction of accessibility flaws in existing and new codebases.no-redundant-roles
Enforce explicit role property is not the same as implicit/default role property on element.
The rule ensures that the code is cleaner by avoiding redundancy. In the example, explicitly setting the role of a <nav>
element to “navigation” is redundant since “navigation” is already its implicit role. By removing such redundancies, the code becomes easier to read and maintain.
It enforces best practices in accessibility. While it might seem harmless to reiterate the role of an element, doing so can potentially lead to confusion for developers who may not be as familiar with the implicit roles of HTML elements. This rule educates developers about these implicit roles, contributing to a more universally accessible web.
The rule can potentially highlight misunderstandings or misuses of the role attribute. For instance, if a developer explicitly sets a role that’s identical to the implicit role of an element, it might indicate a lack of understanding of ARIA roles or HTML semantics. Identifying these instances can serve as teaching moments.
It improves performance optimally. While the direct impact on performance might be minimal, any practice that reduces unnecessary attributes in the DOM can contribute to faster rendering. By enforcing the elimination of redundant roles, this rule helps keep the HTML output lean, which is especially beneficial for users on low-bandwidth connections or older devices.
no-static-element-interactions
Enforce that non-interactive, visible elements (such as <div>
) that have click handlers use the role attribute.
Ensures accessibility for users relying on assistive technologies: By enforcing non-interactive elements like <div>
with click handlers to have a role
attribute, it makes these elements perceivable and usable for users navigating via screen readers or other assistive devices.
Promotes semantic HTML: Even though certain elements are being used in an interactive manner, HTML5 might not always offer a semantic element that fits the use case. Adding roles to elements like <div>
used as buttons helps communicate the intended behavior semantically, improving code clarity and maintainability.
Helps maintain consistency in user interface design: By enforcing roles on elements that are interacted with, this rule assists in creating a consistent approach to how interactions are handled across the website or application. This consistency is crucial for user experience, making interactions predictable across different parts of the application.
Facilitates automated testing and quality assurance: By clearly marking interactive elements with roles, it becomes easier to target these elements in automated tests. This can improve the quality assurance process, ensuring that interactive elements are accessible and function as intended across updates and changes to the site or application.
prefer-tag-over-role
Enforces using semantic DOM elements over the ARIA role
property.
The rule focuses on enhancing accessibility by promoting the use of semantic HTML elements. Using appropriate tags (e.g., <button>
instead of <div role="button">
) helps users with assistive technologies understand and navigate the content more effectively.
It encourages developers to adhere to semantic HTML practices by automatically identifying instances where a non-semantic element is used with an ARIA role that has a semantically appropriate HTML counterpart. This direct mapping ensures that the solutions are not only accessible but also cleaner and more in line with web standards.
This rule aids in reducing the complexity of the codebase. By replacing elements with unnecessary roles with their semantic equivalents, the code becomes more straightforward and maintainable. This is because semantic HTML is inherently more descriptive and easier to understand than spans or divs with added roles and functionality.
Implementing this rule can improve the performance of web applications on assistive devices. Semantic HTML elements come with built-in accessibility features that are optimized for performance, unlike ARIA roles that might require additional processing. This can lead to a smoother and more efficient experience for users relying on screen readers and other assistive technologies.
role-has-required-aria-props
Enforce that elements with ARIA roles must have all required attributes for that role.
aria-checked
attribute in elements with role="checkbox"
.aria-checked="false"
to make the role of the element clear and operable.role-supports-aria-props
Enforce that elements with explicit or implicit roles defined contain only aria-*
properties supported by that role
.
aria-*
properties for their role, it prevents developers from mistakenly using ARIA attributes that are not applicable to the element’s role, which could otherwise lead to confusion for users of assistive technology.role
attribute) and implicit roles (determined by the element type and its context), which is crucial because it covers a wider range of scenarios, ensuring that even elements without an explicitly set role follow the ARIA properties guidelines.aria-*
properties for a given role by comparing the used properties against a set of supported properties for the detected role. This targeted approach helps in catching and mitigating common accessibility issues at the development stage, contributing to a more accessible web.scope
Enforce scope
prop is only used on <th>
elements.
scope
attribute is correctly applied to table headers (<th>
elements), which helps screen readers and other assistive technologies understand the structure of the data, improving the experience for users with disabilities.scope
attribute on elements other than <th>
, such as <td>
, which could lead to misleading information being presented to assistive technologies, thus avoiding confusion and making the content more accessible and semantically correct.scope
attribute, making it easier for developers to follow best practices in web development without having to remember specific accessibility guidelines, thus ensuring a higher quality of code.scope
attribute, this rule saves developer time and reduces the likelihood of accessibility defects being introduced during development, leading to a more efficient development process and reducing the need for extensive accessibility audits later on.tabindex-no-positive
Enforce tabIndex
value is not greater than zero.
tabIndex
values do not exceed zero is essential for creating a web navigation structure that is logical and predictable. Positive values can disrupt the natural order of keyboard navigation, leading to a confusing experience for users who rely on assistive technologies.tabIndex
of zero or negative, developers are encouraged to rely on the natural DOM order for keyboard navigation, which is generally more intuitive and accessible.tabIndex
means it specifically targets easily identifiable and correctable instances where the tabIndex
might be improperly set. This clarity can expedite the process of identifying and addressing accessibility issues related to focus management.tabIndex
for review, this ESLint rule can serve as an educational tool for developers, highlighting an often-overlooked aspect of accessible web design. As developers adjust their coding practices to comply with this rule, they inherently learn more about accessible web development principles.