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.

[drbr]

I know the API Reference side of the site is still early, so maybe you're already planning to do this, but:

The useState API reference page reads more like a tutorial than an API reference. I think this is great info for people new to React and/or JavaScript, but for people who've already been exposed to the ideas and just want to understand what the API is capable of, many of us would expect a concise API reference at the top; i.e. what does each parameter do, what are the return values, what are the different ways the updater can be called.

[ubuntugx]

Hi, I would like to contribute to the translation of React documents. How can I participate in the translation of simplified Chinese documents?

We will announce when we're ready to kick off the translation effort. For now, it's a bit premature because the content is still in flux.

@gaearon thank you for your response! While reading the post Referencing Values with Refs , There are two minor mistakes I would like to mention

[gaearon]

As someone who has learned React 3 years ago from the official examples, I have to say, it really "Feels" like the new docs don't quite have the cohesion of the original tutorial. Perhaps because the tic-tac-toe tutorial was on one single page and didn't require quite so much navigation, but to me the original tutorial is much easier to follow than what's in the new beta docs. Seems like it's a bit of an oversight to me

As noted in https://github.com/reactjs/reactjs.org/pull/3965 in “known issues”:

No tutorials. We need to complete explanations for all core concepts and APIs before we can add tutorials. (This could be really cool to work on with the community at a later date! But not today!)

The pages that exist today are more of a replacement for “Main Concepts” and/or “Advanced” section of the current docs. Tutorials are yet to be added/written. Though I’m curious if you’d find this one, carried over from the old docs, sufficient?

https://beta.reactjs.org/learn/thinking-in-react

[gssakash]

I know that the new React Docs webpage is still in the beta phase but, It would be great for the website to "Persist" the Dark Mode whenever the user reloads the webpage. Websites like Docusaurus already support this so, I'm sure React Docs would be able to adopt it in the future. I've demonstrated how it does not get persisted at the moment in the below video and I hope that this would be resolved soon.

https://user-images.githubusercontent.com/52027687/140014965-6251a83e-be62-4054-9dfd-bac538a8a269.mp4

[amitojsingh366]

I know that the new React Docs webpage is still in the beta phase but, It would be great for the website to "Persist" the Dark Mode whenever the user reloads the webpage. Websites like Docusaurus already support this so, I'm sure React Docs would be able to adopt it in the future. I've demonstrated how it does not get persisted at the moment in the below video and I hope that this would be resolved soon. O25Qa85FN6.mp4

this is done in #4023

[orange-pig]

Celebrate the new react document! I look forward to the new documentation to help more developers easier to understanding React design philosophy. As a user of Chinese documents, I strongly hope that the Chinese translation of the new version document can change the translation of '副作用(side effect)'. Beacuse this word itself has a Uncontrollable bad effect meaning in the context of the text. It has been strongly affecting my understanding of every time I use the hook functions. It is recommended that in the new version document with Chinese ,'side effect' can be translated into any word other than '副作用', such as: '伴随效应/从效应(concomitant effec)', '邻效应(side effect)', or '基效应(base effect)'. It is ten thousand times understanding better than '副作用'.

[MaxNoack]

Editing a challenge and then going to the next challenge and then back again, the code is reset. Would be nice if users changes were persisted. 😃

[gssakash]

Would be great if the scrollbar mentioned in the below issue was removed.

4033

[gaearon]

We've merged a few fixes:

• there should be no full-page horizontal scrollbar now
• the dark mode should persist now

[gaearon]

Added Dark mode for code blocks / sandboxes. We'll be tweaking the color schemes and try to make them consistent separately.

[wanghan-js]

Hello there!

Thanks a lot for your amazing work on the new docs, I'm new to React, and I have read all of it!

The docs is good undoubtedly, I'm just wondering when will the 100% complete version will be released.

Is there a plan of releasing pace?

Thank you!

[RichardLindhout]

Just wanted to say the docs look amazing! Great detail but kept simple and the layout is nice too.

[gssakash]

Hey There, I noticed a few links on this .md file to be incorrect and they redirected to a link which returns a 404 inside Github.
Example: The line where there is a redirection about how the user can set up their editor under the link how to set yours up I wanted to know if this was done on purpose or if it required to be fixed. I would be glad to fix them once I know the reason why the links don't work at the moment.

