Accessibility Checklist for React Applications

Building accessible React applications isn’t just about compliance. It’s about creating experiences that work for everyone, including people who rely on screen readers, keyboard navigation, or magnified displays. Accessibility, often shortened to a11y, should be part of your development workflow from the start. This checklist covers the essential areas you need to address.

Why Accessibility Matters in React

React renders dynamic interfaces that can easily break accessibility if you’re not careful. SPA routing, conditional rendering, and complex state changes can confuse assistive technologies. A structured checklist helps you catch issues early and maintain a high standard of usability.

Accessible apps also benefit search engine SEO and provide a better experience for all users. Many accessibility practices align with good UX principles. By following this checklist, you’ll build more robust and maintainable components.

Semantic HTML in React Components

Start by using the correct HTML elements for their intended purpose. Use <nav> for navigation, <main> for primary content, <button> for actions, and <a> for links. Avoid unnecessary <div> or <span> when native elements exist.

When creating custom components, ensure they render semantic markup. For example, a custom Button component should render a <button> element, not a <div> with an onClick handler. This preserves built-in keyboard and screen reader behavior.

Use headings (<h1> through <h6>) in a logical order to structure content. Don’t skip levels, and avoid using headings for styling alone. Screen reader users rely on heading structure to navigate pages efficiently.

One common mistake is using <div> for clickable cards or panels. Instead, consider using a <button> if it triggers an action, or wrap the entire card in an <a> if it navigates. If the card contains multiple actions, structure it with focusable elements inside.

Keyboard Navigation and Focus Management

All interactive elements must be reachable and operable via keyboard. Use the tab order consistently. Ensure that focus moves in a logical sequence as users tab through the page. Avoid tabindex values greater than 0.

Manage focus when content changes dynamically. For instance, after a modal opens, move focus to the modal’s first focusable element. When the modal closes, return focus to the triggering button. React’s useRef and lifecycle methods make this manageable.

Programmatic focus management: use element.focus() after state updates that add new navigation landmarks. For single-page app route changes, announce new content with aria-live regions or move focus to the top of the new view.

For dynamic lists, such as search results that update as you type, ensure the first result receives focus or is announced. Consider using a useEffect that runs when results change to focus the new list item.

Visible Focus Indicators

Never remove the default focus outline without providing a custom visible indicator. Use CSS like :focus-visible to show focus only when navigating by keyboard. Ensure the focus style has a contrast ratio of at least 3:1 against its background.

Design a focus ring that is noticeable but not overwhelming. A 2px solid outline with a 2px offset works well. Avoid using only color changes, as they may not be visible to users with low vision.

ARIA Roles, States, and Properties

ARIA (Accessible Rich Internet Applications) supplements native HTML semantics. Use it sparingly and correctly. The first rule of ARIA is not to use it if you can use a native HTML element that already has the needed semantics.

When you need ARIA, add roles like role="button" only if the element isn’t naturally a button. For dynamic content, use aria-live regions to announce updates. For example, a live region on a shopping cart icon can announce “Your cart has 3 items” when the count changes.

Manage ARIA attributes dynamically in React. Use state to toggle aria-expanded on accordion headers, aria-selected on tabs, and aria-hidden on off-screen panels. Ensure that ARIA states match the component’s visual state.

Be careful with aria-live regions. Use polite for non-critical updates and assertive only for urgent warnings. Overusing assertive can be disruptive. Also, set aria-atomic="true" if the entire region should be announced as a whole.

Color Contrast and Visual Design

Text and interactive elements must have sufficient color contrast. The WCAG 2.1 AA standard requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text (18px bold or 24px regular). Use tools like the WebAIM Contrast Checker to verify.

Don’t convey information through color alone. For example, form errors should include an icon or text label, not just a red border. Charts and graphs should use patterns or labels in addition to color.

Test your design under different color vision deficiencies. Simulators can show how your app looks to users with deuteranopia (red-green color blindness) or other conditions. Aim for clear differentiation without relying on hue.

