Keyvisual React Apps

    Best practices for building accessible React apps

    Any app that we build should be easy to use for everyone, including people with disabilities. This blog explains why accessibility is an essential part of application development and how it could boost an application’s reach. It throws insights into the best practices that one need to follow to make a react app accessible.

    In this article you will read about

    • Characteristics of Good design
    • Why is Accessibility important?
    • Web Accessibility standards
    • Checklist for building accessible apps
    • Accessibility tools and library

    Characteristics of Good design

    All companies want their products to reach as many users as possible.The primary factor that one should mainly consider while designing an app is user-friendliness. If an app is easy to use, then the chances to retain or engage the users in the app would be more.

    Some key characteristics of good design include:

    • Clear, Simple and Consistent workflow
    • Good color theming
    • Good error/exception handling
    • Every user feels comfortable using the app (Accessible to everyone)
    • Responsiveness

    The list grows bigger and bigger. One could write a separate blog to speak about the characteristics of good design.

    Why is Accessibility important?

    As we have seen above, building accessible apps is a primary characteristic of good design. But what exactly is Accessibility? And the first answer that popup in most of our minds is “Making the app readable with screen readers”. But it’s not just that.

    Web accessibility means designing a product such that every user has equal access to information and functionality irrespective of their ability. It includes people with the following disabilities:

    • Visual (Blindness, Low vision, Color blindness)
    • Cognitive (Dyslexia, Development disabilities)
    • Seizures
    • Auditory (Deafness, Hearing impairments)
    • Motor (tremors, Muscle slowness etc.)

    Building accessible apps have the following additional benefits as well.

    • The accessibility guidelines promote writing semantic HTML which in turn boosts SEO (Search Engine Optimization) for your website.
    • Your product can also comply with Government laws.

    Web Accessibility standards

    Web Content Accessibility Guidelines (WCAG) is a set of recommendations published by the Web Accessibility Initiative (WAI) of W3C to make Web content more accessible for all kinds of people.

    The accessibility guidelines principle says the content must be “POUR” which means:

    Perceivable (By everyone)

    Operable (Accessible with both keyboard and mouse)


    Robust — App works well in current and future user tools (Technologies and devices within reasonable limits)

    There are three levels of accessibility compliance in WCAG 2.1. Each of these levels has a set of guidelines which is catered into three buckets like “Must have, should have and could have”

    • A: Essential
    • AA: Ideal Support
    • AAA: Specialized support

    An app must adhere to at least level A to be minimum accessibility compliant.

    Checklist for building accessible apps

    The following is a summary of noteworthy points that one should bear in mind while building a web app.

    Root HTML tag with lang attribute

    The lang attribute is used to denote the language of the content on the website. It helps search engines to show language-specific results and the screen readers to switch language profiles to provide correct accent and pronunciation.

    The lang attribute can be set as follows:


    Unique title for every page

    The title tag within the head tag should have an appropriate title for every page. The websites should change the title accordingly when users navigate to different pages.

    Since changing the title with document.title affects SEO, tools like react-helmet allows dynamically change the title tag on every page.

    Keyboard navigation

    Keyboard navigation is a fundamental characteristic for providing accessibility. Many users with disability use the keyboard to access the UI elements. There are also users without accessibility who prefer the keyboard over the mouse to control elements.

    If your website has UI elements that are not easily accessible with the keyboard, then your users may get annoyed and leave the website early. Therefore, test your UI with a keyboard always when building components.

    The following are some important points that need to be tested when it comes to keyboard testing.

    Focus state

    The UI elements should have a clear focus state. So if you mark an element with outline:none or outline:0 in CSS, make sure you provide a better focus indicator than the one provided by browsers. You can change the default focus style using :focus attribute.

    Keyboard keys

    All the interactive elements must be activated by the keyboard as per their semantics. If you have defined event handlers for touch or click events, then the same handler should be triggered for the corresponding keyboard keys.

    That is, for example: If you have defined a handler for a button click, then the same should be triggered for pressing Enter or Space key. Apply proper semantics for arrow keys, Tab, Shift + Tab etc.,

    Avoid focus traps

    Tab through the content of your website to ensure the focus is not trapped within any content.

    Tab order — Avoid tabindex greater than zero

    The tab order should be in coherence with the logical flow/order of a web page.

    • A tabindex of 0 allows elements other than links and form elements to receive keyboard focus. These DOM elements receive focus in the order they are arranged in DOM. This tabindex value is handy when you want to make elements like div or li to be accessible with the tab key.

    • A tabindex of -1 means an element is not accessible via sequential keyboard navigation but could be focussed with Javascript or using the mouse.

    • Avoid using a positive value of tabindex because this value determines the order in which the element would be accessed while pressing the tab key. If an element down the page is set with a higher tabindex, it will receive focus before the one at the top of the DOM tree. It creates confusions and must be avoided

    Writing semantic HTML

    Never use <div> for everything. HTML 5 has several useful tags like aside, main, nav, section, header, footer etc. It helps screen readers and also the search engines to effectively crawl and display search results.

    Heading tags

    A page must have only one h1 tag and, the heading tags should have a logical sequence in the HTML. For example, an h4 shouldn’t appear before h2 in a webpage.

    Hide content correctly

    Do not use display:none, or visibility:hidden or hidden attribute because they remove the content from the accessibility tree, making it inaccessible to screen readers. You can create a visually-hidden CSS that hides the element visually without removing it from the accessibility tree.

    Best practices for building accessible React apps (2)


    Every icon should have aria-label to describe its purpose. For example, a thumbs up icon should have an aria-label or label tag with the value like “Like post”. If you are using a label tag, make sure you hide it with the visually hidden CSS seen above.

    Image with alt text

    All images must have meaningful alternative text that is displayed when its loading fails.

    Form input controls

    • Every input or textarea must have a label tag or an aria-label attribute associated with it for screen readers to read the inputs.

    • The input element should have both required and aria-required attributes for the required fields and there should also be a visual indication to imply it.

    • Invalid inputs must have an aria-invalid attribute when it is invalid.

    • Use aria-describedby to provide instructions for controls. For example, if your input element should provide the date in a specific format, then the code should provide the instruction as follows:

    Best practices for building accessible React apps (3)

    • The validation errors should always be mapped to the field it describes so that the assistive devices can read the information when an error is encountered. aria-describedby can be used in conjunction with role=’alert’ to denote errors.

      Best practices for building accessible React apps (4)

    The example binds the input element with the error component using aria-describedby. The aria-describedby holds the id of the error component that is “nameError”

    Here is a blog that describes the difference between aria-label, aria-labelledby and aria-describedby.

    There are a lot more to explain about input controls. React Spectrum’s Aria has much useful information about Accessibility with form controls.

    Provide skip link

    Several websites have something similar to this below.

    Best practices for building accessible React apps (5)

    These skip links would be visible only when they are focused using the keyboard. They allow users to quickly navigate to the main content without pressing Tab several times. For example, one would want to avoid traversing through each of the navigation bar items. In such cases, the skip links are pretty handy.

    A webpage could have skip links to its most significant sections. For example, Twitter has skip links for “Skip to recommended content”, “Skip to secondary content” etc.,

    You can learn more about skip links here


    Some people face problems like nausea, dizziness, and malaise because of animations used on websites. The operating system offers a solution to this problem to opt-out of animations and this value can be read by browsers.

    For example, Apple exposes this value to the browser using a media query: prefer-reduced-motion. Websites can read this value and disable the animation.

    Here is a detailed article about prefer-reduced-motion and how to use it in React applications to create accessible animations.

    Accessibility tools and library

    Having known the best practices, it is always easier if a tool verifies at least some of these. Let’s look at some of the tools and extensions that offer support.

    Static analysis tools

    eslint-plugin-jsx-a11y is a static AST checker for accessibility rules on JSX elements. Since static analysis tools cannot check the values that change at runtime, this plugin alone cannot ensure whether a web app is completely compliant with accessibility guidelines.

    Libraries for React components

    Use some version of axe-core to automate A11y testing. The following tools depend on axe-core

    • @axe-core/react allows you to test accessibility at runtime. You can run axe in the development environment like below.

    Best practices for building accessible React apps (6)

    • jest-axe can be used with both Enzyme and @testing-library/react. But, I highly recommend using @testing-library/react over Enzyme.

    • cypress-axe can be used to test Accessibility in the entire application for different user actions


    Deque Axe is also very handy to test accessibility on applications.

    Although these tools automate/reduce the efforts of some manual testing, this alone does not ensure a website is 100% accessibility compliant. We should put ourselves in the shoes of an end-user and test each page/component when we develop.

    Finally, here is an excellent video from Sara Soueidan where she explains how one could manually test accessibility using the Voiceover tool and how one should layout elements effectively.


    Building accessible website is gaining a lot of traction and there are also laws enforcing the importance of accessibility. So, let’s make the web accessible to everyone irrespective of their ability :)

    Who writes here?

    Aishwarya Lakshmi

    I am full-stack developer at Mercateo. I like to build software that is resilient to change and write clean code whenever possible. I have been a front-end developer for quite some years. Now being a full-stack developer at Mercateo, I have the opportunity to explore other aspects of application development with backend and infrastructure. The company also supports its employee’s professional development in various ways, which I find very useful.

    Aishwarya Lakshmi