Often, several components need to reflect the same changing data. We recommend lifting the shared state up to their closest common ancestor. Let’s see how this works in action.
In this section, we will create a temperature calculator that calculates whether the water would boil at a given temperature.
We will start with a component called
BoilingVerdict
. It accepts the
celsius
temperature as a prop, and prints whether it is enough to boil the water:
functionBoilingVerdict(props){ if(props.celsius >=100){ return<p>The water would boil.</p>;} return<p>The water would not boil.</p>;}
Next, we will create a component called
Calculator
. It renders an
<input>
that lets you enter the temperature, and keeps its value in
this.state.temperature
.
Additionally, it renders the
BoilingVerdict
for the current input value.
render(){ const temperature =this.state.temperature;return( <fieldset> <legend>Enter temperature in Celsius:</legend> <inputvalue={temperature}onChange={this.handleChange}/><BoilingVerdictcelsius={parseFloat(temperature)}/></fieldset> ); } }
We have two inputs now, but when you enter the temperature in one of them, the other doesn’t update. This contradicts our requirement: we want to keep them in sync.
We also can’t display the
BoilingVerdict
from
Calculator
. The
Calculator
doesn’t know the current temperature because it is hidden inside the
TemperatureInput
.
Writing Conversion Functions
First, we will write two functions to convert from Celsius to Fahrenheit and back:
These two functions convert numbers. We will write another function that takes a string
temperature
and a converter function as arguments and returns a string. We will use it to calculate the value of one input based on the other input.
It returns an empty string on an invalid
temperature
, and it keeps the output rounded to the third decimal place:
render(){ const temperature =this.state.temperature;// ...
However, we want these two inputs to be in sync with each other. When we update the Celsius input, the Fahrenheit input should reflect the converted temperature, and vice versa.
In React, sharing state is accomplished by moving it up to the closest common ancestor of the components that need it. This is called “lifting state up”. We will remove the local state from the
TemperatureInput
and move it into the
Calculator
instead.
If the
Calculator
owns the shared state, it becomes the “source of truth” for the current temperature in both inputs. It can instruct them both to have values that are consistent with each other. Since the props of both
TemperatureInput
components are coming from the same parent
Calculator
component, the two inputs will always be in sync.
Let’s see how this works step by step.
First, we will replace
this.state.temperature
with
this.props.temperature
in the
TemperatureInput
component. For now, let’s pretend
this.props.temperature
already exists, although we will need to pass it from the
Calculator
in the future:
render(){ // Before: const temperature = this.state.temperature; const temperature =this.props.temperature;// ...
We know that props are read-only. When the
temperature
was in the local state, the
TemperatureInput
could just call
this.setState()
to change it. However, now that the
temperature
is coming from the parent as a prop, the
TemperatureInput
has no control over it.
In React, this is usually solved by making a component “controlled”. Just like the DOM
<input>
accepts both a
value
and an
onChange
prop, so can the custom
TemperatureInput
accept both
temperature
and
onTemperatureChange
props from its parent
Calculator
.
Now, when the
TemperatureInput
wants to update its temperature, it calls
this.props.onTemperatureChange
:
There is no special meaning to either
temperature
or
onTemperatureChange
prop names in custom components. We could have called them anything else, like name them
value
and
onChange
which is a common convention.
The
onTemperatureChange
prop will be provided together with the
temperature
prop by the parent
Calculator
component. It will handle the change by modifying its own local state, thus re-rendering both inputs with the new values. We will look at the new
Calculator
implementation very soon.
Before diving into the changes in the
Calculator
, let’s recap our changes to the
TemperatureInput
component. We have removed the local state from it, and instead of reading
this.state.temperature
, we now read
this.props.temperature
. Instead of calling
this.setState()
when we want to make a change, we now call
this.props.onTemperatureChange()
, which will be provided by the
Calculator
:
render(){ const temperature =this.props.temperature;const scale =this.props.scale; return( <fieldset> <legend>Enter temperature in {scaleNames[scale]}:</legend> <inputvalue={temperature} onChange={this.handleChange}/> </fieldset> ); } }
Now let’s turn to the
Calculator
component.
We will store the current input’s
temperature
and
scale
in its local state. This is the state we “lifted up” from the inputs, and it will serve as the “source of truth” for both of them. It is the minimal representation of all the data we need to know in order to render both inputs.
For example, if we enter 37 into the Celsius input, the state of the
Calculator
component will be:
{ temperature:'37', scale:'c' }
If we later edit the Fahrenheit field to be 212, the state of the
Calculator
will be:
{ temperature:'212', scale:'f' }
We could have stored the value of both inputs but it turns out to be unnecessary. It is enough to store the value of the most recently changed input, and the scale that it represents. We can then infer the value of the other input based on the current
temperature
and
scale
alone.
The inputs stay in sync because their values are computed from the same state:
Now, no matter which input you edit,
this.state.temperature
and
this.state.scale
in the
Calculator
get updated. One of the inputs gets the value as is, so any user input is preserved, and the other input value is always recalculated based on it.
Let’s recap what happens when you edit an input:
React calls the function specified as
onChange
on the DOM
<input>
. In our case, this is the
handleChange
method in the
TemperatureInput
component.
The
handleChange
method in the
TemperatureInput
component calls
this.props.onTemperatureChange()
with the new desired value. Its props, including
onTemperatureChange
, were provided by its parent component, the
Calculator
.
When it previously rendered, the
Calculator
had specified that
onTemperatureChange
of the Celsius
TemperatureInput
is the
Calculator
’s
handleCelsiusChange
method, and
onTemperatureChange
of the Fahrenheit
TemperatureInput
is the
Calculator
’s
handleFahrenheitChange
method. So either of these two
Calculator
methods gets called depending on which input we edited.
Inside these methods, the
Calculator
component asks React to re-render itself by calling
this.setState()
with the new input value and the current scale of the input we just edited.
React calls the
Calculator
component’s
render
method to learn what the UI should look like. The values of both inputs are recomputed based on the current temperature and the active scale. The temperature conversion is performed here.
React calls the
render
methods of the individual
TemperatureInput
components with their new props specified by the
Calculator
. It learns what their UI should look like.
React calls the
render
method of the
BoilingVerdict
component, passing the temperature in Celsius as its props.
React DOM updates the DOM with the boiling verdict and to match the desired input values. The input we just edited receives its current value, and the other input is updated to the temperature after conversion.
Every update goes through the same steps so the inputs stay in sync.
Lessons Learned
There should be a single “source of truth” for any data that changes in a React application. Usually, the state is first added to the component that needs it for rendering. Then, if other components also need it, you can lift it up to their closest common ancestor. Instead of trying to sync the state between different components, you should rely on the top-down data flow.
Lifting state involves writing more “boilerplate” code than two-way binding approaches, but as a benefit, it takes less work to find and isolate bugs. Since any state “lives” in some component and that component alone can change it, the surface area for bugs is greatly reduced. Additionally, you can implement any custom logic to reject or transform user input.
If something can be derived from either props or state, it probably shouldn’t be in the state. For example, instead of storing both
celsiusValue
and
fahrenheitValue
, we store just the last edited
temperature
and its
scale
. The value of the other input can always be calculated from them in the
render()
method. This lets us clear or apply rounding to the other field without losing any precision in the user input.
When you see something wrong in the UI, you can use React Developer Tools to inspect the props and move up the tree until you find the component responsible for updating the state. This lets you trace the bugs to their source:
Is this page useful?
Edit this page
Composition vs Inheritance – React
Composition vs Inheritance
React has a powerful composition model, and we recommend using composition instead of inheritance to reuse code between components.
In this section, we will consider a few problems where developers new to React often reach for inheritance, and show how we can solve them with composition.
Some components don’t know their children ahead of time. This is especially common for components like
Sidebar
or
Dialog
that represent generic “boxes”.
We recommend that such components use the special
children
prop to pass children elements directly into their output:
This lets other components pass arbitrary children to them by nesting the JSX:
functionWelcomeDialog(){ return( <FancyBordercolor="blue"> <h1className="Dialog-title"> Welcome</h1><pclassName="Dialog-message"> Thank you for visiting our spacecraft!</p></FancyBorder> ); }
Try it on CodePen
Anything inside the
<FancyBorder>
JSX tag gets passed into the
FancyBorder
component as a
children
prop. Since
FancyBorder
renders
{props.children}
inside a
<div>
, the passed elements appear in the final output.
While this is less common, sometimes you might need multiple “holes” in a component. In such cases you may come up with your own convention instead of using
children
:
React elements like
<Contacts />
and
<Chat />
are just objects, so you can pass them as props like any other data. This approach may remind you of “slots” in other libraries but there are no limitations on what you can pass as props in React.
Specialization
Sometimes we think about components as being “special cases” of other components. For example, we might say that a
WelcomeDialog
is a special case of
Dialog
.
In React, this is also achieved by composition, where a more “specific” component renders a more “generic” one and configures it with props:
render(){ return( <Dialogtitle="Mars Exploration Program" message="How should we refer to you?"> <inputvalue={this.state.login}onChange={this.handleChange}/><buttononClick={this.handleSignUp}> Sign Me Up!</button></Dialog> ); }
At Facebook, we use React in thousands of components, and we haven’t found any use cases where we would recommend creating component inheritance hierarchies.
Props and composition give you all the flexibility you need to customize a component’s look and behavior in an explicit and safe way. Remember that components may accept arbitrary props, including primitive values, React elements, or functions.
If you want to reuse non-UI functionality between components, we suggest extracting it into a separate JavaScript module. The components may import it and use that function, object, or class, without extending it.
React is, in our opinion, the premier way to build big, fast Web apps with JavaScript. It has scaled very well for us at Facebook and Instagram.
One of the many great parts of React is how it makes you think about apps as you build them. In this document, we’ll walk you through the thought process of building a searchable product data table using React.
The first thing you’ll want to do is to draw boxes around every component (and subcomponent) in the mock and give them all names. If you’re working with a designer, they may have already done this, so go talk to them! Their Photoshop layer names may end up being the names of your React components!
But how do you know what should be its own component? Use the same techniques for deciding if you should create a new function or object. One such technique is the single responsibility principle, that is, a component should ideally only do one thing. If it ends up growing, it should be decomposed into smaller subcomponents.
Since you’re often displaying a JSON data model to a user, you’ll find that if your model was built correctly, your UI (and therefore your component structure) will map nicely. That’s because UI and data models tend to adhere to the same
information architecture
. Separate your UI into components, where each component matches one piece of your data model.
You’ll see here that we have five components in our app. We’ve italicized the data each component represents. The numbers in the image correspond to the numbers below.
FilterableProductTable
(orange):
contains the entirety of the example
SearchBar
(blue):
receives all
user input
ProductTable
(green):
displays and filters the
data collection
based on
user input
ProductCategoryRow
(turquoise):
displays a heading for each
category
ProductRow
(red):
displays a row for each
product
If you look at
ProductTable
, you’ll see that the table header (containing the “Name” and “Price” labels) isn’t its own component. This is a matter of preference, and there’s an argument to be made either way. For this example, we left it as part of
ProductTable
because it is part of rendering the
data collection
which is
ProductTable
’s responsibility. However, if this header grows to be complex (e.g., if we were to add affordances for sorting), it would certainly make sense to make this its own
ProductTableHeader
component.
Now that we’ve identified the components in our mock, let’s arrange them into a hierarchy. Components that appear within another component in the mock should appear as a child in the hierarchy:
FilterableProductTable
SearchBar
ProductTable
ProductCategoryRow
ProductRow
Step 2: Build A Static Version in React
See the Pen Thinking In React: Step 2 on CodePen.
Now that you have your component hierarchy, it’s time to implement your app. The easiest way is to build a version that takes your data model and renders the UI but has no interactivity. It’s best to decouple these processes because building a static version requires a lot of typing and no thinking, and adding interactivity requires a lot of thinking and not a lot of typing. We’ll see why.
To build a static version of your app that renders your data model, you’ll want to build components that reuse other components and pass data using
props
.
props
are a way of passing data from parent to child. If you’re familiar with the concept of
state
,
don’t use state at all
to build this static version. State is reserved only for interactivity, that is, data that changes over time. Since this is a static version of the app, you don’t need it.
You can build top-down or bottom-up. That is, you can either start with building the components higher up in the hierarchy (i.e. starting with
FilterableProductTable
) or with the ones lower in it (
ProductRow
). In simpler examples, it’s usually easier to go top-down, and on larger projects, it’s easier to go bottom-up and write tests as you build.
At the end of this step, you’ll have a library of reusable components that render your data model. The components will only have
render()
methods since this is a static version of your app. The component at the top of the hierarchy (
FilterableProductTable
) will take your data model as a prop. If you make a change to your underlying data model and call
root.render()
again, the UI will be updated. You can see how your UI is updated and where to make changes. React’s
one-way data flow
(also called
one-way binding
) keeps everything modular and fast.
Refer to the React docs if you need help executing this step.
A Brief Interlude: Props vs State
There are two types of “model” data in React: props and state. It’s important to understand the distinction between the two; skim the official React docs if you aren’t sure what the difference is. See also FAQ: What is the difference between state and props?
Step 3: Identify The Minimal (but complete) Representation Of UI State
To make your UI interactive, you need to be able to trigger changes to your underlying data model. React achieves this with
state
.
To build your app correctly, you first need to think of the minimal set of mutable state that your app needs. The key here is DRY:
Don’t Repeat Yourself
. Figure out the absolute minimal representation of the state your application needs and compute everything else you need on-demand. For example, if you’re building a TODO list, keep an array of the TODO items around; don’t keep a separate state variable for the count. Instead, when you want to render the TODO count, take the length of the TODO items array.
Think of all the pieces of data in our example application. We have:
The original list of products
The search text the user has entered
The value of the checkbox
The filtered list of products
Let’s go through each one and figure out which one is state. Ask three questions about each piece of data:
Is it passed in from a parent via props? If so, it probably isn’t state.
Does it remain unchanged over time? If so, it probably isn’t state.
Can you compute it based on any other state or props in your component? If so, it isn’t state.
The original list of products is passed in as props, so that’s not state. The search text and the checkbox seem to be state since they change over time and can’t be computed from anything. And finally, the filtered list of products isn’t state because it can be computed by combining the original list of products with the search text and value of the checkbox.
So finally, our state is:
The search text the user has entered
The value of the checkbox
Step 4: Identify Where Your State Should Live
See the Pen Thinking In React: Step 4 on CodePen.
OK, so we’ve identified what the minimal set of app state is. Next, we need to identify which component mutates, or
owns
, this state.
Remember: React is all about one-way data flow down the component hierarchy. It may not be immediately clear which component should own what state.
This is often the most challenging part for newcomers to understand,
so follow these steps to figure it out:
For each piece of state in your application:
Identify every component that renders something based on that state.
Find a common owner component (a single component above all the components that need the state in the hierarchy).
Either the common owner or another component higher up in the hierarchy should own the state.
If you can’t find a component where it makes sense to own the state, create a new component solely for holding the state and add it somewhere in the hierarchy above the common owner component.
Let’s run through this strategy for our application:
ProductTable
needs to filter the product list based on state and
SearchBar
needs to display the search text and checked state.
The common owner component is
FilterableProductTable
.
It conceptually makes sense for the filter text and checked value to live in
FilterableProductTable
Cool, so we’ve decided that our state lives in
FilterableProductTable
. First, add an instance property
this.state = {filterText: '', inStockOnly: false}
to
FilterableProductTable
’s
constructor
to reflect the initial state of your application. Then, pass
filterText
and
inStockOnly
to
ProductTable
and
SearchBar
as a prop. Finally, use these props to filter the rows in
ProductTable
and set the values of the form fields in
SearchBar
.
You can start seeing how your application will behave: set
filterText
to
"ball"
and refresh your app. You’ll see that the data table is updated correctly.
Step 5: Add Inverse Data Flow
See the Pen Thinking In React: Step 5 on CodePen.
So far, we’ve built an app that renders correctly as a function of props and state flowing down the hierarchy. Now it’s time to support data flowing the other way: the form components deep in the hierarchy need to update the state in
FilterableProductTable
.
React makes this data flow explicit to help you understand how your program works, but it does require a little more typing than traditional two-way data binding.
If you try to type or check the box in the previous version of the example (step 4), you’ll see that React ignores your input. This is intentional, as we’ve set the
value
prop of the
input
to always be equal to the
state
passed in from
FilterableProductTable
.
Let’s think about what we want to happen. We want to make sure that whenever the user changes the form, we update the state to reflect the user input. Since components should only update their own state,
FilterableProductTable
will pass callbacks to
SearchBar
that will fire whenever the state should be updated. We can use the
onChange
event on the inputs to be notified of it. The callbacks passed by
FilterableProductTable
will call
setState()
, and the app will be updated.
And That’s It
Hopefully, this gives you an idea of how to think about building components and applications with React. While it may be a little more typing than you’re used to, remember that code is read far more often than it’s written, and it’s less difficult to read this modular, explicit code. As you start to build large libraries of components, you’ll appreciate this explicitness and modularity, and with code reuse, your lines of code will start to shrink. :)
Web accessibility (also referred to as
a11y
) is the design and creation of websites that can be used by everyone. Accessibility support is necessary to allow assistive technology to interpret web pages.
React fully supports building accessible websites, often by using standard HTML techniques.
Standards and Guidelines
WCAG
The Web Content Accessibility Guidelines provides guidelines for creating accessible web sites.
The following WCAG checklists provide an overview:
WCAG checklist from Wuhcag
WCAG checklist from WebAIM
Checklist from The A11Y Project
WAI-ARIA
The Web Accessibility Initiative - Accessible Rich Internet Applications document contains techniques for building fully accessible JavaScript widgets.
Note that all
aria-*
HTML attributes are fully supported in JSX. Whereas most DOM properties and attributes in React are camelCased, these attributes should be hyphen-cased (also known as kebab-case, lisp-case, etc) as they are in plain HTML:
Semantic HTML is the foundation of accessibility in a web application. Using the various HTML elements to reinforce the meaning of information
in our websites will often give us accessibility for free.
MDN HTML elements reference
Sometimes we break HTML semantics when we add
<div>
elements to our JSX to make our React code work, especially when working with lists (
<ol>
,
<ul>
and
<dl>
) and the HTML
<table>
.
In these cases we should rather use React Fragments to group together multiple elements.
You can map a collection of items to an array of fragments as you would any other type of element as well:
functionGlossary(props){ return( <dl> {props.items.map(item=>( // Fragments should also have a `key` prop when mapping collections <Fragmentkey={item.id}><dt>{item.term}</dt> <dd>{item.description}</dd> </Fragment>))} </dl> ); }
When you don’t need any props on the Fragment tag you can use the short syntax, if your tooling supports it:
Every HTML form control, such as
<input>
and
<textarea>
, needs to be labeled accessibly. We need to provide descriptive labels that are also exposed to screen readers.
The following resources show us how to do this:
The W3C shows us how to label elements
WebAIM shows us how to label elements
The Paciello Group explains accessible names
Although these standard HTML practices can be directly used in React, note that the
for
attribute is written as
htmlFor
in JSX:
Error situations need to be understood by all users. The following link shows us how to expose error texts to screen readers as well:
The W3C demonstrates user notifications
WebAIM looks at form validation
Focus Control
Ensure that your web application can be fully operated with the keyboard only:
WebAIM talks about keyboard accessibility
Keyboard focus and focus outline
Keyboard focus refers to the current element in the DOM that is selected to accept input from the keyboard. We see it everywhere as a focus outline similar to that shown in the following image:
Only ever use CSS that removes this outline, for example by setting
outline: 0
, if you are replacing it with another focus outline implementation.
Mechanisms to skip to desired content
Provide a mechanism to allow users to skip past navigation sections in your application as this assists and speeds up keyboard navigation.
Skiplinks or Skip Navigation Links are hidden navigation links that only become visible when keyboard users interact with the page. They are very easy to implement with internal page anchors and some styling:
WebAIM - Skip Navigation Links
Also use landmark elements and roles, such as
<main>
and
<aside>
, to demarcate page regions as assistive technology allow the user to quickly navigate to these sections.
Read more about the use of these elements to enhance accessibility here:
Accessible Landmarks
Programmatically managing focus
Our React applications continuously modify the HTML DOM during runtime, sometimes leading to keyboard focus being lost or set to an unexpected element. In order to repair this, we need to programmatically nudge the keyboard focus in the right direction. For example, by resetting keyboard focus to a button that opened a modal window after that modal window is closed.
MDN Web Docs takes a look at this and describes how we can build keyboard-navigable JavaScript widgets.
To set focus in React, we can use Refs to DOM elements.
Using this, we first create a ref to an element in the JSX of a component class:
classCustomTextInputextendsReact.Component{ constructor(props){ super(props); // Create a ref to store the textInput DOM elementthis.textInput = React.createRef();} render(){ // Use the `ref` callback to store a reference to the text input DOM// element in an instance field (for example, this.textInput).return( <input type="text" ref={this.textInput}/> ); } }
Then we can focus it elsewhere in our component when needed:
focus(){ // Explicitly focus the text input using the raw DOM API // Note: we're accessing "current" to get the DOM node this.textInput.current.focus(); }
Sometimes a parent component needs to set focus to an element in a child component. We can do this by exposing DOM refs to parent components through a special prop on the child component that forwards the parent’s ref to the child’s DOM node.
// Now you can set focus when required. this.inputElement.current.focus();
When using a HOC to extend components, it is recommended to forward the ref to the wrapped component using the
forwardRef
function of React. If a third party HOC does not implement ref forwarding, the above pattern can still be used as a fallback.
A great focus management example is the react-aria-modal. This is a relatively rare example of a fully accessible modal window. Not only does it set initial focus on
the cancel button (preventing the keyboard user from accidentally activating the success action) and trap keyboard focus inside the modal, it also resets focus back to the element that initially triggered the modal.
Note:
While this is a very important accessibility feature, it is also a technique that should be used judiciously. Use it to repair the keyboard focus flow when it is disturbed, not to try and anticipate how
users want to use applications.
Mouse and pointer events
Ensure that all functionality exposed through a mouse or pointer event can also be accessed using the keyboard alone. Depending only on the pointer device will lead to many cases where keyboard users cannot use your application.
To illustrate this, let’s look at a prolific example of broken accessibility caused by click events. This is the outside click pattern, where a user can disable an opened popover by clicking outside the element.
This is typically implemented by attaching a
click
event to the
window
object that closes the popover:
This may work fine for users with pointer devices, such as a mouse, but operating this with the keyboard alone leads to broken functionality when tabbing to the next element as the
window
object never receives a
click
event. This can lead to obscured functionality which blocks users from using your application.
The same functionality can be achieved by using appropriate event handlers instead, such as
onBlur
and
onFocus
:
// We close the popover on the next tick by using setTimeout.// This is necessary because we need to first check if// another child of the element has received focus as// the blur event fires prior to the new focus event.onBlurHandler(){this.timeOutId =setTimeout(()=>{this.setState({isOpen:false});});} // If a child receives focus, do not close the popover.onFocusHandler(){clearTimeout(this.timeOutId);} render(){ // React assists us by bubbling the blur and// focus events to the parent.return( <divonBlur={this.onBlurHandler}onFocus={this.onFocusHandler}><buttononClick={this.onClickHandler} aria-haspopup="true" aria-expanded={this.state.isOpen}> Select an option </button> {this.state.isOpen &&( <ul> <li>Option 1</li> <li>Option 2</li> <li>Option 3</li> </ul> )} </div> ); } }
This code exposes the functionality to both pointer device and keyboard users. Also note the added
aria-*
props to support screen-reader users. For simplicity’s sake the keyboard events to enable
arrow key
interaction of the popover options have not been implemented.
This is one example of many cases where depending on only pointer and mouse events will break functionality for keyboard users. Always testing with the keyboard will immediately highlight the problem areas which can then be fixed by using keyboard aware event handlers.
More Complex Widgets
A more complex user experience should not mean a less accessible one. Whereas accessibility is most easily achieved by coding as close to HTML as possible, even the most complex widget can be coded accessibly.
Here we require knowledge of ARIA Roles as well as ARIA States and Properties.
These are toolboxes filled with HTML attributes that are fully supported in JSX and enable us to construct fully accessible, highly functional React components.
Each type of widget has a specific design pattern and is expected to function in a certain way by users and user agents alike:
ARIA Authoring Practices Guide (APG) - Design Patterns and Examples
Heydon Pickering - ARIA Examples
Inclusive Components
Other Points for Consideration
Setting the language
Indicate the human language of page texts as screen reader software uses this to select the correct voice settings:
WebAIM - Document Language
Setting the document title
Set the document
<title>
to correctly describe the current page content as this ensures that the user remains aware of the current page context:
WCAG - Understanding the Document Title Requirement
We can set this in React using the React Document Title Component.
Color contrast
Ensure that all readable text on your website has sufficient color contrast to remain maximally readable by users with low vision:
WCAG - Understanding the Color Contrast Requirement
Everything About Color Contrast And Why You Should Rethink It
A11yProject - What is Color Contrast
It can be tedious to manually calculate the proper color combinations for all cases in your website so instead, you can calculate an entire accessible color palette with Colorable.
Both the aXe and WAVE tools mentioned below also include color contrast tests and will report on contrast errors.
If you want to extend your contrast testing abilities you can use these tools:
WebAIM - Color Contrast Checker
The Paciello Group - Color Contrast Analyzer
Development and Testing Tools
There are a number of tools we can use to assist in the creation of accessible web applications.
The keyboard
By far the easiest and also one of the most important checks is to test if your entire website can be reached and used with the keyboard alone. Do this by:
Disconnecting your mouse.
Using
Tab
and
Shift+Tab
to browse.
Using
Enter
to activate elements.
Where required, using your keyboard arrow keys to interact with some elements, such as menus and dropdowns.
Development assistance
We can check some accessibility features directly in our JSX code. Often intellisense checks are already provided in JSX aware IDE’s for the ARIA roles, states and properties. We also have access to the following tool:
eslint-plugin-jsx-a11y
The eslint-plugin-jsx-a11y plugin for ESLint provides AST linting feedback regarding accessibility issues in your JSX. Many IDE’s allow you to integrate these findings directly into code analysis and source code windows.
Create React App has this plugin with a subset of rules activated. If you want to enable even more accessibility rules, you can create an
.eslintrc
file in the root of your project with this content:
A number of tools exist that can run accessibility audits on web pages in your browser. Please use them in combination with other accessibility checks mentioned here as they can only
test the technical accessibility of your HTML.
aXe, aXe-core and react-axe
Deque Systems offers aXe-core for automated and end-to-end accessibility tests of your applications. This module includes integrations for Selenium.
The Accessibility Engine or aXe, is an accessibility inspector browser extension built on
aXe-core
.
You can also use the @axe-core/react module to report these accessibility findings directly to the console while developing and debugging.
WebAIM WAVE
The Web Accessibility Evaluation Tool is another accessibility browser extension.
Accessibility inspectors and the Accessibility Tree
The Accessibility Tree is a subset of the DOM tree that contains accessible objects for every DOM element that should be exposed
to assistive technology, such as screen readers.
In some browsers we can easily view the accessibility information for each element in the accessibility tree:
Using the Accessibility Inspector in Firefox
Using the Accessibility Inspector in Chrome
Using the Accessibility Inspector in OS X Safari
Screen readers
Testing with a screen reader should form part of your accessibility tests.
Please note that browser / screen reader combinations matter. It is recommended that you test your application in the browser best suited to your screen reader of choice.
Commonly Used Screen Readers
NVDA in Firefox
NonVisual Desktop Access or NVDA is an open source Windows screen reader that is widely used.
Refer to the following guides on how to best use NVDA:
WebAIM - Using NVDA to Evaluate Web Accessibility
Deque - NVDA Keyboard Shortcuts
VoiceOver in Safari
VoiceOver is an integrated screen reader on Apple devices.
Refer to the following guides on how to activate and use VoiceOver:
WebAIM - Using VoiceOver to Evaluate Web Accessibility
Deque - VoiceOver for OS X Keyboard Shortcuts
Deque - VoiceOver for iOS Shortcuts
JAWS in Internet Explorer
Job Access With Speech or JAWS, is a prolifically used screen reader on Windows.
Refer to the following guides on how to best use JAWS:
WebAIM - Using JAWS to Evaluate Web Accessibility
Deque - JAWS Keyboard Shortcuts
Other Screen Readers
ChromeVox in Google Chrome
ChromeVox is an integrated screen reader on Chromebooks and is available as an extension for Google Chrome.
Refer to the following guides on how best to use ChromeVox:
Google Chromebook Help - Use the Built-in Screen Reader
Most React apps will have their files “bundled” using tools like Webpack, Rollup or Browserify. Bundling is the process of following imported files and merging them into a single file: a “bundle”. This bundle can then be included on a webpage to load an entire app at once.
Example
App:
// app.js import{ add }from'./math.js';
console.log(add(16,26));// 42
// math.js exportfunctionadd(a, b){ return a + b; }
Bundle:
functionadd(a, b){ return a + b; }
console.log(add(16,26));// 42
Note:
Your bundles will end up looking a lot different than this.
If you’re using Create React App, Next.js, Gatsby, or a similar tool, you will have a Webpack setup out of the box to bundle your app.
If you aren’t, you’ll need to set up bundling yourself. For example, see the Installation and Getting Started guides on the Webpack docs.
Code Splitting
Bundling is great, but as your app grows, your bundle will grow too. Especially if you are including large third-party libraries. You need to keep an eye on the code you are including in your bundle so that you don’t accidentally make it so large that your app takes a long time to load.
To avoid winding up with a large bundle, it’s good to get ahead of the problem and start “splitting” your bundle. Code-Splitting is a feature
supported by bundlers like Webpack, Rollup and Browserify (via factor-bundle) which can create multiple bundles that can be dynamically loaded at runtime.
Code-splitting your app can help you “lazy-load” just the things that are currently needed by the user, which can dramatically improve the performance of your app. While you haven’t reduced the overall amount of code in your app, you’ve avoided loading code that the user may never need, and reduced the amount of code needed during the initial load.
import()
The best way to introduce code-splitting into your app is through the dynamic
import()
syntax.
When Webpack comes across this syntax, it automatically starts code-splitting your app. If you’re using Create React App, this is already configured for you and you can start using it immediately. It’s also supported out of the box in Next.js.
If you’re setting up Webpack yourself, you’ll probably want to read Webpack’s guide on code splitting. Your Webpack config should look vaguely like this.
When using Babel, you’ll need to make sure that Babel can parse the dynamic import syntax but is not transforming it. For that you will need @babel/plugin-syntax-dynamic-import.
React.lazy
The
React.lazy
function lets you render a dynamic import as a regular component.
This will automatically load the bundle containing the
OtherComponent
when this component is first rendered.
React.lazy
takes a function that must call a dynamic
import()
. This must return a
Promise
which resolves to a module with a
default
export containing a React component.
The lazy component should then be rendered inside a
Suspense
component, which allows us to show some fallback content (such as a loading indicator) while we’re waiting for the lazy component to load.
The
fallback
prop accepts any React elements that you want to render while waiting for the component to load. You can place the
Suspense
component anywhere above the lazy component. You can even wrap multiple lazy components with a single
Suspense
component.
Any component may suspend as a result of rendering, even components that were already shown to the user. In order for screen content to always be consistent, if an already shown component suspends, React has to hide its tree up to the closest
<Suspense>
boundary. However, from the user’s perspective, this can be disorienting.
In this example, if tab gets changed from
'photos'
to
'comments'
, but
Comments
suspends, the user will see a glimmer. This makes sense because the user no longer wants to see
Photos
, the
Comments
component is not ready to render anything, and React needs to keep the user experience consistent, so it has no choice but to show the
Glimmer
above.
However, sometimes this user experience is not desirable. In particular, it is sometimes better to show the “old” UI while the new UI is being prepared. You can use the new
startTransition
API to make React do this:
Here, you tell React that setting tab to
'comments'
is not an urgent update, but is a transition that may take some time. React will then keep the old UI in place and interactive, and will switch to showing
<Comments />
when it is ready. See Transitions for more info.
Error boundaries
If the other module fails to load (for example, due to network failure), it will trigger an error. You can handle these errors to show a nice user experience and manage recovery with Error Boundaries. Once you’ve created your Error Boundary, you can use it anywhere above your lazy components to display an error state when there’s a network error.
Deciding where in your app to introduce code splitting can be a bit tricky. You want to make sure you choose places that will split bundles evenly, but won’t disrupt the user experience.
A good place to start is with routes. Most people on the web are used to page transitions taking some amount of time to load. You also tend to be re-rendering the entire page at once so your users are unlikely to be interacting with other elements on the page at the same time.
Here’s an example of how to setup route-based code splitting into your app using libraries like React Router with
React.lazy
.
React.lazy
currently only supports default exports. If the module you want to import uses named exports, you can create an intermediate module that reexports it as the default. This ensures that tree shaking keeps working and that you don’t pull in unused components.
Context provides a way to pass data through the component tree without having to pass props down manually at every level.
In a typical React application, data is passed top-down (parent to child) via props, but such usage can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like these between components without having to explicitly pass a prop through every level of the tree.
Context is designed to share data that can be considered “global” for a tree of React components, such as the current authenticated user, theme, or preferred language. For example, in the code below we manually thread through a “theme” prop in order to style the Button component:
functionToolbar(props){ // The Toolbar component must take an extra "theme" prop// and pass it to the ThemedButton. This can become painful// if every single button in the app needs to know the theme// because it would have to be passed through all components.return( <div> <ThemedButtontheme={props.theme}/></div> ); }
Using context, we can avoid passing props through intermediate elements:
// Context lets us pass a value deep into the component tree// without explicitly threading it through every component.// Create a context for the current theme (with "light" as the default).const ThemeContext = React.createContext('light'); classAppextendsReact.Component{ render(){ // Use a Provider to pass the current theme to the tree below.// Any component can read it, no matter how deep it is.// In this example, we're passing "dark" as the current value.return( <ThemeContext.Providervalue="dark"><Toolbar/> </ThemeContext.Provider> ); } }
// A component in the middle doesn't have to// pass the theme down explicitly anymore.functionToolbar(){ return( <div> <ThemedButton/> </div> ); }
classThemedButtonextendsReact.Component{ // Assign a contextType to read the current theme context.// React will find the closest theme Provider above and use its value.// In this example, the current theme is "dark".static contextType = ThemeContext; render(){ return<Buttontheme={this.context}/>;} }
Before You Use Context
Context is primarily used when some data needs to be accessible by
many
components at different nesting levels. Apply it sparingly because it makes component reuse more difficult.
If you only want to avoid passing some props through many levels, component composition is often a simpler solution than context.
For example, consider a
Page
component that passes a
user
and
avatarSize
prop several levels down so that deeply nested
Link
and
Avatar
components can read it:
<Pageuser={user}avatarSize={avatarSize}/> // ... which renders ... <PageLayoutuser={user}avatarSize={avatarSize}/> // ... which renders ... <NavigationBaruser={user}avatarSize={avatarSize}/> // ... which renders ... <Linkhref={user.permalink}> <Avataruser={user}size={avatarSize}/> </Link>
It might feel redundant to pass down the
user
and
avatarSize
props through many levels if in the end only the
Avatar
component really needs it. It’s also annoying that whenever the
Avatar
component needs more props from the top, you have to add them at all the intermediate levels too.
One way to solve this issue
without context
is to pass down the
Avatar
component itself so that the intermediate components don’t need to know about the
user
or
avatarSize
props:
// Now, we have: <Pageuser={user}avatarSize={avatarSize}/> // ... which renders ... <PageLayoutuserLink={...}/> // ... which renders ... <NavigationBaruserLink={...}/> // ... which renders ... {props.userLink}
With this change, only the top-most Page component needs to know about the
Link
and
Avatar
components’ use of
user
and
avatarSize
.
This
inversion of control
can make your code cleaner in many cases by reducing the amount of props you need to pass through your application and giving more control to the root components. Such inversion, however, isn’t the right choice in every case; moving more complexity higher in the tree makes those higher-level components more complicated and forces the lower-level components to be more flexible than you may want.
You’re not limited to a single child for a component. You may pass multiple children, or even have multiple separate “slots” for children, as documented here:
This pattern is sufficient for many cases when you need to decouple a child from its immediate parents. You can take it even further with render props if the child needs to communicate with the parent before rendering.
However, sometimes the same data needs to be accessible by many components in the tree, and at different nesting levels. Context lets you “broadcast” such data, and changes to it, to all components below. Common examples where using context might be simpler than the alternatives include managing the current locale, theme, or a data cache.
Creates a Context object. When React renders a component that subscribes to this Context object it will read the current context value from the closest matching
Provider
above it in the tree.
The
defaultValue
argument is
only
used when a component does not have a matching Provider above it in the tree. This default value can be helpful for testing components in isolation without wrapping them. Note: passing
undefined
as a Provider value does not cause consuming components to use
defaultValue
.
Context.Provider
<MyContext.Providervalue={/* some value */}>
Every Context object comes with a Provider React component that allows consuming components to subscribe to context changes.
The Provider component accepts a
value
prop to be passed to consuming components that are descendants of this Provider. One Provider can be connected to many consumers. Providers can be nested to override values deeper within the tree.
All consumers that are descendants of a Provider will re-render whenever the Provider’s
value
prop changes. The propagation from Provider to its descendant consumers (including
.contextType
and
useContext
) is not subject to the
shouldComponentUpdate
method, so the consumer is updated even when an ancestor component skips an update.
Changes are determined by comparing the new and old values using the same algorithm as
Object.is
.
Note
The way changes are determined can cause some issues when passing objects as
value
: see Caveats.
Class.contextType
classMyClassextendsReact.Component{ componentDidMount(){ let value =this.context; /* perform a side-effect at mount using the value of MyContext */ } componentDidUpdate(){ let value =this.context; /* ... */ } componentWillUnmount(){ let value =this.context; /* ... */ } render(){ let value =this.context; /* render something based on the value of MyContext */ } } MyClass.contextType = MyContext;
The
contextType
property on a class can be assigned a Context object created by
React.createContext()
. Using this property lets you consume the nearest current value of that Context type using
this.context
. You can reference this in any of the lifecycle methods including the render function.
Note:
You can only subscribe to a single context using this API. If you need to read more than one see Consuming Multiple Contexts.
If you are using the experimental public class fields syntax, you can use a
static
class field to initialize your
contextType
.
classMyClassextendsReact.Component{ static contextType = MyContext; render(){ let value =this.context; /* render something based on the value */ } }
Context.Consumer
<MyContext.Consumer> {value=>/* render something based on the context value */} </MyContext.Consumer>
A React component that subscribes to context changes. Using this component lets you subscribe to a context within a function component.
Requires a function as a child. The function receives the current context value and returns a React node. The
value
argument passed to the function will be equal to the
value
prop of the closest Provider for this context above in the tree. If there is no Provider for this context above, the
value
argument will be equal to the
defaultValue
that was passed to
createContext()
.
Note
For more information about the ‘function as a child’ pattern, see render props.
Context.displayName
Context object accepts a
displayName
string property. React DevTools uses this string to determine what to display for the context.
For example, the following component will appear as MyDisplayName in the DevTools:
const MyContext = React.createContext(/* some value */); MyContext.displayName ='MyDisplayName'; <MyContext.Provider> // "MyDisplayName.Provider" in DevTools <MyContext.Consumer> // "MyDisplayName.Consumer" in DevTools
Examples
Dynamic Context
A more complex example with dynamic values for the theme:
render(){ // The ThemedButton button inside the ThemeProvider// uses the theme from state while the one outside uses// the default dark themereturn( <Page> <ThemeContext.Providervalue={this.state.theme}><ToolbarchangeTheme={this.toggleTheme}/></ThemeContext.Provider><Section> <ThemedButton/></Section> </Page> ); } }
It is often necessary to update the context from a component that is nested somewhere deeply in the component tree. In this case you can pass a function down through the context to allow consumers to update the context:
theme-context.js
// Make sure the shape of the default value passed to // createContext matches the shape that the consumers expect! exportconst ThemeContext = React.createContext({ theme: themes.dark,toggleTheme:()=>{},});
theme-toggler-button.js
import{ThemeContext}from'./theme-context';
functionThemeTogglerButton(){ // The Theme Toggler Button receives not only the theme// but also a toggleTheme function from the contextreturn( <ThemeContext.Consumer> {({theme, toggleTheme})=>(<button onClick={toggleTheme} style={{backgroundColor: theme.background}}> Toggle Theme </button> )} </ThemeContext.Consumer> ); }
// State also contains the updater function so it will// be passed down into the context providerthis.state ={ theme: themes.light, toggleTheme:this.toggleTheme,}; }
render(){ // The entire state is passed to the providerreturn( <ThemeContext.Providervalue={this.state}><Content/> </ThemeContext.Provider> ); } }
// A component may consume multiple contexts functionContent(){ return( <ThemeContext.Consumer>{theme=>(<UserContext.Consumer>{user=>(<ProfilePageuser={user}theme={theme}/>)}</UserContext.Consumer>)}</ThemeContext.Consumer>); }
If two or more context values are often used together, you might want to consider creating your own render prop component that provides both.
Caveats
Because context uses reference identity to determine when to re-render, there are some gotchas that could trigger unintentional renders in consumers when a provider’s parent re-renders. For example, the code below will re-render all consumers every time the Provider re-renders because a new object is always created for
value
:
React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. The legacy API will be removed in a future major React version. Read the legacy context docs here.