Markdown conversion of react.dev is ready for download

[](/) [React](/) [v19.2](/versions) Search`⌘``Ctrl``K` [Learn](/learn) [Reference](/reference/react) [Community](/community) [Blog](/blog) ### GET STARTED * [Quick Start](/learn "Quick Start") + [Tutorial: Tic-Tac-Toe](/learn/tutorial-tic-tac-toe "Tutorial: Tic-Tac-Toe") + [Thinking in React](/learn/thinking-in-react "Thinking in React") * [Installation](/learn/installation "Installation") + [Creating a React App](/learn/creating-a-react-app "Creating a React App") + [Build a React App from Scratch](/learn/build-a-react-app-from-scratch "Build a React App from Scratch") + [Add React to an Existing Project](/learn/add-react-to-an-existing-project "Add React to an Existing Project") * [Setup](/learn/setup "Setup") + [Editor Setup](/learn/editor-setup "Editor Setup") + [Using TypeScript](/learn/typescript "Using TypeScript") + [React Developer Tools](/learn/react-developer-tools "React Developer Tools") * [React Compiler](/learn/react-compiler "React Compiler") + [Introduction](/learn/react-compiler/introduction "Introduction") + [Installation](/learn/react-compiler/installation "Installation") + [Incremental Adoption](/learn/react-compiler/incremental-adoption "Incremental Adoption") + [Debugging and Troubleshooting](/learn/react-compiler/debugging "Debugging and Troubleshooting") * ### LEARN REACT * [Describing the UI](/learn/describing-the-ui "Describing the UI") + [Your First Component](/learn/your-first-component "Your First Component") + [Importing and Exporting Components](/learn/importing-and-exporting-components "Importing and Exporting Components") + [Writing Markup with JSX](/learn/writing-markup-with-jsx "Writing Markup with JSX") + [JavaScript in JSX with Curly Braces](/learn/javascript-in-jsx-with-curly-braces "JavaScript in JSX with Curly Braces") + [Passing Props to a Component](/learn/passing-props-to-a-component "Passing Props to a Component") + [Conditional Rendering](/learn/conditional-rendering "Conditional Rendering") + [Rendering Lists](/learn/rendering-lists "Rendering Lists") + [Keeping Components Pure](/learn/keeping-components-pure "Keeping Components Pure") + [Your UI as a Tree](/learn/understanding-your-ui-as-a-tree "Your UI as a Tree") * [Adding Interactivity](/learn/adding-interactivity "Adding Interactivity") + [Responding to Events](/learn/responding-to-events "Responding to Events") + [State: A Component's Memory](/learn/state-a-components-memory "State: A Component's Memory") + [Render and Commit](/learn/render-and-commit "Render and Commit") + [State as a Snapshot](/learn/state-as-a-snapshot "State as a Snapshot") + [Queueing a Series of State Updates](/learn/queueing-a-series-of-state-updates "Queueing a Series of State Updates") + [Updating Objects in State](/learn/updating-objects-in-state "Updating Objects in State") + [Updating Arrays in State](/learn/updating-arrays-in-state "Updating Arrays in State") * [Managing State](/learn/managing-state "Managing State") + [Reacting to Input with State](/learn/reacting-to-input-with-state "Reacting to Input with State") + [Choosing the State Structure](/learn/choosing-the-state-structure "Choosing the State Structure") + [Sharing State Between Components](/learn/sharing-state-between-components "Sharing State Between Components") + [Preserving and Resetting State](/learn/preserving-and-resetting-state "Preserving and Resetting State") + [Extracting State Logic into a Reducer](/learn/extracting-state-logic-into-a-reducer "Extracting State Logic into a Reducer") + [Passing Data Deeply with Context](/learn/passing-data-deeply-with-context "Passing Data Deeply with Context") + [Scaling Up with Reducer and Context](/learn/scaling-up-with-reducer-and-context "Scaling Up with Reducer and Context") * [Escape Hatches](/learn/escape-hatches "Escape Hatches") + [Referencing Values with Refs](/learn/referencing-values-with-refs "Referencing Values with Refs") + [Manipulating the DOM with Refs](/learn/manipulating-the-dom-with-refs "Manipulating the DOM with Refs") + [Synchronizing with Effects](/learn/synchronizing-with-effects "Synchronizing with Effects") + [You Might Not Need an Effect](/learn/you-might-not-need-an-effect "You Might Not Need an Effect") + [Lifecycle of Reactive Effects](/learn/lifecycle-of-reactive-effects "Lifecycle of Reactive Effects") + [Separating Events from Effects](/learn/separating-events-from-effects "Separating Events from Effects") + [Removing Effect Dependencies](/learn/removing-effect-dependencies "Removing Effect Dependencies") + [Reusing Logic with Custom Hooks](/learn/reusing-logic-with-custom-hooks "Reusing Logic with Custom Hooks") [Learn React](/learn) Copy pageCopy Quick Start =========== Welcome to the React documentation! This page will give you an introduction to 80% of the React concepts that you will use on a daily basis. ### You will learn * How to create and nest components * How to add markup and styles * How to display data * How to render conditions and lists * How to respond to events and update the screen * How to share data between components Creating and nesting components ------------------------------- React apps are made out of *components*. A component is a piece of the UI (user interface) that has its own logic and appearance. A component can be as small as a button, or as large as an entire page. React components are JavaScript functions that return markup: ``` function MyButton() { return ( <button>I'm a button</button> ); } ``` Now that you’ve declared `MyButton`, you can nest it into another component: ``` export default function MyApp() { return ( <div> <h1>Welcome to my app</h1> <MyButton /> </div> ); } ``` Notice that `<MyButton />` starts with a capital letter. That’s how you know it’s a React component. React component names must always start with a capital letter, while HTML tags must be lowercase. Have a look at the result: App.js App.js ReloadClear[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox") ``` function MyButton() { return ( <button> I'm a button </button> ); } export default function MyApp() { return ( <div> <h1>Welcome to my app</h1> <MyButton /> </div> ); } ``` Show more The `export default` keywords specify the main component in the file. If you’re not familiar with some piece of JavaScript syntax, [MDN](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export) and [javascript.info](https://javascript.info/import-export) have great references. Writing markup with JSX ----------------------- The markup syntax you’ve seen above is called *JSX*. It is optional, but most React projects use JSX for its convenience. All of the [tools we recommend for local development](/learn/installation) support JSX out of the box. JSX is stricter than HTML. You have to close tags like `<br />`. Your component also can’t return multiple JSX tags. You have to wrap them into a shared parent, like a `<div>...</div>` or an empty `<>...</>` wrapper: ``` function AboutPage() { return ( <> <h1>About</h1> <p>Hello there.<br />How do you do?</p> </> ); } ``` If you have a lot of HTML to port to JSX, you can use an [online converter.](https://transform.tools/html-to-jsx) Adding styles ------------- In React, you specify a CSS class with `className`. It works the same way as the HTML [`class`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) attribute: ``` <img className="avatar" /> ``` Then you write the CSS rules for it in a separate CSS file: ``` /* In your CSS */ .avatar { border-radius: 50%; } ``` React does not prescribe how you add CSS files. In the simplest case, you’ll add a [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) tag to your HTML. If you use a build tool or a framework, consult its documentation to learn how to add a CSS file to your project. Displaying data --------------- JSX lets you put markup into JavaScript. Curly braces let you “escape back” into JavaScript so that you can embed some variable from your code and display it to the user. For example, this will display `user.name`: ``` return ( <h1> {user.name} </h1> ); ``` You can also “escape into JavaScript” from JSX attributes, but you have to use curly braces *instead of* quotes. For example, `className="avatar"` passes the `"avatar"` string as the CSS class, but `src={user.imageUrl}` reads the JavaScript `user.imageUrl` variable value, and then passes that value as the `src` attribute: ``` return ( <img className="avatar" src={user.imageUrl} /> ); ``` You can put more complex expressions inside the JSX curly braces too, for example, [string concatenation](https://javascript.info/operators#string-concatenation-with-binary): App.js App.js ReloadClear[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox") ``` const user = { name: 'Hedy Lamarr', imageUrl: 'https://react.dev/images/docs/scientists/yXOvdOSs.jpg', imageSize: 90, }; export default function Profile() { return ( <> <h1>{user.name}</h1> <img className="avatar" src={user.imageUrl} alt={'Photo of ' + user.name} style={{ width: user.imageSize, height: user.imageSize }} /> </> ); } ``` Show more In the above example, `style={{}}` is not a special syntax, but a regular `{}` object inside the `style={ }` JSX curly braces. You can use the `style` attribute when your styles depend on JavaScript variables. Conditional rendering --------------------- In React, there is no special syntax for writing conditions. Instead, you’ll use the same techniques as you use when writing regular JavaScript code. For example, you can use an [`if`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/if...else) statement to conditionally include JSX: ``` let content; if (isLoggedIn) { content = <AdminPanel />; } else { content = <LoginForm />; } return ( <div> {content} </div> ); ``` If you prefer more compact code, you can use the [conditional `?` operator.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator) Unlike `if`, it works inside JSX: ``` <div> {isLoggedIn ? ( <AdminPanel /> ) : ( <LoginForm /> )} </div> ``` When you don’t need the `else` branch, you can also use a shorter [logical `&&` syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND#short-circuit_evaluation): ``` <div> {isLoggedIn && <AdminPanel />} </div> ``` All of these approaches also work for conditionally specifying attributes. If you’re unfamiliar with some of this JavaScript syntax, you can start by always using `if...else`. Rendering lists --------------- You will rely on JavaScript features like [`for` loop](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for) and the [array `map()` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) to render lists of components. For example, let’s say you have an array of products: ``` const products = [ { title: 'Cabbage', id: 1 }, { title: 'Garlic', id: 2 }, { title: 'Apple', id: 3 }, ]; ``` Inside your component, use the `map()` function to transform an array of products into an array of `<li>` items: ``` const listItems = products.map(product => <li key={product.id}> {product.title} </li> ); return ( <ul>{listItems}</ul> ); ``` Notice how `<li>` has a `key` attribute. For each item in a list, you should pass a string or a number that uniquely identifies that item among its siblings. Usually, a key should be coming from your data, such as a database ID. React uses your keys to know what happened if you later insert, delete, or reorder the items. App.js App.js ReloadClear[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox") ``` const products = [ { title: 'Cabbage', isFruit: false, id: 1 }, { title: 'Garlic', isFruit: false, id: 2 }, { title: 'Apple', isFruit: true, id: 3 }, ]; export default function ShoppingList() { const listItems = products.map(product => <li key={product.id} style={{ color: product.isFruit ? 'magenta' : 'darkgreen' }} > {product.title} </li> ); return ( <ul>{listItems}</ul> ); } ``` Show more Responding to events -------------------- You can respond to events by declaring *event handler* functions inside your components: ``` function MyButton() { function handleClick() { alert('You clicked me!'); } return ( <button onClick={handleClick}> Click me </button> ); } ``` Notice how `onClick={handleClick}` has no parentheses at the end! Do not *call* the event handler function: you only need to *pass it down*. React will call your event handler when the user clicks the button. Updating the screen ------------------- Often, you’ll want your component to “remember” some information and display it. For example, maybe you want to count the number of times a button is clicked. To do this, add *state* to your component. First, import [`useState`](/reference/react/useState) from React: ``` import { useState } from 'react'; ``` Now you can declare a *state variable* inside your component: ``` function MyButton() { const [count, setCount] = useState(0); // ... ``` You’ll get two things from `useState`: the current state (`count`), and the function that lets you update it (`setCount`). You can give them any names, but the convention is to write `[something, setSomething]`. The first time the button is displayed, `count` will be `0` because you passed `0` to `useState()`. When you want to change state, call `setCount()` and pass the new value to it. Clicking this button will increment the counter: ``` function MyButton() { const [count, setCount] = useState(0); function handleClick() { setCount(count + 1); } return ( <button onClick={handleClick}> Clicked {count} times </button> ); } ``` React will call your component function again. This time, `count` will be `1`. Then it will be `2`. And so on. If you render the same component multiple times, each will get its own state. Click each button separately: App.js App.js ReloadClear[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox") ``` import { useState } from 'react'; export default function MyApp() { return ( <div> <h1>Counters that update separately</h1> <MyButton /> <MyButton /> </div> ); } function MyButton() { const [count, setCount] = useState(0); function handleClick() { setCount(count + 1); } return ( <button onClick={handleClick}> Clicked {count} times </button> ); } ``` Show more Notice how each button “remembers” its own `count` state and doesn’t affect other buttons. Using Hooks ----------- Functions starting with `use` are called *Hooks*. `useState` is a built-in Hook provided by React. You can find other built-in Hooks in the [API reference.](/reference/react) You can also write your own Hooks by combining the existing ones. Hooks are more restrictive than other functions. You can only call Hooks *at the top* of your components (or other Hooks). If you want to use `useState` in a condition or a loop, extract a new component and put it there. Sharing data between components ------------------------------- In the previous example, each `MyButton` had its own independent `count`, and when each button was clicked, only the `count` for the button clicked changed:   Initially, each `MyButton`’s `count` state is `0`   The first `MyButton` updates its `count` to `1` However, often you’ll need components to *share data and always update together*. To make both `MyButton` components display the same `count` and update together, you need to move the state from the individual buttons “upwards” to the closest component containing all of them. In this example, it is `MyApp`:   Initially, `MyApp`’s `count` state is `0` and is passed down to both children   On click, `MyApp` updates its `count` state to `1` and passes it down to both children Now when you click either button, the `count` in `MyApp` will change, which will change both of the counts in `MyButton`. Here’s how you can express this in code. First, *move the state up* from `MyButton` into `MyApp`: ``` export default function MyApp() { const [count, setCount] = useState(0); function handleClick() { setCount(count + 1); } return ( <div> <h1>Counters that update separately</h1> <MyButton /> <MyButton /> </div> ); } function MyButton() { // ... we're moving code from here ... } ``` Then, *pass the state down* from `MyApp` to each `MyButton`, together with the shared click handler. You can pass information to `MyButton` using the JSX curly braces, just like you previously did with built-in tags like `<img>`: ``` export default function MyApp() { const [count, setCount] = useState(0); function handleClick() { setCount(count + 1); } return ( <div> <h1>Counters that update together</h1> <MyButton count={count} onClick={handleClick} /> <MyButton count={count} onClick={handleClick} /> </div> ); } ``` The information you pass down like this is called *props*. Now the `MyApp` component contains the `count` state and the `handleClick` event handler, and *passes both of them down as props* to each of the buttons. Finally, change `MyButton` to *read* the props you have passed from its parent component: ``` function MyButton({ count, onClick }) { return ( <button onClick={onClick}> Clicked {count} times </button> ); } ``` When you click the button, the `onClick` handler fires. Each button’s `onClick` prop was set to the `handleClick` function inside `MyApp`, so the code inside of it runs. That code calls `setCount(count + 1)`, incrementing the `count` state variable. The new `count` value is passed as a prop to each button, so they all show the new value. This is called “lifting state up”. By moving state up, you’ve shared it between components. App.js App.js ReloadClear[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox") ``` import { useState } from 'react'; export default function MyApp() { const [count, setCount] = useState(0); function handleClick() { setCount(count + 1); } return ( <div> <h1>Counters that update together</h1> <MyButton count={count} onClick={handleClick} /> <MyButton count={count} onClick={handleClick} /> </div> ); } function MyButton({ count, onClick }) { return ( <button onClick={onClick}> Clicked {count} times </button> ); } ``` Show more Next Steps ---------- By now, you know the basics of how to write React code! Check out the [Tutorial](/learn/tutorial-tic-tac-toe) to put them into practice and build your first mini-app with React. [NextTutorial: Tic-Tac-Toe](/learn/tutorial-tic-tac-toe) --- On this page ------------ * [Overview](#) * [Creating and nesting components](#components) * [Writing markup with JSX](#writing-markup-with-jsx) * [Adding styles](#adding-styles) * [Displaying data](#displaying-data) * [Conditional rendering](#conditional-rendering) * [Rendering lists](#rendering-lists) * [Responding to events](#responding-to-events) * [Updating the screen](#updating-the-screen) * [Using Hooks](#using-hooks) * [Sharing data between components](#sharing-data-between-components) * [Next Steps](#next-steps)