New React Docs

[rachelnabors]

Updated September 29, 2022! We're close to completing the remaining pages, and there is now a link to the Beta site from the main site.

---

Updated October 22, 2021! We have released React Docs Beta. See more details in the announcement and leave feedback on this issue!

---

Updated June 10, 2021! Full details in this comment.

---

Over the next months, we're planning to rebuild our website with fresh content!

Since Hooks have become increasingly popular in the React community, we have heard from confused learners as well as industry trainers asking why the docs are still so class component-centric. Additionally, while more and more educational materials for React are being created every day, there are still things not being taught because we have failed to explain them well.

We want to make reactjs.org the best place to grok React. We want to be there with you from the moment you make your first component, to well into your career as your React knowledge deepens and advances.

The plan

The new docs will teach React Hooks-first, with a focus on “how to think in React” and deeply grok React over building an app in React. (There are many amazing frameworks with full stacks, tutorials, and learning paths we will point people to for a holistic kickstart.) We’ll have a section on React’s core concepts as well as an expanded and concise API reference.

Anyone can learn React

We want React to be accessible to learners of all backgrounds, so we’re going to expand our coverage to include:

• explanations of some of the more complex programming concepts for folks just diving into computer science (welcome welcome!)
• visual explanations and diagrams for people with visual learning styles
• interactive code examples for people who learn by doing
• early and integrated use of React DevTools and lint rules, to prepare the learner for real world debugging

Because so much of this is going to be new content with a different structure, most of the existing documentation will be archived rather than edited. (Don’t worry: you’ll still be able to access our “class”-ic docs for legacy and migration work and we’ll set up redirects where appropriate!)

To ensure consistent voice and narrative, Dan and Rachel will start by writing the core of the new content, but later on we will be accepting community contributions as usual when everything is in place.

We’re also surveying the community to learn how you use reactjs.org so we can see what’s working and what isn’t. If you have five minutes to spare, we’d love if you could take our 2020 community survey!

Translations

With the help of our wonderful translators, more people than ever before have access to React. We want to thank our translation community so much for their hard work and commitment to React's v1 docs. Their efforts have allowed people all over the world to learn, teach, and build with React, and we will need their help more than ever when v2 launches. We’ll reach out to start coordinating as soon as we have content ready to translate.

What to expect

We’re aiming to launch the new docs in early 2021. We've got the initial structure in place and are working on a new site we're wrangling design resources for. We've sharing early stage outlines with individual teachers and learners to gather feedback, and as we have more and more content prepared, we will start publishing previews to gather even more feedback. This is an iterative process, and we want to get this right! In the meantime, if you’re looking for the React docs with Hooks, check out this community-maintained version of the docs where all examples use Hooks.

Help us help you! Take the survey!

Want to help? We’re running a survey to help better understand and measure the React community, your needs, and where we can do better. If you have a moment, you’ll be helping us a lot! Please take our survey—and share it with your team, classmates, other people who use and learn React.

[gaearon]

Alternatively we can have banners on individual pages whose content has been superseded.

[raulriera]

Loving the docs, they are extremely useful! I believe there is an odd situation in this one https://beta.reactjs.org/learn/updating-arrays-in-state

push() will mutate an array, which you don’t want:

This first example and the next one produce the same result, shouldn't the first one not create renders? I imagine line 17 is causing the render, but seemed unintuitive that both the right and wrong example work

[galliumsoft]

I love the speed at which the react beta docs loads. Is the code repo for the beta docs open source? If so, where can I see the repo. Would like to study more the best practices there. thanks.

[jakubdrozdek]

I love the speed at which the react beta docs loads. Is the code repo for the beta docs open source? If so, where can I see the repo. Would like to study more the best practices there. thanks.

Currently, beta docs are a part of the React Docs monorepo. You can browse the code here: https://github.com/reactjs/reactjs.org/tree/main/beta

[ovieu]