[YagamiNewLight]

In the Escape Hatches chapter, after reading two descriptions of the Refs: "This is what makes it an “escape hatch” from React’s one-way data flow" "Refs are an escape hatch to hold onto values that aren’t used for rendering"

I'm still confused about how does the ref becomes the escape hatches of one-way data flow. Does the parent container holding ref to change the child's component's state breaks the one-way data flow?

[Aprillion]

I just noticed there are 2 names for the concept previously known as "react element" in the new docs:

• "place in the UI tree" on https://beta.reactjs.org/learn/preserving-and-resetting-state
• "component instance" on https://beta.reactjs.org/learn/state-a-components-memory#state-is-isolated-and-private

Not sure which name is preferred, which prompts an additional idea - can we have a Glossary page in the docs?

[saurabhaditya]

Noticed a few mistakes when reading the Interactivity sections.

This sentence should be inverted.

Link: https://beta.reactjs.org/learn/updating-arrays-in-state#adding-to-an-array

Actual: "In this way, spread can do the job of both push() by adding to the beginning of an array and unshift() by adding to the end of an array. Try it in the sandbox above!"

Expected: "In this way, spread can do the job of both push() by adding to the end of an array and unshift() by adding to the beginning of an array. Try it in the sandbox above!"

[saurabhaditya]

Possible to correct this?:

Link: https://beta.reactjs.org/learn/queueing-a-series-of-state-updates#what-happens-if-you-replace-state-after-updating-it

Actual:

In Strict Mode, React will run each updater function twice (but discard the second result) to help you find mistakes.

Expected:

In Strict Mode, React will run each updater function twice (but discard the first result) to help you find mistakes.

[gaearon]

Please send PRs if you'd like; the content is in beta/src/pages/learn/.

[kpav33]

Hello,

I just noticed a little grammar mistake while reading the new docs. On top of the Managing State page (Link to page: https://beta.reactjs.org/learn/managing-state) in the You will learn section, the third item in the unordered list is How “lift state up” to share it between components. There is a to missing here, so it should be How to “lift state up” to share it between components.

[mungojam]

The new page on using Refs mentions 'measure its size and position' as one use of them. But it doesn't have an example.

The importance of this one is that the old docs suggested making use of useCallback not useRef for this such that the size is measured and events triggered as soon as the DOM element is mounted. I wondered if there is a new recommended approach or if the existing one should come across from the old docs.

[0xnoob]

In the Learning area, it's unpleasant that I can't see subsections without first clicking on its main section: I'm on Adding Interactivity ᐳ Updating Arrays in State and I want to see or go to Describing the UI ᐳ Rendering Lists. I can't do that without going over Describing UI Overview.

One way to fix that would be to make clicking the arrows not visiting the page to the left (and not highlighting it), but simply (un-)collapsing it's tree. One way to indicate this behaviour would be to only highlight the arrow and not the text to its left, while hovering it.

---

As people mentioned ([1], [2]) I found the title "Quick Start" confusing:

To be clear, Quick Start itself doesn't have several chapters — it summarizes the chapters. That page is a summary of the entire site. You can "dive deeper" to a chapter (example chapter), which summarizes each page (example page) in it. And then you can dive deeper into the pages you find interesting.

As @rmorshea said:

My assumption when reading "Quick Start" is that this section will tell me how to write and run a simple app in as few words as possible. The reality though, is that it feels more like a more considered introduction or overview [...]

This is what I thought as well, because I read it as "Quick start to using react" rather than "Quick start to learning react", even though it is in the learning section, because that's what you normally find under a Quick Start section (e.g. Quick Start | React Query). The Thinking in React subsection is what I associate with the term "Quick Start". If you don't want to call it Introduction or Overview, how about Getting Started.

The ToC on the right of that section - however named - should be similar to the navigation on the left, to support the purpose of it as a "guidance" or "signpost". But this should also be going the other way: the navigation should be similiar to the ToC. Right now, only the ToC makes its obvious that three chapters (Describing the UI, Adding interactivity, Managing State) are more related to each other than the rest of them (Installation, Escape Hatches).

---

e.g. What I think the navigation should look like:

Installation ᐳ

Getting Started

Introduction (currently called Quick Start) Thinking in React / Quick Start

Learn React / Main Concepts

Describing the UI ᐳ Adding Interactivity ᐳ Managing State ᐳ

Advanced Guides

Escape Hatches ᐳ

Explanation: Headers are neither clickable nor collapsable, just like it is in react queries doc. and A / B means B is an alternative name for A. List items are clickable to get to its corresponding overview and the ᐳ to its right are also clickable to unfold it's subsections without loading its overview.

[luckymore]

你们也这么卷吗😄

[Lemmmy]

They look absolutely beautiful, and a huge improvement to the structure and readability of what I've glanced at so far!

This is a very minor issue but might be crucial for accessibility, on my system at least (Chrome 95 on Windows 11), it is almost impossible to tell the bold font apart from the regular font.

Personally, I would argue that the bold font is fine but the body font is far too thick. With a non-retina display at default font scale and 100% zoom, it's fairly hard to read due to the poor hinting from the font weight.

[gaearon]

Thanks, we'll investigate.

[yordis]

Hey folks, is it too late to suggest following https://documentation.divio.com/?

In a sense, you are already following it but I am referring to name it like "How-To Guides", "Tutorials" and such ... to train the community to align in such topic. Before reading such a website and watching the video, I wasn't intentional with documentation, but now, as a consumer, I see a lot of value in it.

:2cents:

Also, that website is looking amazing, thank you so much for such work

[rachelnabors]

Huge fan of that system!!

But, for React, we wanted something that would explain concepts along with guiding folks through working with React. it’s a bit unconventional, but the hope is that by teaching concepts alongside goal-based activities, the concepts will “stick” better than if they were taught separately. We have seen promising results from teaching the why alongside the how in beta testing and hope to see those results continue in this beta :)

