# Building client-side apps with React
React makes dealing with the DOM in JavaScript more like writing HTML. It helps package up elements into "components" so you can divide your UI up into reusable pieces. You can try out the examples online by creating a new [React playground](https://vite.new/react-ts).
### Quick summary
A lot of React concepts are explained in detail below. If you just want to get started quickly here's a code sample with the most important features:
```tsx
import React, { useState } from "react";
import ReactDOM from "react-dom/client";
function Counter() {
// Calling the `setCount` with a new value re-runs your component
const [count, setCount] = useState(0);
return ;
}
// Any properties passed to the component are available on the `props` object
function Title(props: { id: string; children: React.ReactNode }) {
return
{props.children}
;
}
function App() {
return (
Hello world
);
}
// React handles all DOM element creation/updates—you just call `render` once
const root = ReactDOM.createRoot(document.querySelector("#root")!);
root.render(
);
```
### React elements
Interacting with the DOM can be awkward when you just want to render an element:
```ts
const title = document.createElement("h1");
title.className = "title";
title.textContent = "Hello world!";
```
This is frustrating because there is a simpler, more declarative way to describe elements—HTML:
```html
Hello world!
```
Unfortunately we can't use HTML inside JavaScript files. HTML is a static markup language—it can't create elements dynamically as a user interacts with our app. This is where React comes in:
```tsx
const title =
Hello world!
;
```
This variable is a *React element*. It's created using a special syntax called [JSX](https://react.dev/learn/writing-markup-with-jsx) that lets us write HTML-like elements within our JavaScript.
The example above will be transformed into a JS function call that returns an object:
```ts
const title = _jsx("h1", { className: "title", children: "Hello world!" });
/*
* Over-simplified for examples sake:
{
type: "h1",
props: {
className: "title",
children: "Hello world!",
},
}
*/
```
### Templating dynamic values
JSX supports inserting dynamic values into your elements. It uses a similar syntax to JS template literals: anything inside curly brackets will be evaluated as a JS expression:
```tsx
const title =
Hello {5 * 5}
;
//
Hello 25
```
You can do all kinds of JS stuff inside the curly brackets, like referencing other variables, or conditional expressions.
```tsx
const name = "oli";
const title =
Hello {name}
;
//
Hello oli
```
```tsx
const number = Math.random();
const result =
{number > 0.5 ? "You won!" : "You lost"}
;
// 50% of the time:
You won!
// the other 50%:
You lost
```
#### Note on expressions
You can put any valid JS *expression* inside the curly brackets. An expression is code that *resolves to a value*. I.e. you can assign it to a variable. These are all valid expressions:
```ts
const number = 5 + 4 * 9;
const isEven = number % 2 === 0;
const message = isEven ? "It is even" : "It is odd";
```
This is *not* a valid expression:
```ts
const message = if (isEven) { "It is even" } else { "It is odd" };
// this is not valid JS and will cause an error
```
`if` blocks are *statements*, not expressions. The main impact of this is that you have to use ternaries instead of `if` statements inside JSX.
***
### React components
React elements aren't very useful on their own, since they're just static objects. To build an interface we need something reusable and dynamic, like functions.
A *React component* is a function that returns a React element.
```tsx
function Title() {
return
Hello world!
;
}
```
#### Valid elements
Your components don't *have* to return JSX. A React element can be JSX, or a string, number, boolean, or array of elements. Returning `null`, `undefined`, `false` or `""` will cause your component to render nothing.
Returning an array is especially useful for [rendering lists](https://react.dev/learn/rendering-lists) from data:
```tsx
const fruits = ["apple", "orange", "banana"];
function FruitList() {
const items = fruits.map((fruit) =>
{fruit}
);
return
{items}
;
}
```
Array items in JSX must have a special unique [`key` prop](https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key) so React can keep track of the order if the data changes.
#### Composing components
Components are useful because JSX allows us to compose them together just like HTML elements. We can use our `Title` component as JSX within another component:
```tsx
function Title() {
return
Hello world!
;
}
function Page() {
return (
);
}
```
When we use a component in JSX (``) React will find the corresponding `Title` function, call it, and use whatever element it returns.
### Customising components
A component where everything is hard-coded isn't very useful. Functions are most useful when they take *arguments*. Passing different arguments lets us change what the function returns each time we call it.
JSX supports passing arguments to your components. It does this using the same syntax as HTML:
```tsx
/**
* The above JSX is transformed into this:
* _jsx(Title, { name: "oli" });
*/
```
Most people name this object "props" in their component function:
```tsx
function Title(props) {
console.log(props); // { name: "oli" }
return
Hello world
;
}
```
We can use these props within your components to customise them. For example we can insert them into our JSX:
```tsx
function Title(props) {
return
Hello {props.name}
;
}
```
Now we can re-use our `Title` component to render different DOM elements:
```tsx
function Page() {
return (
);
}
/**
*
*
Hello oli
*
Hello sam
*
*/
```
#### Typing our props
We need to define the type of the props object so TypeScript can check we're using the component correctly. We can do this in the same way we would type any object:
```tsx
function Title(props: { name: string }) {
return
Hello {props.name}
;
}
```
If you have several props it can be more readable to extract the type to an alias:
```tsx
type TitleProps = { name: string };
function Title(props: TitleProps) {
return
Hello {props.name}
;
}
```
The React docs have a page on [using TypeScript with React](https://react.dev/learn/typescript), which can be helpful.
#### Non-string props
Since JSX is JavaScript it supports passing *any* valid JS expression to your components, not just strings. To pass JS values as props you use **curly brackets**, just like interpolating expressions inside tags.
```tsx
function Page() {
const fullname = "oliver" + " phillips";
return (
);
}
/**
*
*
Hello oliver phillips
*
Hello 25
*
*/
```
#### Children
It would be nice if we could nest our components just like HTML. Right now this won't work, since we hard-coded the text inside our `
`:
```tsx
Hello oli
/**
* The above JSX is transformed into this:
* _jsx(Title, { children: "hello oli" });
*/
```
JSX supports a special prop to achieve this: `children`. Whatever value you put *between* JSX tags will be passed to the component function as a prop named `children`.
You can then access and use it exactly like any other prop.
```tsx
function Title(props) {
return
{props.children}
;
}
```
Now this JSX will work as we expect:
```tsx
Hello oli
//
Hello oli
```
This is quite powerful, as you can now nest your components to build up more complex DOM elements.
```tsx
// pretend we have defined Image and BigText components above
<Image src="hand-wave.svg" />
<BigText>Hello oli</BigText>
```
#### Typing the `children` prop
Since the children of an element can be almost anything React has built-in type for it: `React.ReactNode`.
```tsx
type TitleProps = { children: React.ReactNode };
function Title(props) {
return
{props.children}
;
}
```
### Rendering to the page
You may be wondering how we get these components to actually show up on the page. React manages the DOM for you, so you don't need to use `document.createElement`/`.appendChild`.
React consists of two libraries—the main `React` library and a specific `ReactDOM` library for rendering to the DOM. We can use `ReactDOM` to render a component to the DOM.
It's common practice to have a single top-level `App` component that contains all the rest of the UI.
```tsx
import ReactDOM from "react-dom/client";
function App() {
return (
Hello world!
Welcome to my page
);
}
const div = document.querySelector("#root")!; // The `!` tells TS it's definitely not null
const root = ReactDOM.createRoot(div);
root.render();
```
***
### Event listeners
JSX makes adding event listeners simple—you add them inline on the element you want to target. They are always formatted as "on" followed by the camelCased event name (`onClick`, `onKeyDown` etc):
```tsx
function Alerter() {
return ;
}
```
### React state
An app can't do much with static DOM elements—we need a way to create values that can *change* and trigger updates to the UI.
React provides a special "hook" function called `useState` to create a stateful value. When you update the value React will automatically re-render the component to ensure the UI stays up-to-date.
When this button is clicked we want the count to go up one:
```tsx
function Counter() {
const count = 0;
return ;
}
```
We need to use the `useState` hook. It takes the initial state value as an argument, and returns an array. This array contains the state value itself, and a function that lets you *update* the state value.
```tsx
import { useState } from "react";
function Counter() {
const stateArray = useState(0);
const count = stateArray[0];
const setCount = stateArray[1];
return ;
}
```
It's common to use destructuring to shorten this:
```tsx
import { useState } from "react";
function Counter(props) {
const [count, setCount] = useState(0);
return ;
}
```
If we call `setCount(1)` React will re-run our `Counter` component, but this time the `count` variable will be `1` instead of `0`. This is how React keeps your UI in sync with the state.
#### Lifting state up
React components encapsulate their state—it lives inside that function and can't be accessed elsewhere. Sometimes however you need several components to read the same value. In these cases you should ["lift the state up"](https://react.dev/learn/sharing-state-between-components) to a shared parent component:
```tsx
function Counter() {
const [count, setCount] = useState(0);
return (
{count}
);
}
function FancyButton(props) {
function increment() {
props.setCount(props.count + 1);
}
return (
);
}
function FancyText(props) {
return
{props.children}
;
}
```
Here `FancyButton` and `FancyText` both need access to the state, so we move it up to `Counter` and pass it down via props. That way both components can read/update the same state value.
#### Typing state
TS can mostly infer state types from the initial value you provide. In the `Counter` example above it will infer `count` to be of type `number`, since the initial value is `0`. We can explicitly provide a type by passing a generic to `useState`:
```ts
const [count, setCount] = useState(0);
```
That's not useful here, but can be necessary if for example you wish to constrain the type:
```ts
type Status = "loading" | "complete" | "error";
const [status, setStatus] = useState("loading");
```
We need to define a type for the state setter function when we pass it down to another component as a prop (like the `FancyButton` example above). Since updating state does some React magic behind the scenes we can't just write a normal function type: we must use React's built-in types:
```tsx
type FancyButtonProps = {
count: number;
setCount: React.Dispatch>;
};
function FancyButton(props: FancyButtonProps) {
function increment() {
props.setCount(props.count + 1);
}
return (
);
}
```
The `React.Dispatch>` is a little wild because of the triple-nested generic, but the only part you ever need to change is the final generic (`` here). This should be the type of the actual state value.
#### Updates based on previous state
Sometimes your update depends on the previous state value. For example updating the count inside an interval. In these cases you can [pass a *function*](https://react.dev/apis/react/useState#updating-state-based-on-the-previous-state) to the state updater. React will call this function with the previous state, and whatever you return will be set as the new state.
```tsx
// ...
const [count, setCount] = useState(0);
// ...
setInterval(() => {
setCount((previousCount) => {
const nextCount = previousCount + 1;
return nextCount;
});
}, 1000);
// or more concisely:
// setInterval(() => setCount(c => c + 1), 1000);
```
We cannot just reference `count`, since this is `0` when the interval is created. It would just do `0 + 1` over and over (so the count would be stuck at `1`).
***
### Form fields
React apps still use the DOM, so forms work the same way:
```tsx
function ChooseName() {
const [name, setName] = useState("");
function updateName(event) {
event.preventDefault();
setName(event.target.username.value);
}
return (
);
}
```
#### Typing DOM events
TS can infer the type of the event parameter in inline handlers. For example:
```tsx
```
Here `event` will be inferred as `React.MouseEvent`.
When you define event handlers as separate function (like the `updateName` example above) you will need to manually provide this type. React [defines types for most DOM events](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/b580df54c0819ec9df62b0835a315dd48b8594a9/types/react/index.d.ts#L1247C1-L1373)—you just need to pass in the type of DOM element it will be triggered for. For example:
```ts
function updateName(event: React.FormEvent) {
event.preventDefault();
setName(event.target.username.value);
}
```
Often the easiest way to find the type is to write the handler inline first, then copy the type that is inferred.
#### Controlled components
React tries to normalise the different form fields, so behaviour is consistent across e.g. `` and `