For Challenge 1 of 2: Fix a request counter at (https://beta.reactjs.org/learn/queueing-a-series-of-state-updates) It seems there is a runtime exception in the code runner.

The error

Runtime Exception

App.js: regeneratorRuntime is not defined (3:41)

  1 | import { useState } from 'react';
  2 | 
> 3 | export default function RequestTracker() {
                                               ^
  4 |   const [pending, setPending] = useState(0);
  5 |   const [completed, setCompleted] = useState(0);
  6 | 

The code

import { useState } from 'react';

export default function RequestTracker() {
  const [pending, setPending] = useState(0);
  const [completed, setCompleted] = useState(0);

  async function handleClick() {
    setPending(p => p + 1);
    await delay(3000);
    setPending(p => p - 1);
    setCompleted(c => c + 1);
  }

  return (
    <>
      <h3>
        Pending: {pending}
      </h3>
      <h3>
        Completed: {completed}
      </h3>
      <button onClick={handleClick}>
        Buy     
      </button>
    </>
  );
}

function delay(ms) {
  return new Promise(resolve => {
    setTimeout(resolve, ms);
  });
}

[gaearon]

Thanks @ovieu, will fix

[pgremeau]

I'm going through the tutorial and I'm getting 'regeneratorRuntime is not defined' errors on all code samples that include 'async'. The latest, for instance, is the city quizz example under Managing State > Reacting to input with state. There were a couple others in previous pages (sorry, didn't keep track of them). Not sure if it is an error on my side or with the docs setup (I'm using latest Chrome).

[markerikson]

I think this accidentally got closed by that Sandpack fix PR :)

[gaearon]

lol

[pgremeau]

There is now a permanent 'Error, Failed to fetch' in all the doc's examples and challenges.

[gaearon]

Woah. I'll see if reverting fixes this. Or maybe something on CS side is down.

[gaearon]

Ok reverting fixed this. So the bug is back but sandboxes work.

[khaki32]

Love the new beta docs, both the way the site looks and the actual docs themselves.

However, I wish there was a live table of content. Prettier implements this really nicely for their options doc.

It's optimal for large pages like the useContext hook. It reduces clutter and lets you move around the page easily.

[gaearon]

There is a table of content if you make the page a bit wider (or zoom out). It doesn't show up on smaller screens.

[gmoniava]

@gaearon Looked at the upcoming section about useEffectfrom Twitter, after briefly looking at it, I didn't notice example of using ref to run code inside effect only once (section about effects firing twice in dev), like here: https://github.com/reactwg/react-18/discussions/18. I suppose it should be there?

PS. Also for really long pages, wouldn't a clickable table of contents at the start of the page be nice?

[gaearon]

PS. Also for really long pages, wouldn't a table of contents (so that I can click and jump to section) at the start be nice?

There is a table of contents on the side but it shows up on slightly wider screens. Maybe we can explore showing it in more cases though this might make code examples crowded.

I didn't notice example of using ref to run code inside effect only once (section about effects firing twice in dev)

Yea that's intentional. I'm noticing that a lot of people reading https://github.com/reactwg/react-18/discussions/18 seem to think that that is the primary solution whereas the text there says that you should usually leave code as is and the ref thing is kind of a last measure. So I think I'll mention it in some place but really the focus should be on teaching the main pattern.

[khaki32]

There is a table of contents on the side but it shows up on slightly wider screens. Maybe we can explore showing it in more cases though this might make code examples crowded.

I didn't know that. It'd be nice if it was visible on smaller screens (I have to zoom out to 67% 😅) and on mobile. On mobile it could just be another menu, like MDN. For smaller screens, I geuss the main menu and the table of contents could be less wide. The main menu takes up a lot of space. I'm fine with having to zoom out a little.

[gmoniava]

Here, in deep dive "how to manage list of refs" maybe few words can be added why new Map() is used for storing references to dom nodes, instead of object literal?

[vincerubinetti]

Hi, hopefully this is the right place to comment on or make a suggestion for the new docs?

https://beta.reactjs.org/learn/synchronizing-with-effects#recap https://beta.reactjs.org/learn/synchronizing-with-effects#step-2-specify-the-effect-dependencies

These sections say that you "can't choose your dependencies, they're determined by the code in the effect", but you can also add dependencies beyond what's in the code. This is reflected by the fact that react-hooks/exhaustive-deps doesn't complain about extra deps (unless something changed since I last updated it).

You might want to add a note like "An effect's dependencies must include at least the entities referenced in its code. In rare cases you may want to add extra dependencies that are not used in the effect."

example use case of extra deps

I have a fancy SVG chart visualization that changes its appearance based on several different often-changing props. I want to auto-fit the `viewBox` to the contents of the rendered SVG, but only when certain props change; props that greatly affect the geometry of the chart (if I do it on every prop change, it's too jittery). The `autoFit()` function doesn't actually take any of the props the chart does, just a ref to the rendered SVG element. So, I use a `useEffect` that just calls `autoFit()`, and has a dependency array with the `autoFit()` function and several "extra" dependencies.

[kdivringi]

I want to start by saying that the Scaling Up with Reducer and Context section is a great addition that gives some guidance on how apps can grow and still remain easy to work with. Introducing context like this is also good because state libraries all build on it and an understanding of the primitive will help understanding with how those libraries operate.

One reservation I have is that it's very common to make the reference identity mistake with the context value (ie defining value as an object literal), which is common as soon as you want to have more than one value in a context. I'd think it'd be worthwhile to have another step where the TasksDispatchContext is changed into an object and put in an intermediate useState/useMemo to demonstrate that pattern here, not just in the API docs.

[payapula]

Love the new react docs.

Spotted one typo on this challenge https://beta.reactjs.org/learn/queueing-a-series-of-state-updates#challenges

And if you click fast twice, both counters seem to behave unpredictably.

I guess it should be 'click that twice'.

[gmoniava]

Here it says:

React’s rendering process must always be pure. Components should only return their JSX, and not change any objects or variables that existed before rendering—that would make them impure!

But elsewhere in the docs, there is example where it is Ok to call set state during render (albeit inside a condition). Isn't a state variable something that existed before rendering? So according to the quote above changing it shouldn't be allowed during render, isn't it? @gaearon

Maybe it is worth to reword the quoted sentence.

[hichemfantar]

Love the new docs. Why isn't it open source tho? I believe the new docs should be open source, this will allow the community to contribute directly by fixing bugs in both the documentation and the code. We want the new react docs to be up and running asap and with the help of the community it will reach stable status quickly.

[harish-sethuraman]

@hichemfantar the new docs site is open source and is available inside the beta directory.

[hichemfantar]

@harish-sethuraman can't believe I missed that. I thought they moved the new docs to a different repository. Thanks!

[surjithctly]

I'd be very worried if react beta docs shipped with the current font Optimistic Display. It's not readable at all. Esp for a text-heavy docs like this. Look how clean it is by just switching it to default stack:

✅ Good, Readable font

For reference, here's the existing font.

❌ Bad Font

What's your opinion? React with Emojis

[swikars1]

I agree the font looks nice but actually feels harder to read comparing it to font of vue docs

[cxOrz]

I guess it's the font color that affects the reading experience. Although the font color didn't change, the current doc's font make it's color looks darker than the Readable font @surjithctly mentioned. Current doc paragraph's font color looks the same dark as the title which make reader feels bit of wierd. Maybe adjust the paragraph's color lighter could be better.

[checkmatez]

Minor thing: on the page "Manipulating the DOM with Refs" in the deep dive section "How to manage a list of refs using a ref callback", code example uses getMap function to initialize ref lazily; I wonder if it could be removed in favor of providing initial value to useRef directly:

const itemsRef = useRef(new Map());

this way, there is way less code, and it is easier to see the essence of the example. Created MR: https://github.com/reactjs/reactjs.org/pull/4814

[zwwdev]

Typo: on the page "Passing Props to a Component" in the part "Passing JSX as children", it says that

You can think of a component with a children prop as having a “hole” that can be “filled in” by its parent components with arbitrary JSX.

I think it actually means that "the hole can be filled in by its children components?

[checkmatez]

@zwwang98 I think docs are right, and this is not a typo. You probably confused children components with the children prop. If we have a component that renders props.children, than this "hole" can be filled in by whomever renders this component, so the parents.

[Adaxelx]

There is a bug on a nav in chrome mobile (iPhone 11). You can't select last item as it is hidden behind bottom bar (element "You might not need an effect")

https://user-images.githubusercontent.com/48855027/179072351-3a0c8314-4b50-48a7-ae03-f471b6f2eae3.MOV

[zwwdev]

@checkmatez Thank you! It helps me a lot! Just to make sure I am understanding you right. Do you mean the parent component of the component with a children prop pass in some props to it?

[smikitky]

From Synchronizing with Effects:

Note: Here and later in this text, capitalized “Effect” refers to the React-specific definition above, i.e. a side effect caused by rendering. To refer to the broader programming concept, we’ll say “side effect”.

I think this can be friendlier. Historically, React docs have treated effect simply as the shorter synonym for side effect. Those who are already knowledgeable about this concept may tend to take this for granted, but this is a puzzling tradition for beginners. People may read this Wikipedia article, think too strictly, and consider effect also includes the "primary effect" of returning a JSX tree from a component.

I have seen people ask "Why is this called effect in the first place? What's the difference between effect and side effect? Why is this hook not useSideEffect?". Since this is the first page where the term "effect" (without "side") appears, it would be nice to have a more explicit explanation that "effect" and "side effect" are essentially the same in the context of React as well as functional programming in general.

[GGrassiant]

Hello 👋

I think there might be a small typo in a link's URL for you-might-not-need-an-effect#fetching-data

Where it says To fix the race condition, you need to add a cleanup function to ignore stale responses the URL points to https://beta.reactjs.org/learn/learn/synchronizing-with-effects#fetching-data instead of https://beta.reactjs.org/learn/synchronizing-with-effects#fetching-data

Thanks again to the whole team for the great work!

[bholtbholt]

👋 Hello! Thanks for the new docs -- they're great!

I have a question about rendering objects in state. In this example, we need to create a new object in order render. Does this mean objects are less performant than other state values?

I'd like additional text added to the effect of:

• Note: objects will always re-render all fields, so you may have better performance by splitting properties
• (or if that's not the case) Note: Don't worry -- There's no render performance cost for non-nested objects compared to other types of state values. React diffs based on the values in the object and only re-renders what's changed.

Code example for comparison:

// Using an object
const [person, setPerson] = useState({
  firstName: 'Barbara',
  lastName: 'Hepworth',
  email: 'bhepworth@sculpture.com'
});
// Updating an object
setPerson({
  ...person,
  [e.target.name]: e.target.value
});

// Using strings
const [firstName, setFirstName] = useState('Barbara');
const [lastName, setLastName] = useState('Hepworth');
const [email, setEmail] = useState('bhepworth@sculpture.com');
// Updating values
setFirstName(e.target.value);
setLastName(e.target.value);
setEmail(e.target.value);

[markerikson]

@bholtbholt : there's no meaningful difference here.

The primary requirement for a useState setter is that you must pass in a new reference in order for a render pass to actually get queued up (ie, passing in the same existing state value reference is a no-op and React will bail out of the render). As part of that, React expects immutable updates for any objects or arrays.

In this case, the only difference between "multiple separate useStates for each field" and "one useState with an object" is that you have to copy the one object when you update it. A single object spread has no actual performance difference. (and if anything, you're avoiding a few additional hook calls each render.)

Note that in both cases, the entire component re-renders regardless of how many setState() calls happened or how many fields there are.

[gaearon]

Since this is the first page where the term "effect" (without "side") appears, it would be nice to have a more explicit explanation that "effect" and "side effect" are essentially the same in the context of React

The intention is the opposite; it's to establish that not every side effect needs to be expressed as an Effect. Most side effects belong in event handlers. But side effects caused by rendering should be written as Effects.

[lgenzelis]

Hey folks, kudos on the terrific work on the new documents! Is this the best place to leave suggestions? I've run into a couple of minor mistakes, but I don't seem to find a way to report them directly in the docs.

• in challenge 2. Fix a broken packing list in https://beta.reactjs.org/learn/choosing-the-state-structure there's an unused state (const [title, setTitle] = useState('');), both in the exercise and the solution
• some exercises point at stuff that should break (for example, while teaching the rules of hooks), but it seems you added eslint to the sandboxes after writing the exercises. So, exercises say things like "click at this button, you'll see X error, why you think that's happening?", but that's actually not the case, because the sandbox is not running at all because the linter is (correctly) catching the mistake beforehand

[ndejoma]

Great docs, sorry I had not seen the challenge

[arviinmo]

Hey @gaearon, i was wondering what would happen to the older version of React docs? because i already translated some parts of Ku.reactjs.org. are they gone forever, and if so how can i contribute to the Kurdish version of this new docs?

[zanzlender]

Question here regarding the new docs, I came across this page React Docs - Integrating with other libraries and I was wondering, since most of the docs are now Functional, is this intentionally left like a class component because it cannot be done with functional or something else?

For example I know one such problem I came across, it believe was with EditorJS and the problem was the functional component would call it again and again, so we had to implement a workaround that would check if it had been instantiated, and would only render if it wasn't yet.

[joepetrillo]

I am curious if the progress percentages are still accurate? Thanks!

[blake663]

Hi, I noticed that in the solution for the challenge https://beta.reactjs.org/learn/passing-data-deeply-with-context#challenges , the List component still takes the imageSize prop.

[mrxvt]

Is the {' '} proceeding the text in the input tag within the SearchBar function of the sandbox example on the Thinking in React page (L98) necessary? If it's only seeking to advance leading whitespace, would it be a good idea to wrap the entire string in curly braces, a la { ' Only show products in stock '} or remove it entirely as Prettier does?

[pengkai]

Hi, there! The page (https://beta.reactjs.org/learn/choosing-the-state-structure#avoid-deeply-nested-state), there is a mistake, need to put the child ol code blocks inside the parent li element.

Permitted content | Zero or more \<li>, \<script> and \<template> elements.

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol

[michal-markiewicz]

Hi! There is a typo at the end of Thinking in React: Step 4

wil should be will

[gaearon]

Hey folks, sorry it's been a while with no updates. We've completed almost the entire Learn section, and wrote stubs for the API pages, so we'll try to finish up the API pages over the coming weeks, and in the meantime start linking to the Beta site from the main docs.

---

I'll respond to a few comments:

https://github.com/reactjs/reactjs.org/issues/3308#issuecomment-1197344998

in challenge 2. Fix a broken packing list in https://beta.reactjs.org/learn/choosing-the-state-structure there's an unused state (const [title, setTitle] = useState('');), both in the exercise and the solution

Fixed.

some exercises point at stuff that should break (for example, while teaching the rules of hooks), but it seems you added eslint to the sandboxes after writing the exercises. So, exercises say things like "click at this button, you'll see X error, why you think that's happening?", but that's actually not the case, because the sandbox is not running at all because the linter is (correctly) catching the mistake beforehand

Fixed.

https://github.com/reactjs/reactjs.org/issues/3308#issuecomment-1202156664

i was wondering what would happen to the older version of React docs?

I was thinking we'd put them at some URL like archive.reactjs.org or similar, but they will be frozen in time and have a banner on every page linking to the new docs. So I'd suggest to do the same with existing translations when the time comes.

https://github.com/reactjs/reactjs.org/issues/3308#issuecomment-1203855129

Question here regarding the new docs, I came across this page React Docs - Integrating with other libraries and I was wondering, since most of the docs are now Functional, is this intentionally left like a class component because it cannot be done with functional or something else?

This is a page in the old docs. We don't have a 1:1 page in the new docs (at least, not yet). Much of the Escape Hatches section in the new docs is relevant to this topic though.

For example I know one such problem I came across, it believe was with EditorJS and the problem was the functional component would call it again and again, so we had to implement a workaround that would check if it had been instantiated, and would only render if it wasn't yet.

You're welcome to ask a question on StackOverflow or in React issues, but no, you can implement things like this with function components perfectly fine. It's supposed to be called over and over, but the way you'd deal with this is by using refs and Effects. See this section: https://beta.reactjs.org/learn/escape-hatches.

https://github.com/reactjs/reactjs.org/issues/3308#issuecomment-1221407853

Hi, I noticed that in the solution for the challenge https://beta.reactjs.org/learn/passing-data-deeply-with-context#challenges , the List component still takes the imageSize prop.

Fixed.

https://github.com/reactjs/reactjs.org/issues/3308#issuecomment-1237699453

Hi, there! The page (https://beta.reactjs.org/learn/choosing-the-state-structure#avoid-deeply-nested-state), there is a mistake, need to put the child ol code blocks inside the parent li element.

Fixed.

https://github.com/reactjs/reactjs.org/issues/3308#issuecomment-1240387916

Hi! There is a typo at the end of Thinking in React: Step 4

Fixed.

---

In general, please feel free to send direct edits for typos. The source is in this repo, the files are in beta/content.

[vonkoff]

For the first challenge of Preserving and Resetting State I believe the solution offered that has two buttons, with one showing depending on a state boolean, is a little bit too verbose.

You can remove the conditional operator and simplify the component by using setShowHint(!showHint) to change the information shown.

Simplified Solution

export default function App() {
    const [showHint, setShowHint] = useState(false);
    return (
      <div>
        {showHint && 
          <p><i>Hint: Your favorite city?</i></p>
        }
        <Form />
        <button onClick={() => {
          setShowHint(!showHint);
        }}>{showHint ? 'Hide hint' : 'Show hint'}</button>
      </div>
    );
}

Original Solution

export default function App() {
  const [showHint, setShowHint] = useState(false);
  return (
    <div>
      {showHint &&
        <p><i>Hint: Your favorite city?</i></p>
      }
      <Form />
      {showHint ? (
        <button onClick={() => {
          setShowHint(false);
        }}>Hide hint</button>
      ) : (
        <button onClick={() => {
          setShowHint(true);
        }}>Show hint</button>
      )}
    </div>
  );
}

[tsilefy]

Hi!

In "Reusing Logic with Custom Hooks", testing the custom hook relies on the online/offline browser events, which in turn relies on navigator.onLine. The text asks the reader to "Try turning your network on and off". On Firefox, that won't work, as navigator.Online always return true even if the network is turned off, the wifi is turned off or the ethernet cable is unplugged.

There's a 12-year old wontfix bug about this.

The only way to trigger the change to offline on Firefox is to enable Work Offline (File/Work Offline). I'd suggest adding that to the sentence.