Accessibility Rules

React Doctor includes 15 accessibility rules from the jsx-a11y plugin to help you build interfaces that work for everyone.

Why Accessibility Matters

15% of the world has some form of disability
Legal requirement in many jurisdictions (ADA, Section 508, WCAG)
Better UX for everyone (keyboard nav, screen readers, low vision)
SEO benefits from semantic HTML

Rules

alt-text

Severity: error
Rule ID: jsx-a11y/alt-textRequires alt attribute on <img> elements. Screen readers use alt text to describe images.Bad:

<img src="logo.png" />

Good:

<img src="logo.png" alt="Company logo" />

// Decorative images should have empty alt
<img src="divider.png" alt="" />

anchor-is-valid

Severity: warn
Rule ID: jsx-a11y/anchor-is-validEnsures <a> elements have valid href attributes. Links without hrefs should be buttons.Bad:

<a onClick={handleClick}>Click me</a>
<a href="#">Click me</a>

Good:

<button onClick={handleClick}>Click me</button>
<a href="/page">Go to page</a>

click-events-have-key-events

Severity: warn
Rule ID: jsx-a11y/click-events-have-key-eventsRequires keyboard event handlers alongside click handlers for accessibility.Bad:

<div onClick={handleClick}>Click me</div>

Good:

// Use semantic button instead
<button onClick={handleClick}>Click me</button>

// Or add keyboard handler
<div
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
  role="button"
  tabIndex={0}
>
  Click me
</div>

no-static-element-interactions

Severity: warn
Rule ID: jsx-a11y/no-static-element-interactionsPrevents adding click/keyboard handlers to non-interactive elements without proper ARIA roles.Bad:

<div onClick={handleClick}>Clickable</div>

Good:

<button onClick={handleClick}>Clickable</button>

// Or with role
<div role="button" tabIndex={0} onClick={handleClick}>Clickable</div>

no-noninteractive-element-interactions

Severity: warn
Rule ID: jsx-a11y/no-noninteractive-element-interactionsPrevents adding interactions to non-interactive elements like <li>, <article>, etc.Bad:

<li onClick={handleClick}>Item</li>

Good:

<li>
  <button onClick={handleClick}>Item</button>
</li>

role-has-required-aria-props

Severity: error
Rule ID: jsx-a11y/role-has-required-aria-propsEnsures ARIA roles have all required ARIA attributes.Bad:

<div role="checkbox" />

Good:

<div role="checkbox" aria-checked="false" />

no-autofocus

Severity: warn
Rule ID: jsx-a11y/no-autofocusDiscourages autoFocus as it can be disorienting for screen reader users.Bad:

<input autoFocus />

Good:

// Let users focus naturally, or use programmatic focus
const inputRef = useRef();
useEffect(() => {
  inputRef.current?.focus();
}, []);

heading-has-content

Severity: warn
Rule ID: jsx-a11y/heading-has-contentRequires heading elements to have content for screen readers.Bad:

<h1></h1>
<h2 />

Good:

<h1>Page Title</h1>
<h2>{dynamicTitle}</h2>

html-has-lang

Severity: warn
Rule ID: jsx-a11y/html-has-langRequires <html> element to have lang attribute for screen readers.Bad:

<html>

Good:

<html lang="en">

no-redundant-roles

Severity: warn
Rule ID: jsx-a11y/no-redundant-rolesPrevents specifying redundant ARIA roles that are implicit.Bad:

<button role="button">Click</button>
<nav role="navigation">...</nav>

Good:

<button>Click</button>
<nav>...</nav>

scope

Severity: warn
Rule ID: jsx-a11y/scopeEnsures scope attribute is only used on <th> elements in tables.Bad:

<td scope="col">Header</td>

Good:

<th scope="col">Header</th>

tabindex-no-positive

Severity: warn
Rule ID: jsx-a11y/tabindex-no-positivePrevents positive tabIndex values which disrupt natural tab order.Bad:

<div tabIndex={1}>First</div>
<div tabIndex={2}>Second</div>

Good:

<div tabIndex={0}>Focusable</div>
<div tabIndex={-1}>Not in tab order</div>

label-has-associated-control

Severity: warn
Rule ID: jsx-a11y/label-has-associated-controlRequires <label> elements to be associated with form controls.Bad:

<label>Email</label>
<input type="email" />

Good:

// htmlFor
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// Nested
<label>
  Email
  <input type="email" />
</label>

no-distracting-elements

Severity: error
Rule ID: jsx-a11y/no-distracting-elementsPrevents using distracting elements like <marquee> and <blink>.Bad:

<marquee>Scrolling text</marquee>
<blink>Blinking text</blink>

Good:

<div className="animate-slide">Scrolling text</div>

iframe-has-title

Severity: warn
Rule ID: jsx-a11y/iframe-has-titleRequires <iframe> elements to have a title attribute.Bad:

<iframe src="/embed" />

Good:

<iframe src="/embed" title="Embedded content" />

Accessibility Best Practices

Semantic HTML

Use the right element for the job:

// ✅ Semantic
<button onClick={handleClick}>Submit</button>
<nav><a href="/">Home</a></nav>
<main><article>Content</article></main>

// ❌ Non-semantic
<div onClick={handleClick}>Submit</div>
<div><div onClick={nav}>Home</div></div>
<div><div>Content</div></div>

Ensure all interactive elements are keyboard accessible:

Use semantic HTML (<button>, <a>, <input>)
Add tabIndex={0} for custom interactive elements
Handle Enter and Space keys for custom controls
Provide visible focus indicators

Screen Readers

Make content accessible to screen readers:

Use alt text for images
Label form inputs
Use ARIA labels when needed: aria-label, aria-labelledby
Provide aria-live regions for dynamic content
Use proper heading hierarchy (h1 → h2 → h3)

Color and Contrast

Maintain 4.5:1 contrast ratio for text
Don’t rely on color alone to convey information
Test with color blindness simulators

Testing Tools

axe DevTools - Browser extension
WAVE - Web accessibility evaluation tool
Lighthouse - Built into Chrome DevTools
NVDA - Free screen reader for Windows
VoiceOver - Built into macOS

Correctness Rules - Common React mistakes
Next.js Rules - Next.js-specific patterns

Get Started

Usage

Rules Reference

Guides

Examples

Why Accessibility Matters

Rules

Accessibility Best Practices

Semantic HTML

Keyboard Navigation

Screen Readers

Color and Contrast

Testing Tools

​Why Accessibility Matters

​Rules

​Accessibility Best Practices

​Semantic HTML

​Keyboard Navigation

​Screen Readers

​Color and Contrast

​Testing Tools

​Related Rules

Why Accessibility Matters

Rules

Accessibility Best Practices

Semantic HTML

Keyboard Navigation

Screen Readers

Color and Contrast

Testing Tools

Related Rules