Click the link above to open an online editor. Feel free to make some changes, and see how they affect the output. Most pages in this guide will have editable examples like this one.
How to Read This Guide
In this guide, we will examine the building blocks of React apps: elements and components. Once you master them, you can create complex apps from small reusable pieces.
Tip
This guide is designed for people who prefer
learning concepts step by step
. If you prefer to learn by doing, check out our practical tutorial. You might find this guide and the tutorial complementary to each other.
This is the first chapter in a step-by-step guide about main React concepts. You can find a list of all its chapters in the navigation sidebar. If you’re reading this from a mobile device, you can access the navigation by pressing the button in the bottom right corner of your screen.
Every chapter in this guide builds on the knowledge introduced in earlier chapters.
You can learn most of React by reading the “Main Concepts” guide chapters in the order they appear in the sidebar.
For example, “Introducing JSX” is the next chapter after this one.
Knowledge Level Assumptions
React is a JavaScript library, and so we’ll assume you have a basic understanding of the JavaScript language.
If you don’t feel very confident, we recommend going through a JavaScript tutorial to check your knowledge level
and enable you to follow along this guide without getting lost. It might take you between 30 minutes and an hour, but as a result you won’t have to feel like you’re learning both React and JavaScript at the same time.
Note
This guide occasionally uses some newer JavaScript syntax in the examples. If you haven’t worked with JavaScript in the last few years, these three points should get you most of the way.
Let’s Get Started!
Keep scrolling down, and you’ll find the link to the next chapter of this guide right before the website footer.
Is this page useful?
Edit this page
Introducing JSX – React
Introducing JSX
Consider this variable declaration:
const element =<h1>Hello, world!</h1>;
This funny tag syntax is neither a string nor HTML.
It is called JSX, and it is a syntax extension to JavaScript. We recommend using it with React to describe what the UI should look like. JSX may remind you of a template language, but it comes with the full power of JavaScript.
React embraces the fact that rendering logic is inherently coupled with other UI logic: how events are handled, how the state changes over time, and how the data is prepared for display.
Instead of artificially separating
technologies
by putting markup and logic in separate files, React separates
concerns
with loosely coupled units called “components” that contain both. We will come back to components in a further section, but if you’re not yet comfortable putting markup in JS, this talk might convince you otherwise.
React doesn’t require using JSX, but most people find it helpful as a visual aid when working with UI inside the JavaScript code. It also allows React to show more useful error and warning messages.
With that out of the way, let’s get started!
Embedding Expressions in JSX
In the example below, we declare a variable called
name
and then use it inside JSX by wrapping it in curly braces:
const name ='Josh Perez';const element =<h1>Hello, {name}</h1>;
You can put any valid JavaScript expression inside the curly braces in JSX. For example,
2 + 2
,
user.firstName
, or
formatName(user)
are all valid JavaScript expressions.
In the example below, we embed the result of calling a JavaScript function,
formatName(user)
, into an
<h1>
element.
const user ={ firstName:'Harper', lastName:'Perez' };
const element =( <h1> Hello, {formatName(user)}!</h1> );
Try it on CodePen
We split JSX over multiple lines for readability. While it isn’t required, when doing this, we also recommend wrapping it in parentheses to avoid the pitfalls of automatic semicolon insertion.
JSX is an Expression Too
After compilation, JSX expressions become regular JavaScript function calls and evaluate to JavaScript objects.
This means that you can use JSX inside of
if
statements and
for
loops, assign it to variables, accept it as arguments, and return it from functions:
You may use quotes to specify string literals as attributes:
const element =<ahref="https://www.reactjs.org"> link </a>;
You may also use curly braces to embed a JavaScript expression in an attribute:
const element =<imgsrc={user.avatarUrl}></img>;
Don’t put quotes around curly braces when embedding a JavaScript expression in an attribute. You should either use quotes (for string values) or curly braces (for expressions), but not both in the same attribute.
Warning:
Since JSX is closer to JavaScript than to HTML, React DOM uses
camelCase
property naming convention instead of HTML attribute names.
For example,
class
becomes
className
in JSX, and
tabindex
becomes
tabIndex
.
Specifying Children with JSX
If a tag is empty, you may close it immediately with
/>
, like XML:
const element =<imgsrc={user.avatarUrl}/>;
JSX tags may contain children:
const element =( <div> <h1>Hello!</h1> <h2>Good to see you here.</h2> </div> );
JSX Prevents Injection Attacks
It is safe to embed user input in JSX:
const title = response.potentiallyMaliciousInput; // This is safe: const element =<h1>{title}</h1>;
By default, React DOM escapes any values embedded in JSX before rendering them. Thus it ensures that you can never inject anything that’s not explicitly written in your application. Everything is converted to a string before being rendered. This helps prevent XSS (cross-site-scripting) attacks.
JSX Represents Objects
Babel compiles JSX down to
React.createElement()
calls.
These two examples are identical:
const element =( <h1className="greeting"> Hello, world! </h1> );
const element = React.createElement( 'h1', {className:'greeting'}, 'Hello, world!' );
React.createElement()
performs a few checks to help you write bug-free code but essentially it creates an object like this:
// Note: this structure is simplified const element ={ type:'h1', props:{ className:'greeting', children:'Hello, world!' } };
These objects are called “React elements”. You can think of them as descriptions of what you want to see on the screen. React reads these objects and uses them to construct the DOM and keep it up to date.
We will explore rendering React elements to the DOM in the next section.
Tip:
We recommend using the “Babel” language definition for your editor of choice so that both ES6 and JSX code is properly highlighted.
Elements are the smallest building blocks of React apps.
An element describes what you want to see on the screen:
const element =<h1>Hello, world</h1>;
Unlike browser DOM elements, React elements are plain objects, and are cheap to create. React DOM takes care of updating the DOM to match the React elements.
Let’s say there is a
<div>
somewhere in your HTML file:
<divid="root"></div>
We call this a “root” DOM node because everything inside it will be managed by React DOM.
Applications built with just React usually have a single root DOM node. If you are integrating React into an existing app, you may have as many isolated root DOM nodes as you like.
To render a React element, first pass the DOM element to
ReactDOM.createRoot()
, then pass the React element to
root.render()
:
React elements are immutable. Once you create an element, you can’t change its children or attributes. An element is like a single frame in a movie: it represents the UI at a certain point in time.
With our knowledge so far, the only way to update the UI is to create a new element, and pass it to
root.render()
.
functiontick(){ const element =( <div> <h1>Hello, world!</h1> <h2>It is {newDate().toLocaleTimeString()}.</h2> </div> ); root.render(element);}
setInterval(tick,1000);
Try it on CodePen
It calls
root.render()
every second from a
setInterval()
callback.
Note:
In practice, most React apps only call
root.render()
once. In the next sections we will learn how such code gets encapsulated into stateful components.
We recommend that you don’t skip topics because they build on each other.
React Only Updates What’s Necessary
React DOM compares the element and its children to the previous one, and only applies the DOM updates necessary to bring the DOM to the desired state.
You can verify by inspecting the last example with the browser tools:
Even though we create an element describing the whole UI tree on every tick, only the text node whose contents have changed gets updated by React DOM.
In our experience, thinking about how the UI should look at any given moment, rather than how to change it over time, eliminates a whole class of bugs.
Components let you split the UI into independent, reusable pieces, and think about each piece in isolation. This page provides an introduction to the idea of components. You can find a
detailed component API reference here.
Conceptually, components are like JavaScript functions. They accept arbitrary inputs (called “props”) and return React elements describing what should appear on the screen.
Function and Class Components
The simplest way to define a component is to write a JavaScript function:
This function is a valid React component because it accepts a single “props” (which stands for properties) object argument with data and returns a React element. We call such components “function components” because they are literally JavaScript functions.
You can also use an ES6 class to define a component:
The above two components are equivalent from React’s point of view.
Function and Class components both have some additional features that we will discuss in the next sections.
Rendering a Component
Previously, we only encountered React elements that represent DOM tags:
const element =<div/>;
However, elements can also represent user-defined components:
const element =<Welcomename="Sara"/>;
When React sees an element representing a user-defined component, it passes JSX attributes and children to this component as a single object. We call this object “props”.
For example, this code renders “Hello, Sara” on the page:
const root = ReactDOM.createRoot(document.getElementById('root')); const element =<Welcomename="Sara"/>;root.render(element);
Try it on CodePen
Let’s recap what happens in this example:
We call
root.render()
with the
<Welcome name="Sara" />
element.
React calls the
Welcome
component with
{name: 'Sara'}
as the props.
Our
Welcome
component returns a
<h1>Hello, Sara</h1>
element as the result.
React DOM efficiently updates the DOM to match
<h1>Hello, Sara</h1>
.
Note:
Always start component names with a capital letter.
React treats components starting with lowercase letters as DOM tags. For example,
<div />
represents an HTML div tag, but
<Welcome />
represents a component and requires
Welcome
to be in scope.
To learn more about the reasoning behind this convention, please read JSX In Depth.
Composing Components
Components can refer to other components in their output. This lets us use the same component abstraction for any level of detail. A button, a form, a dialog, a screen: in React apps, all those are commonly expressed as components.
For example, we can create an
App
component that renders
Welcome
many times:
Typically, new React apps have a single
App
component at the very top. However, if you integrate React into an existing app, you might start bottom-up with a small component like
Button
and gradually work your way to the top of the view hierarchy.
Extracting Components
Don’t be afraid to split components into smaller components.
It accepts
author
(an object),
text
(a string), and
date
(a date) as props, and describes a comment on a social media website.
This component can be tricky to change because of all the nesting, and it is also hard to reuse individual parts of it. Let’s extract a few components from it.
The
Avatar
doesn’t need to know that it is being rendered inside a
Comment
. This is why we have given its prop a more generic name:
user
rather than
author
.
We recommend naming props from the component’s own point of view rather than the context in which it is being used.
Extracting components might seem like grunt work at first, but having a palette of reusable components pays off in larger apps. A good rule of thumb is that if a part of your UI is used several times (
Button
,
Panel
,
Avatar
), or is complex enough on its own (
App
,
FeedStory
,
Comment
), it is a good candidate to be extracted to a separate component.
Props are Read-Only
Whether you declare a component as a function or a class, it must never modify its own props. Consider this
sum
function:
functionsum(a, b){ return a + b; }
Such functions are called “pure” because they do not attempt to change their inputs, and always return the same result for the same inputs.
In contrast, this function is impure because it changes its own input:
React is pretty flexible but it has a single strict rule:
All React components must act like pure functions with respect to their props.
Of course, application UIs are dynamic and change over time. In the next section, we will introduce a new concept of “state”. State allows React components to change their output over time in response to user actions, network responses, and anything else, without violating this rule.
Consider the ticking clock example from one of the previous sections. In Rendering Elements, we have only learned one way to update the UI. We call
root.render()
to change the rendered output:
functiontick(){ const element =( <div> <h1>Hello, world!</h1> <h2>It is {newDate().toLocaleTimeString()}.</h2> </div> ); root.render(element);}
setInterval(tick,1000);
Try it on CodePen
In this section, we will learn how to make the
Clock
component truly reusable and encapsulated. It will set up its own timer and update itself every second.
We can start by encapsulating how the clock looks:
However, it misses a crucial requirement: the fact that the
Clock
sets up a timer and updates the UI every second should be an implementation detail of the
Clock
.
Ideally we want to write this once and have the
Clock
update itself:
root.render(<Clock/>);
To implement this, we need to add “state” to the
Clock
component.
State is similar to props, but it is private and fully controlled by the component.
Converting a Function to a Class
You can convert a function component like
Clock
to a class in five steps:
Create an ES6 class, with the same name, that extends
React.Component
.
Add a single empty method to it called
render()
.
Move the body of the function into the
render()
method.
Replace
props
with
this.props
in the
render()
body.
Clock
is now defined as a class rather than a function.
The
render
method will be called each time an update happens, but as long as we render
<Clock />
into the same DOM node, only a single instance of the
Clock
class will be used. This lets us use additional features such as local state and lifecycle methods.
Adding Local State to a Class
We will move the
date
from props to state in three steps:
Replace
this.props.date
with
this.state.date
in the
render()
method:
Note how we save the timer ID right on
this
(
this.timerID
).
While
this.props
is set up by React itself and
this.state
has a special meaning, you are free to add additional fields to the class manually if you need to store something that doesn’t participate in the data flow (like a timer ID).
We will tear down the timer in the
componentWillUnmount()
lifecycle method:
Let’s quickly recap what’s going on and the order in which the methods are called:
When
<Clock />
is passed to
root.render()
, React calls the constructor of the
Clock
component. Since
Clock
needs to display the current time, it initializes
this.state
with an object including the current time. We will later update this state.
React then calls the
Clock
component’s
render()
method. This is how React learns what should be displayed on the screen. React then updates the DOM to match the
Clock
’s render output.
When the
Clock
output is inserted in the DOM, React calls the
componentDidMount()
lifecycle method. Inside it, the
Clock
component asks the browser to set up a timer to call the component’s
tick()
method once a second.
Every second the browser calls the
tick()
method. Inside it, the
Clock
component schedules a UI update by calling
setState()
with an object containing the current time. Thanks to the
setState()
call, React knows the state has changed, and calls the
render()
method again to learn what should be on the screen. This time,
this.state.date
in the
render()
method will be different, and so the render output will include the updated time. React updates the DOM accordingly.
If the
Clock
component is ever removed from the DOM, React calls the
componentWillUnmount()
lifecycle method so the timer is stopped.
Using State Correctly
There are three things you should know about
setState()
.
Do Not Modify State Directly
For example, this will not re-render a component:
// Wrong this.state.comment ='Hello';
Instead, use
setState()
:
// Correct this.setState({comment:'Hello'});
The only place where you can assign
this.state
is the constructor.
State Updates May Be Asynchronous
React may batch multiple
setState()
calls into a single update for performance.
Because
this.props
and
this.state
may be updated asynchronously, you should not rely on their values for calculating the next state.
For example, this code may fail to update the counter:
To fix it, use a second form of
setState()
that accepts a function rather than an object. That function will receive the previous state as the first argument, and the props at the time the update is applied as the second argument:
The merging is shallow, so
this.setState({comments})
leaves
this.state.posts
intact, but completely replaces
this.state.comments
.
The Data Flows Down
Neither parent nor child components can know if a certain component is stateful or stateless, and they shouldn’t care whether it is defined as a function or a class.
This is why state is often called local or encapsulated. It is not accessible to any component other than the one that owns and sets it.
A component may choose to pass its state down as props to its child components:
<FormattedDatedate={this.state.date}/>
The
FormattedDate
component would receive the
date
in its props and wouldn’t know whether it came from the
Clock
’s state, from the
Clock
’s props, or was typed by hand:
functionFormattedDate(props){ return<h2>It is {props.date.toLocaleTimeString()}.</h2>; }
Try it on CodePen
This is commonly called a “top-down” or “unidirectional” data flow. Any state is always owned by some specific component, and any data or UI derived from that state can only affect components “below” them in the tree.
If you imagine a component tree as a waterfall of props, each component’s state is like an additional water source that joins it at an arbitrary point but also flows down.
To show that all components are truly isolated, we can create an
App
component that renders three
<Clock>
s:
Each
Clock
sets up its own timer and updates independently.
In React apps, whether a component is stateful or stateless is considered an implementation detail of the component that may change over time. You can use stateless components inside stateful components, and vice versa.
Another difference is that you cannot return
false
to prevent default behavior in React. You must call
preventDefault
explicitly. For example, with plain HTML, to prevent the default form behavior of submitting, you can write:
When using React, you generally don’t need to call
addEventListener
to add listeners to a DOM element after it is created. Instead, just provide a listener when the element is initially rendered.
When you define a component using an ES6 class, a common pattern is for an event handler to be a method on the class. For example, this
Toggle
component renders a button that lets the user toggle between “ON” and “OFF” states:
You have to be careful about the meaning of
this
in JSX callbacks. In JavaScript, class methods are not bound by default. If you forget to bind
this.handleClick
and pass it to
onClick
,
this
will be
undefined
when the function is actually called.
This is not React-specific behavior; it is a part of how functions work in JavaScript. Generally, if you refer to a method without
()
after it, such as
onClick={this.handleClick}
, you should bind that method.
If calling
bind
annoys you, there are two ways you can get around this. You can use public class fields syntax to correctly bind callbacks:
classLoggingButtonextendsReact.Component{ // This syntax ensures `this` is bound within handleClick.handleClick=()=>{ console.log('this is:',this);};render(){ return( <buttononClick={this.handleClick}> Click me </button> ); } }
This syntax is enabled by default in Create React App.
If you aren’t using class fields syntax, you can use an arrow function in the callback:
render(){ // This syntax ensures `this` is bound within handleClickreturn(<buttononClick={()=>this.handleClick()}> Click me </button> ); } }
The problem with this syntax is that a different callback is created each time the
LoggingButton
renders. In most cases, this is fine. However, if this callback is passed as a prop to lower components, those components might do an extra re-rendering. We generally recommend binding in the constructor or using the class fields syntax, to avoid this sort of performance problem.
Passing Arguments to Event Handlers
Inside a loop, it is common to want to pass an extra parameter to an event handler. For example, if
id
is the row ID, either of the following would work:
The above two lines are equivalent, and use arrow functions and
Function.prototype.bind
respectively.
In both cases, the
e
argument representing the React event will be passed as a second argument after the ID. With an arrow function, we have to pass it explicitly, but with
bind
any further arguments are automatically forwarded.