[Madses]

Switching between menu items feels very sluggish. This happens with every menu item except the first and the last one for some reason. See link for example.

https://giphy.com/gifs/3kxkEs6NvoopTsl1vm

[o-t-w]

Would love to see documented best practices about building a shareable installable component library.

[kaushalyap]

@rachelnabors Great work so far! Can we please have a best practices section too like in Redux docs

[13zebras]

@rachelnabors I am listening to you on JS Party as I'm typing! Great explanation of the new docs. And they are excellent....... And since you want feedback..... The first thing I noticed with the beginning of Quick Start (https://beta.reactjs.org/learn) was WHY did I edit my name on the tiny react app? What was I meant to take away from this tiny lesson? I'm a long time high school teacher, and personally I would make this tiny app a mini lesson. Maybe a "want to know more" button? Or just a sentence explaining the very basics of this tiny React app. While the fuller explanation comes 8-10 paragraphs, something brief to explain this app would be great. 👍

[erhkim]

Will there be a TypeScript section in the future? Coming from Angular, using TS usage looks to be a lot more complicated in React.

[kosmickanga]

Small one, the "Start a New React Project" page uses NPM, but after running npx as shown it creates a project that uses Yarn. The npx command needs --use-npm appending to it.

https://beta.reactjs.org/learn/start-a-new-react-project

[markerikson]

@erhkim fwiw, the canonical React+TS resource is https://react-typescript-cheatsheet.netlify.app/ .

(and I would be legitimately surprised if TS is "more complicated" in React than it is in Angular.)

[jtoar]

