React Documentation

Getting Started

React is a JavaScript library for building user interfaces. Learn what React is all about on our homepage or in the tutorial.

Try React

React has been designed from the start for gradual adoption, and you can use as little or as much React as you need. Whether you want to get a taste of React, add some interactivity to a simple HTML page, or start a complex React-powered app, the links in this section will help you get started.

Online Playgrounds

If you're interested in playing around with React, you can use an online code playground. Try a Hello World template on CodePen, CodeSandbox, or Stackblitz.

If you prefer to use your own text editor, you can also download this HTML file, edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so we’d only recommend using this for simple demos

Add React to a Website

You can add React to an HTML page in one minute. You can then either gradually expand its presence, or keep it contained to a few dynamic widgets.

Create a New React App

When starting a React project, a simple HTML page with script tags might still be the best option. It only takes a minute to set up!

As your application grows, you might want to consider a more integrated setup. There are several JavaScript toolchains we recommend for larger applications. Each of them can work with little to no configuration and lets you take full advantage of the rich React ecosystem.
Learn how.

Learn React

People come to React from different backgrounds and with different learning styles. Whether you prefer a more theoretical or a practical approach, we hope you’ll find this section helpful.

If you prefer to learn by doing, start with our practical tutorial.
If you prefer to learn concepts step by step, start with our guide to main concepts.

Like any unfamiliar technology, React does have a learning curve. With practice and some patience, you will get the hang of it.

First Examples

The React homepage contains a few small React examples with a live editor. Even if you don’t know anything about React yet, try changing their code and see how it affects the result.

React for Beginners

If you feel that the React documentation goes at a faster pace than you’re comfortable with, check out this overview of React by Tania Rascia. It introduces the most important React concepts in a detailed, beginner-friendly way. Once you’re done, give the documentation another try!

React for Designers

If you’re coming from a design background, these resources are a great place to get started.

JavaScript Resources

The React documentation assumes some familiarity with programming in the JavaScript language. You don’t have to be an expert, but it’s harder to learn both React and JavaScript at the same time.

We recommend going through this JavaScript overview to check your knowledge level. It will take you between 30 minutes and an hour but you will feel more confident learning React.

Tip

Whenever you get confused by something in JavaScript, MDN and javascript.info are great websites to check. There are also community support forums where you can ask for help.

Add React to a Website

React has been designed from the start for gradual adoption, and you can use as little or as much React as you need. Perhaps you only want to add some “sprinkles of interactivity” to an existing page. React components are a great way to do that.

The majority of websites aren’t, and don’t need to be, single-page apps. With a few lines of code and no build tooling, try React in a small part of your website. You can then either gradually expand its presence, or keep it contained to a few dynamic widgets.

Add React in One Minute

In this section, we will show how to add a React component to an existing HTML page. You can follow along with your own website, or create an empty HTML file to practice.

There will be no complicated tools or install requirements — to complete this section, you only need an internet connection, and a minute of your time.

Step 1: Add a DOM Container to the HTML

First, open the HTML page you want to edit. Add an empty

tag to mark the spot where you want to display something with React. For example:

<div id="like_button_container"></div>

We gave this <div> a unique id HTML attribute. This will allow us to find it from the JavaScript code later and display a React component inside of it.

Tip

You can place a “container” <div> like this anywhere inside the <body> tag. You may have as many independent DOM containers on one page as you need. They are usually empty — React will replace any existing content inside DOM containers.

Step 2: Add the Script Tags

Next, add three <script> tags to the HTML page right before the closing </body> tag:


            <!-- ... other HTML ... -->

            

            <!-- Load React. -->

            <!-- Note: when deploying, replace "development.js" with "production.min.js". -->

            <script src="https://unpkg.com/react@18/umd/react.development.js" crossorigin></script>

            <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js" crossorigin></script>

            

            <!-- Load our React component. -->

            <script src="like_button.js"></script>

            

            </body>

The first two tags load React. The third one will load your component code.

Step 3: Create a React Component

Create a file called like_button.js next to your HTML page.

Open this starter code and paste it into the file you created.

Tip

This code defines a React component called LikeButton. Don’t worry if you don’t understand it yet — we’ll cover the building blocks of React later in our hands-on tutorial and main concepts guide. For now, let’s just get it showing on the screen!

After the starter code, add three lines to the bottom of like_button.js:


            // ... the starter code you pasted ...

            

            const domContainer = document.querySelector('#like_button_container');

            const root = ReactDOM.createRoot(domContainer);

            root.render(e(LikeButton));

These lines of code find the <div> we added to our HTML in the first step, and then display our “Like” button React component inside of it.

That's It!

There is no step four. You have just added the first React component to your website.

View the full example source code

Download the full example (2KB zipped)

Create a New React App

This page describes a few popular React toolchains which help with tasks like:

Scaling to many files and components.
Using third-party libraries from npm.
Detecting common mistakes early.
Live-editing CSS and JS in development.
Optimizing the output for production.

The toolchains recommended on this page don’t require configuration to get started.

You Might Not Need a Toolchain

If you don’t experience the problems described above or don’t feel comfortable using JavaScript tools yet, consider adding React as a plain <script> tag on an HTML page, optionally with JSX.

Create React App

Create React App is a comfortable environment for learning React, and is the best way to start building a new single-page application in React.

It sets up your development environment so that you can use the latest JavaScript features, provides a nice developer experience, and optimizes your app for production. You’ll need to have Node >= 14.0.0 and npm >= 5.6 on your machine. To create a project, run:


                npx create-react-app my-app

                cd my-app

                npm start

Note

npx on the first line is not a typo — it’s a package runner tool that comes with npm 5.2+.

Hello World

The smallest React example looks like this:


            const root = ReactDOM.createRoot(document.getElementById('root'));

            root.render(<h1>Hello, world!</h1>);

It displays a heading saying “Hello, world!” on the page.

Try it on CodePen

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 to learn 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.

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.

JSX produces React “elements”. We will explore rendering them to the DOM in the next section. Below, you can find the basics of JSX necessary to get you started.

Why JSX?

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.


                function formatName(user) {

                     return user.firstName + ' ' + user.lastName;

                }

                

                const user = {

                     firstName: 'Harper',

                     lastName: 'Perez'

                };

                

                const element = ( 

                 <h1>

                  Hello, {formatName(user)}!

                 </h1>

                );