Cover image for The basics of Web Accessibility in React & Gatsby Projects

The basics of Web Accessibility in React & Gatsby Projects

maniekm profile image Mariusz Updated on ・5 min read

What is Accessibility and Web Accessibility?

Accessibility is the degree to which an environment is usable by as many people as possible.

Web Accessibility is the degree to which a website is usable by as many people as possible.

We traditionally think of this as being about people with disabilities, but the practice of making sites accessible also benefits other groups such as those using mobile devices, or those with slow network connections.

What is WCAG?

WCAG means Web Content Accessibility Guidelines:

  • published by W3C
  • a large and very detailed document that includes very precise, technology-agnostic criteria for accessibility conformance.

The criteria are split up into four main categories, which specify how implementations can be made perceivable, operable, understandable, robust.

I. Perceivable

  • Provide text alternatives for non-text content.
  • Provide captions and other alternatives for multimedia.
  • Create content that can be presented in different ways, including by assistive technologies, without losing meaning.
  • Make it easier for users to see and hear content.

II. Operable

  • Make all functionality available from a keyboard.
  • Give users enough time to read and use the content.
  • Do not use content that causes seizures or physical reactions.
  • Help users navigate and find content.
  • Make it easier to use inputs other than a keyboard.

III. Understandable

  • Make text readable and understandable.
  • Make content appear and operate in predictable ways.
  • Help users avoid and correct mistakes.

IV. Robust

Maximize compatibility with current and future user tools.

Most common WCAG failures?

wcag failures

How to achieve Accessibility in React & Gatsby projects?

In React & Gatsby you have full control of generated HTML so you can achieve an accessible website, by using standard HTML techniques.

Set Page Titles

Descriptive HTML page titles help users quickly understand a web page’s content. Remember to set up initial title and update it on every page change.

componentDidMount() {
  document.title = "Contact Us - Pagepro LTD";

You can also use a react-helmet plugin instead where you handle head tags per page:

import React from "react";
import {Helmet} from "react-helmet";

class App extends React.Component {
  render () {
    return (
        <div className="page">
                <title>Contact Us - Pagepro LTD</title>

Write Semantic HTML

An important principle in the web is the idea of using HTML elements to indicate what they actually are, rather than how they may appear in the browser by default. This is known as using semantic HTML.

Examples of semantic HTML tags include:

  • Header tags <h1> through <h6>
  • Paragraph tags <p> indicating the enclosed text
  • Button tags <button> for clickable controls
  • Anchor tags <a> for links

Semantic markup:

<button className="c-btn" onClick={this.onClick}>

Non-semantic markup:

<div onClick={this.onClick} className=c-btn>

Set lang attribute

Indicating the text language used on a web page is critical because assistive technologies need to know how to correctly pronounce the text. If you are displaying text in different languages on the same page you can use lang attribute for HTML tag and also for specific page elements:

<html lang="en-GB">
    <title>Contact Us - Pagepro LTD</title>
        <span lang="pl">"Klienci mówia, że jesteśmy całkiem mili."</span> . 

Provide alternative text for images

People with visual disabilities or other cognitive impairments often cannot perceive information conveyed through images without help from a textual alternative. Image-based content that impedes accessibility includes charts, graphs, and other non-textual content. Remember to add alt attributes that are describing the content in easy to understand form.

<img src="lola.jpg" alt="A picture of sitting Yorkshire Terrier called Lola" />

Use the aria-label attribute

Let's imagine that you have a popup dialog with a cross as a close button.

Most people would be able to infer visually that the top right button will close the dialog. A blind person using assistive technology might just hear "X", which doesn't mean much without the visual clues. aria-label explicitly tells them what the click on the button will do.

<button aria-label="Close Dialog" onclick="confirmationDialog.close()">X</button>

A Few Helpful Tools

You can also install ESLint jsx-a11y plugin for your React projects to display accessibility rules you miss while building your application.

npm install eslint-plugin-jsx-a11y  --save-dev

Update your eslint.rc file’s plugin and extends sections in your code editor. For plugin section:

"plugin": [ 

In the extends section:

"extends": [
  "plugin": "jsx-a11y/recommended"

What are the benefits of building accessible sites?

  • Semantic HTML, which improves accessibility, also improves SEO, making your site more findable.
  • Caring about accessibility demonstrates good ethics and morals, which improves your public image.
  • Other good practices that improve accessibility also make your site more usable by other groups, such as mobile phone users or those on low network speed. In fact, everyone can benefit from many such improvements.

Posted on Jun 18 by:

maniekm profile



Building web & mobile apps with React & React Native.


We build web and mobile apps to accelerate web businesses.


markdown guide

Great Post! I am working on updating our corporate web site to meet ADA, WCAG standards. I wish it was a React.js app but is ASP.NET. A bit old and could use a makeover for sure. I am building any new applications using React.js and Gatsby site generator so this will definitely be part of my tool belt for all public facing applications.


Indeed, I highly recommend both React for apps & Gatsby for static sites. Easy to make, easy to use.

Keeping fingers crossed for ASP.NET site! Maybe it's time to give it a new life! :)


I use React every chance I get, but the key being the time, with so much going on here and I am the only developer which also makes me help desk for all the applications we use (thank me that the ones I build new are of newer tech and easier to maintain). Would love to replace some of these old dinosaurs. I don't like putting band-aids on everything, not a good practice at all. Do it right the first time.

Maybe it's time to outsource it? :)

Or find a remote developer for help to join your team per hour?

It became crazy easy and efficient cost-wise now.

Let me know if you need a help with that. I know mid-senior you could onboard for your projects very quick.

I will definitely keep that in mind. Waiting to find out now if we are doing a system conversion and if that happens i will definitely need some dev help.