@gaearon wanted to give you more thoughts on the reddit comment (https://github.com/reactjs/reactjs.org/pull/3965#issuecomment-949262481). First off, I thoroughly enjoyed the new docs! The Learn section reads like a book. So I’ll start by disagreeing with:

None of this flows well from one section to another, and you can end up getting lost very easily.

I thought that the sections were joined smooth and I never felt lost in the least. Just want to give you another data point.

Second off, big fan of zoomable content. I sympathize a bit with the OP in that it does take a second to get used to the way it’s structured. But once you realize “Oh this is a summary of all the chapters, and this is a summary of chapter 1...” it makes finding what you want super easy.

To me the main question is how do you make it more obvious that the content is zoomable. Right now I don’t think you can tell that it is just by looking at the sidebar (I only discovered that it was after reading a bit).

One easy-to-implement suggestion: rename “Quick Start” to something like “Course Structure” or even just “Learn React”. I expect something called “Quick Start” to be a suite of curl commands that I’m supposed to run so that I can just start using the thing that I came here for. What you described “Quick Start” as in the original thread sounds more like a Table of Contents (which is invaluable!):

To be clear, Quick Start itself doesn't have several chapters — it summarizes the chapters. That page is a summary of the entire site.

[taniarascia]

One easy-to-implement suggestion: rename “Quick Start” to something like “Course Structure” or even just “Learn React”. I expect something called “Quick Start” to be a suite of curl commands that I’m supposed to run so that I can just start using the thing that I came here for. What you described “Quick Start” as in the original thread sounds more like a Table of Contents (which is invaluable!):

I agree, it seems like "Overview" would be an accurate term here.

[ScytheDraven47]

Firstly; the docs look great! Really clean, and thanks for having a dark mode!

I believe I found a bug that I don't think anyone's mentioned yet... The eventHandler for the next ">" arrow button in the Challenges section (all pages) doesn't keep up if you're using the blue "Next Challenge >" button.

Only noticed because I've been doing all the challenges, and they're also really well done!

[gaearon]

@ScytheDraven47 would you like to look into a fix?

[rmorshea]

I think this image:

In the state as a snapshot section could use some improvement. At first glance, the order of events is not clear to the reader because there arrows do not flow in one direction. Having looked at it for a while, I now understand that that the order of events is supposed to carry over from the prior image

However, I think that only became clear to me due to the experience I already have with React. If you were to show the two images without any explanatory text to people who are unfamiliar with React, I suspect they'd be unable to interpret what's happening in the image where React and setState are introduced.

[erhkim]

Ok this might be a small error, but in the first challenge here: https://beta.reactjs.org/learn/reacting-to-input-with-state#challenges the image zooms in for the user react sandbox but not for the solution sandbox.

[erhkim]

https://beta.reactjs.org/learn/reacting-to-input-with-state#challenges Also in challenge 3 I believe let lastNameText = document.getElementById('lastNameText'); is missing from the sandbox

[ghost]

Hello, I love the new look and I love hooks! I noticed a problem with one of the examples here https://beta.reactjs.org/learn/writing-markup-with-jsx#converting-html-to-jsx

It says "Suppose that you have some (perfectly valid) HTML" but both the HTML example and the live demo are missing the closing </li> tags in their unordered lists.

[gaearon]

It says "Suppose that you have some (perfectly valid) HTML" but both the HTML example and the live demo are missing the closing tags in their unordered lists.

This is valid HTML. https://css-tricks.com/some-html-is-optional/

Also in challenge 3 I believe let lastNameText = document.getElementById('lastNameText'); is missing from the sandbox

If something's missing, do you mind sending a PR?

[gaearon]

Created an issue to kick off the translation process: https://github.com/reactjs/reactjs.org/issues/4135.

[ghost]

This is valid HTML

Woah, there's a first thing for everything. I just found it odd how in some other file it was written with closing </li> tags. I would try to make a case that since the included material is aimed at beginners that adding exceptions like that would further confuse beginners like myself that are used to write "semantic" HTML and include closing tags whenever possible.

Anyways, I'm terribly sorry! I removed the pull request.

[gaearon]

No problem! I agree we should probably clarify this.

[herrhelms]

Excellent job on the new documentation. So well done, congrats to everyone on the team!

I've noticed that there's no actual link preview available when trying to share the beta docs on social platforms (e.g. twitter) while og:image and twitter:image meta tags are all set, it seems robots.txt is blocking access to the referenced social image - resulting in no link preview.

steps to reproduce: https://cards-dev.twitter.com/validator enter https://beta.reactjs.org

Just wanted to let you all know. Keep up the great work! 🙌

[Ibrahim60]

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

Its Not working.

[minhaics]

hi guys could you please make a similar site for react-native.dev

[ikhattab]

in Scaling Up with Reducer and Context, can you please illustrate why we use 2 contexts one for providing state and the other for providing dispatch instead of using a single one for both?

[DFive5]

A little slow