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.

[smikitky]

What will the translation process be like? The current translation bot merges everything from the original repo's master branch into each translation repo, but it sees only the master branch.

The easiest approach would be to create a new docs-v2 directory on the master branch, alongside the current docs, so that translators can work on it as soon as new articles are made. (Of course, the new directory doesn't have to be live until it becomes ready in early 2021.)

[ericzorn93]

Always great news to here from the React Core Team. Excited to see the new website.

[jhayworthg]

I think the visual diagrams of how React works will be incredibly helpful. It will encourage the benefits of how React. I am the type of person that likes to know how and why just as much as what when learning something. There is a bit of a mirage when learning React and why it is a great solution to frontend development. Getting a visual example of when a component updates and its relative child components update will go a long way to people understanding the concept.

[jjoselv]

Great! A good moment and place to put all experience gathered from explain complex concepts from Just JavaScript @gaearon AIR? Btw, count me in for Spanish translations of you want. 💪

[sondh0127]

As a suggestion for an awesome react hook tutorial form 'EpicReact.Dev' https://github.com/kentcdodds/react-hooks

[maifeeulasad]

Just asking

In future, is there any chance that Class Components becoming deprecated ?

They are really cool to play around.

[AhmadMayo]

Adding my two cents, please add a "Why use react" section. I still reference the first talk I've seen that explained why was react invented in the first place. People learn and teach the "how" not the "why", and I think this has two major results:

1. The "x is faster than react" content. This happens because they don't know that speed is no the most important concern for react. Modularity, easy to reason about code, predictability, maintainability, and resilience are.
2. A lot of the developers that I've dealt with personally write code that is not aligned with these reasons. They focus on re-usability, because components and hooks, writing lots of and lots of very small components and I don't even know why.

I'm sorry if this seems like a rant, and its not your fault, but people tend to forget, and as time passes by, it seems that more and more forget why we chose react in the first place.

[fuzunspm]

Just asking

In future, is there any chance that Class Components becoming deprecated ?

They are really cool to play around.

I like to use Class Components and I hope it will never be deprecated

[rachelnabors]

Thank you all for your feedback! Love reading your thoughts here! To answer a few concerns:

What will the translation process be like?

We're still figuring this out! As we start having more to share, we'll reach out to the translation community and adopt a plan that works for everyone. (Thanks for your suggestion, btw! Good idea!)

In future, is there any chance that Class Components becoming deprecated ?

Class components are going to be around for years to come—for example, there are tens of thousands in production at Facebook already. However, we do recommend that new apps be built with function components and Hooks, which is why we want those docs front and center. The class component docs will remain available for folks working with those components, and class components themselves might one day be spun out into their own package—but if that did happen, we're provide migration scripts to automate that transition :)

[balazsorban44]

Hi @rachelnabors!

As a core maintainer of the 🇭🇺 Hungarian docs translations, I welcome this update to the docs, as - while working through the docs myself - I too noticed a need for a refresh.

Although, I am now wondering as since we haven't fully finished the translations, how much of the content is expected to change in the next version? Will we be able to transfer some of the translations, or should we start from scratch when the new docs come out?

Our progress has slowed over time (https://github.com/reactjs/hu.reactjs.org/issues/1) as life caught up and got busy with other stuff, but I am still motivated to contribute at my own pace! (There were periods when I was able to translate a dozen pages in a matter of days).

Either way, an estimate of the change in % could give a picture of the forthcoming work to be done, not counting new content. If things could be transferred, do you think this can be done in some kind of an automated/semi-automated process?

Thanks!

[gaearon]

I think there’s a high chance most of the content would be rewritten from scratch.

[balazsorban44]

Thanks @gaearon!

I did not have high hopes anyway, but it is good to know, we will then probably not invest too much into translating new pages, only maintain the current ones by merging the weekly PRs, except if someone with a lot of free time would consider translating anyway. I used up all my energy on work in the last weeks/months.

[fsociety0XX]

thanks @rachelnabors ! Looking forward to see the new react documentation. This is going to be awesome with react 17. 🔥

[michaeldera]

I would like to see more content on the CSS in React. I am aware that React is generally not opinionated when it comes to implementing CSS but it would still be great to see some guides on the subject.... and documentation of stuff like React.CSSProperties

[gaearon]

Can you tell us more about React.CSSProperties and what you'd like to see documented there? This is not a React API but a part of the React TypeScript definitions. But we could maybe include those somewhere.

[csdal]

To introduce functional component first for new users

This is the idea of @0xca0a on Twitter. I totally agree with him.

Introducing React with class-based component makes new users push back away from learning React. I also faced this experience. I wanted to learn React so many times but after reading front page examples, I left out of the website.

[gaearon]

Yes, this is exactly what the post is saying:

The new docs will teach React Hooks-first, [...]

[michaeldera]

Can you tell us more about React.CSSProperties and what you'd like to see documented there? This is not a React API but a part of the React TypeScript definitions. But we could maybe include those somewhere.

I think it would be helpful in general to have the TypeScript definitions mentioned or simply a link to the documentation of those and other definitions if possible. If the community using TypeScript with React is large enough, it would be nice to have documentation for people using React with TypeScript. It is not difficult to figure out but could be easier to figure out if there is documentation to read.

[gaearon]

@michaeldera Have you found any external resources on this topic particularly helpful? E.g. https://github.com/typescript-cheatsheets/react? Maybe we could integrate or link to them.

[xzilja]

Not sure if it falls under the issue, but I'd love to dive deeper into concepts like reconciliation. While there plenty of examples available, it would be nice to have official docs covering this as well.

[gaearon]

@IljaDaderko Tell us more about what aspects you feel isn't adequately covered?

[michaeldera]

https://create-react-app.dev/docs/adding-typescript/

@michaeldera Have you found any external resources on this topic particularly helpful? E.g. https://github.com/typescript-cheatsheets/react? Maybe we could integrate or link to them.

It has been blogs on the most part and the guide on https://create-react-app.dev/docs/adding-typescript/, when I started out I fell back on code completion when I am using types.

[thmsrmbld]

I'd like to suggest a +1 on additional graphics / visuals on how React works from a lifecycle and structural perspective. I'm an extremely visual learner and I think it could be a good addition for those who respond easily to visual patterns rather than strictly logical ones.

Great work though thank you for your extremely clear writing.

[xzilja]

@gaearon Sure. I might be missing something, but to the best of my knowledge this https://github.com/facebook/react/blob/master/packages/react-dom/src/client/ReactDOM.js is closes to documentation there is for react-reconciler. When I was starting out, I referenced this file alongside some videos like https://www.youtube.com/watch?v=CGpMlWVcHok which helped out a lot.

With time I saw fewunstable_ methods pop up in react-dom's host config and it seems that some methods talked about in video above are no longer used i.e. supportsMutation.

For the most part, I am able to figure out what's going on by going through commits and following some people on twitter i.e. https://twitter.com/0xca0a (works on react-three-fiber)

As you can imagine relying on process above results in some confusion and probably doesn't cover some important parts. Hence, I'd love to see structured documentation around this, to dive deeper and better understand all these methods i.e. why are they needed, when are they fired etc... in my head I am imagining "advanced" section of docs for something like this.

[gaearon]

I think you're asking for documentation for creating custom renderers?

[xzilja]

@gaearon Yep exactly. Thought it might be an interesting addition if possible.

[rafgraph]

I’d like to see TypeScript become a first class citizen in the docs (it already is in create-react-app). My suggestion would be to have all code samples available in both JavaScript and TypeScript and be able to toggle between the two.

[trigunam]

Testing react is been quite a challenge due to various techniques we use with Enzyme and Jest. However if there are ways to test for unit and components separately and how to differentiate for React components would be a great addition. Cheers! Looking forward.

[technoplato]

When React Native did their site rewrite, they let the community help out. Can we do the same here? If so, is there a way to sign up? (No T Shirt necessary, just want to give back a little to the excellent tools that help produce my family’s livelihood 😊)

[technoplato]

I’d like to see TypeScript become a first class citizen in the docs (it already is in create-react-app). My suggestion would be to have all code samples available in both JavaScript and TypeScript and be able to toggle between the two.

Further on that, I’ve been tinkering with the idea of having a very lightweight solution to having your preferences “follow” you by default across sites.

Example: if I’m looking at React Native and I’m on a Mac and I want to view docs in TS, I’ve got to manually select those each time. I understand the docs pretty well at this point, but it still adds to the cognitive load every time I have to evaluate that “if” in my head... it would be awesome for doc publishers to be able to opt in to some super easy API to support that.

[GooBall]

I'm actually really interested in the idea of adding some more general introduction into computer science and the problems react tries to solve compared to other solutions (even compared to HTML/CSS/jQuery).

At first thought, it might seem a little outside the scope of the react documentation to supply people with that type of information, however the fact that react is now a starting point for so many new developers means there is a bit of a void in fundamental understanding that the documentation is well positioned to fill.

I've known a few devs who have been started on react right way and so they can't even begin to answer "why" they are using it (beyond "it's what the project is written in").

And on a more personal note, +1 for typescript examples for everything!

[markerikson]

@rafgraph , @technoplato : FWIW, @phryneas just built a great Remark plugin for the Redux Toolkit docs that lets us write code samples in TypeScript, automatically compiles them to JS as well, and generates tabs for each. I think the language selection is also (semi-?)persistent:

https://github.com/phryneas/remark-typescript-tools

Per the readme:

Currently it is aimed at docusaurus, but already pretty configurable. And it's open source, pull requests for more configuration options are always welcome ;)

You can see them in action here:

https://redux-toolkit.js.org/api/createSlice

Looks like the React docs are using Remark internally as well, so that could very well be added over here.

And @gaearon , yeah, I would strongly recommend that the React docs add a "Usage with TypeScript" section with at least the basics, and that page should definitely link to the React+TS Cheatsheet for more details.

FWIW, when we did a poll of /r/reactjs at the start of the year, the results showed that 50% of React devs were using plain JS, 48% were using TS, and 2% used Flow. So, potentially half the userbase is using TS at this point:

https://www.swyx.io/react-survey-2019/

[ChiragRupani]

There is good things going on refreshing React documentation - especially it would be nice it can cover some practical scenarios like Calling API, Showing loading indicator while doing async activity, some suggestions for form handling, input validation, designing services, common UI patterns like dialogs, file pickers, drop downs and other common design problems. It would be helpful to have examples for testing different scenarios and instead of separate section for testing - for each example how it can be tested should be right there.

However, if goal is to make to React to easy to understand then there is no need to archive class related doc and entire docs rewritten in hooks. Both Class and functional Component can be first class citizens. There can options for users to show example in hooks or class. Another way - to have Class Component all along and wherever applicable - both Class + Functional (using hooks) examples can be added. This way docs would be generic and more focus on React way and less on particular class/hooks way.

Also, as others said, it would be nice to have examples in TypeScript.

[darcusfenix]

I would like to see more about why React JS is "A declarative, efficient, and flexible JavaScript library for building user interfaces"

Declarative Views is so important ! there is not enough information about declarative views or declarative programing here

what do you think ?

[littlepoolshark]

I would like to see some in-depth and rigorous elaboration on the core terms of react

[twlite]

yes please

[debel27]

I would like to see some in-depth and rigorous elaboration on the core terms of react

If I had to pick one thing about doc improvement, it would be that. Some side articles written by the core team helped me really understand React and write better React code. Here are some of them :

• https://reactjs.org/blog/2015/12/18/react-components-elements-and-instances.html
• https://overreacted.io/react-as-a-ui-runtime/ (e.g. the "Inversion of Control" section)

I would be great to have them integrated in the doc somehow.

[maifeeulasad]

maybe some installation step like this : https://maifeeulasad.github.io/reactjs-beginner/day/0/

i think, as one should install node and etc. so these types of doc should be included in official doc.

[njzydark]

look forward to best practices examples

[adibfirman]

Please adding an interactive documentation, at the moment the documentation react is very useful, but when we can edit the example code on documentation it's easier to learn what's the meaning of that code, thanks

[laoshaw]

can you make the site layout customizable, e.g. I'd like to the content category/menu on the left side instead of the right side, also a day/night reading mode will be nice.

[rafgraph]

@rachelnabors there seems to be a decent amount of support in this thread for more TypeScript in the docs. Curious if you have data on when starting a new React project do people use plain JS, TypeScript, or Flow? I noticed that a question like this wasn't included in the React 2020 Community Survey.

[rafgraph]

As @markerikson mentioned:

FWIW, when we did a poll of /r/reactjs at the start of the year, the results showed that 50% of React devs were using plain JS, 48% were using TS, and 2% used Flow. So, potentially half the userbase is using TS at this point: https://www.swyx.io/react-survey-2019/

@rachelnabors does this seem accurate to you?

[bansalvks]

It feels good

[laoshaw]

@rachelnabors there seems to be a decent amount of support in this thread for more TypeScript in the docs. Curious if you have data on when starting a new React project do people use plain JS, TypeScript, or Flow? I noticed that a question like this wasn't included in the React 2020 Community Survey.

TS is yet another layer adding to the complex JS ecosystem and is in no way beginner friendly, I would strongly recommend React site just focus on native JS instead. When a beginner gets really comfortable with JS he/she might or might not move to TS...tutorial must be beginner friendly, the JS frontend's biggest problem is already too-much-info to begin with.

[keymastervn]

To me, people tend to meet TypeScript will find their way on the learning curves. Plain JS and dynamic-typed languages have their missions for a friendly happy coding experience, in contrast to TypeScript that may creates complexity and confusion to some starter levels.

[phryneas]

Which is why it would be great if

• every example would exist in pure JavaScript
• every example would also exist in TypeScript so that people who want to know how that would look in TypeScript could just look at the example in TypeScript and JavaScript and compare the two.

You know, not make TypeScript more difficult than it already is by having people guess how to use it, but give people tangible examples that show them how it could be used - without forcing them to use it of course. See the examples from the redux toolkit docs that @markerikson linked above.

[jakubdrozdek]

I remember learning Rust language not longer than 1 year ago. I got really surprised by the number of different approaches in the documentation. They linked to an "example-based" version for people who prefer learning that way. There was also a strict reference guide for oldboys. And they even had simple exercises (katas) in a repo you could clone, that included tests and some failing code. I know that's a lot and I can imagine they are maintained by different groups, but I've never seen anything like that and was really delighted. Worth keeping in mind that people learn in different ways.

I'd say we need more examples, written in both TS and JS, that could be run in the browser. I remember learning from W3Schools at some point and it was very valuable for me to be able to test the code without loosing context and focus. But I'm happy enough with the output comments in the code :)

I'd like to see more structural and testing best practices, and some explanation WHY it's the best practice and what problem does it solve. Common pitfalls would be great, too, since React lets you write the code in thousand different ways, while some of them lead to doom. I know there are lots of examples in the current docs, but there could be more, especially for high-level architecture.

[technoplato]

@rachelnabors @gaearon This issue is getting a little cluttered, but is there going to be a thread on how we can help or are you keeping this rewrite as an internal task?

[gaearon]

We're keeping this issue for free-form comments and ideas although we don't promise to respond to every one of those (but we do read through them all regularly). We haven't started any writing yet so there isn't anything you can help with at this point. But when we get to a place that we have something to show, we'll update the thread and possibly spin up subthreads for specific things where the community could help.