For interactive elements like links, use both underline and color to distinguish them from surrounding text. Hover and focus states should also be distinguishable. A good practice is to ensure that the same information is available through text or icons.

Forms and Input Labels

Every form input must have an associated label. Use the <label> element with a htmlFor attribute matching the input’s id. Alternatively, wrap the input inside the label. For custom-styled inputs, use aria-label or aria-labelledby.

Provide clear error messages that are programmatically associated with the input using aria-describedby. For example, a required email field might have an error message like “Please enter a valid email address” linked via aria-describedby="email-error".

Group related inputs with <fieldset> and <legend>. This is especially useful for radio buttons, checkboxes, and address fields. The legend provides a label for the group, helping screen reader users understand the context.

For validation, use live regions to announce errors after submission. Avoid relying solely on visual cues. Also, ensure that error messages are concise and actionable, telling the user what to fix.

Testing Accessibility in React

Automated testing catches many common issues. Integrate tools like eslint-plugin-jsx-a11y into your IDE and CI pipeline. It flags missing alt text, incorrect ARIA, and invalid heading order. For unit tests, use jest-axe to run accessibility assertions on rendered components.

Manual testing is equally important. Use your keyboard to navigate the entire app. Can you reach all links, buttons, and form fields? Does the tab order make sense? Also test with a screen reader like NVDA (Windows) or VoiceOver (macOS) to hear what users experience.

Test on different devices and zoom levels. Ensure the app is usable at high zoom levels and on small screens. Accessibility overlaps significantly with responsive design and mobile usability.

Create a testing checklist for each new feature. Include items like: “Does this component work with keyboard only?”, “Are focus states visible?”, “Is content announced correctly?” Run manual tests after every major update.

Images and Alternative Text

Every image must have appropriate alternative text. Use the alt attribute on <img> elements. For decorative images, set alt="" (empty alt) so screen readers ignore them. For informative images, describe the content concisely.

In React, always pass an alt prop to your Image component. If the image is a link, the alt text should describe the link destination. For complex images like charts, provide a text alternative nearby or in a longdesc attribute.

Use ARIA roles like role="img" on SVG icons if they convey meaning. Otherwise, add aria-hidden="true" to ignore them. For icon buttons, combine with aria-label to provide an accessible name.

Putting It All Together

Start integrating these checks into your development workflow. Choose a few items from this checklist and focus on them in your next sprint. Over time, accessibility becomes a natural part of your coding habits.

Remember that accessibility is a continuous process. User needs change, and new tools emerge. Regularly revisit your checklist, run automated scans, and listen to feedback from users with disabilities. Your React app will be better for everyone.

Frequently asked questions

What is the most common accessibility mistake in React apps?

The most common mistake is using unnecessary or incorrect ARIA attributes. Many developers add ARIA roles and properties when a native HTML element already provides the needed semantics. For example, using role=”button” on a <div> instead of using a <button> element. This breaks keyboard navigation and screen reader support.

How do I manage focus in a single-page React app?

When navigating between routes, focus should move to the new page’s heading or main content. Use a useEffect hook to call focus() on a ref after the route change. For modals or dialogs, trap focus inside the modal and return it to the trigger element on close. Libraries like react-focus-lock can help.

Do I always need to use ARIA in React?

No. The first rule of ARIA is to use native HTML elements when possible. For example, use <button> instead of <div role=”button”>. Use ARIA only when the native semantics are insufficient, such as for live regions, custom widgets, or when you need to overwrite an element’s implicit role.

What tools can I use to test accessibility in React?

Use eslint-plugin-jsx-a11y for static analysis in your editor. For unit tests, jest-axe runs Axe accessibility checks on rendered components. For end-to-end testing, tools like Cypress with cypress-axe or Playwright with Axe integration can catch issues during integration tests.

How often should I run accessibility audits?

Run automated accessibility checks continuously in your CI pipeline on every pull request. Perform manual keyboard and screen reader tests during feature development and before major releases. Schedule full audits (using tools like Lighthouse or axe DevTools) at least once per sprint or after significant UI changes.