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.

[WilsonNet]

Hi guys, the new docs is pretty awesome, much more beginner-friendly than the last one.

In the Keeping Component Pures article, there is nothing explaining how to behave when you need impure functions. Like Math.random() and Date.now()

It gets a little confusing when you say, Same inputs, same output. Given the same inputs, a component should always return the same JSX. I think this can cause a little confusion like: "That means I can never use Math.random() inside a react app?"

The explanation for side effects is good, but I think impure functions should also be addressed.

[pavankjadda]

Please provide an option to toggle between TS and JS in code snippets. Otherwise this new code snippets would not be useful for many people who use React with TS.

[atomiks]

I was directed here after writing a thread on Twitter expressing my concerns about the content of the docs. I like the new design, but I think the Quick Start / Thinking in React, etc. guides could start from a more fundamental, more easily digestible manner that is friendlier to beginners.

I tried placing myself in my shoes when I was a beginner. I would be confused by the current docs, and the best way I learned was by experiencing the problems React tries to solve without using it. The biggest question I had was, "why does this even exist? I have built websites with jQuery just fine!" Explaining this fundamental question is important.

I know this may be a big pivot and may not be easy to incorporate, but I hope this is useful.

This does have trade-offs, in that they don't immediately start working with React and JSX syntax. I think building the fundamentals is far more effective, and less confusing in the long run though. Perhaps the docs could show separate cards of the learning direction the user wants to go in.

I wrote up an example I'd like to see in the docs 👇 (note: this is completely ignoring back-end solutions to the problem)

Show

## What is React? React is a JavaScript library for building user interfaces. It shines as an application becomes more complex by letting you build it out of small, individual pieces that work well together as a whole. [Picture of the above] Many developers find working in this model very useful when building their websites as it makes them easier to maintain and build upon as they grow. It’s important to mention that you don’t **need** React to build a website. React is a tool to make building user interfaces easier, but it’s not required to do so. Most developers have started using React and similar libraries as they make building front-ends easier, providing useful sugar on top of raw HTML and JavaScript. To start using React, it's recommended you have a basic understanding of HTML and JavaScript. These are the foundations for working with React, and will help guide you in your learning experience. ## Why React? The best way to understand React is to first experience the problems it solves. We’re going to start with a common example of where React comes in handy. Imagine you are displaying a static list of reviews on your website about a project you built. Each review has 3 elements: the avatar of the person, their name, and the message of the review. ```html

Mark

The project is great!

``` [Picture of the above] What if we wanted to display two of these on our website? Well, we could duplicate it twice: ```html

Mark

The project is great!

Susan

I recommended this project to my family.

``` [Picture of the above] But, what if there were say, 10 of these? Duplicating them over and over again is cumbersome. If you also wanted to change something about each review, you'd need to repeat yourself 10 times. Imagine if these also appeared on another page — you'd be updating it everywhere and might miss some instances of it. Instead, let's use JavaScript to help us reduce this duplication by creating a single source of it. ```js function Review({ avatar, name, message }) { return `

${name}

${message}

`; } ``` This is a reusable "component" which receives arguments and returns a HTML string with those arguments interpolated in the string. We can call this function and assign it to the `body` innerHTML: ```js const markReview = Review({ avatar: "images/mark.jpg", name: "Mark", message: "This product is great!", }); const susanReview = Review({ avatar: "images/susan.jpg", name: "Susan", message: "I recommended this project to my family.", }); document.body.innerHTML = markReview + susanReview; ``` [Picture of the above] However, we're still repeating ourselves here. Where using JavaScript to build the list really shines is the ability to use **loops** and other features of the programming language — something HTML does not have! If we stored all of the review data as an array of objects, we could loop over them: ```js const reviews = [ { avatar: "images/mark.jpg", name: "Mark", message: "The product is great!", }, { avatar: "images/susan.jpg", name: "Susan", message: "I recommended this project to my family.", }, // ... more reviews ]; const reviewsHTML = reviews.map((review) => Review(review)); document.body.innerHTML = reviewsHTML.join(""); ``` Now: - There is a single source of truth for all reviews. Want to update the markup of the reivews, for example to add a class to style it? Do it in one place, not 10. - We can loop over a plain array of data to generate each review. - The only repetition is each object of reviews data. Let's now imagine we wanted to add the date of each review. Since we only have one place to update, it's quick to do so! ```js function Review({ avatar, name, message, timestamp }) { return `

${name} ${timestamp ? `${timestamp}` : ""}

${message}

`; } const reviews = [ { avatar: "images/mark.jpg", name: "Mark", message: "The product is great!", timestamp: "Dec. 1, 2021", }, { avatar: "images/susan.jpg", name: "Susan", message: "I recommended this product to my family.", // missing timestamp }, ]; ``` Above, we can incrementally adopt the `timestamp` feature by conditionally adding the `` string only if the timestamp exists. ## State If we had many reviews, we probably don't want to display all of them at once. We might add a toggle to display the rest of the reviews if there are more than 3 when the user presses a button. This is where "state" comes in. ...and so on, gradually teaching each concept until: - They reach JSX syntax - Why React over returning template literals - Composing pieces to build something bigger - etc. The important thing here is that **each concept starts from its most primitive form and works its way up, without any extra stuff that can be distracting or indirect**.

[markerikson]

Yeah, I've always been a fan of helping people understand what problems a tool is designed to solve and why it exists. I'm not sure what the best place is to put that kind of info in the new React docs, but I do think it's worth including that somewhere.

FWIW, in the new Redux docs tutorial I did it by putting a section right up front on "What is Redux?", explaining its purpose and when you might want to consider using it:

• https://redux.js.org/tutorials/essentials/part-1-overview-concepts#what-is-redux

[ryota-murakami]

React working on browser as similar as PHP or traditional Server Side Temple Engine. That mean when display data changed, just re-render page based on new data without manual dom creation,removing.

That declarative approach makes harder to create dynamic visual effects like calucel, parallax than jQuery approach, but less fragile and scaling as well with great testability.

Finally JSX is 95% similar to HTML so there are various static site tooling despite JavaScript library.

[GuiYuanLu]

When will I see the new document officially launched?

[arnaudambro]

Hi everyone, @gaearon and @rachelnabors in particular,

Taking a bit of my holidays to update my knowledge about React, I just spent two hours reading the docs and I learned some cool stuff ! especially about how React works at its core. Really nice doc I must say !

Although at the end of all of it I'm still confused about how queueing works and how to change a loading state from, is loading to is not loading...

Let me quote the Queueing a Series of State Updates article:

React waits until all code in the event handlers has run before processing your state updates.

So why would this handleSubmit works ?

const AnyComponent = () => {

  const [isLoading, setIsLoading] = useState(false);

  const handleSubmit = async () => {
    setIsLoading(true);
    // do your async stuff, post your form wherever
    setIsLoading(false);
  }

  return (
    <form onSubmit={handleSubmit}>
      {{/* ...your form */}}
      <button type="submit">{isLoading ? 'Loading...' : 'Submit'}</button>
    </form>
  )
}

Why the setIsLoading(true) then setIsLoading(false) works - proved by the button changing its content from Submit to Loading..., then Submit again - if React really waits until all code in the event handlers has run before processing my state updates ?

Anyway, thanks for that doc, I'll suggest everyone (senior or junior dev) around me to have a look at it, it's great !

[Meligy]

@arnaudambro

Although at the end of all of it I'm still confused about how queueing works and how to change a loading state from, is loading to is not loading...

I think React understands that there's an async context (or at least setTimeout in my example, more on that in the Github link below), and creates a new render for it. See this example:

https://codesandbox.io/embed/kind-ramanujan-3rpgz?expanddevtools=1

There's a bit of explanation of this and how it changes in React 18 in here: "Automatic batching for fewer renders in React 18" https://github.com/reactwg/react-18/discussions/21

I haven't checked how much of that is in new docs yet.

Update

Also worth noting that the second setState call it not executed asynchronously. The event handler function exists before the await.

You can test this by moving the preventDefault() call after await. It will not work.

I got reminded of this by a tweet here:

https://twitter.com/jaimefebres/status/1477191104441163779

[JAYKALIA007]

Hi everyone. I would like to suggest a UI change that may increase the readability of the docs for users. How about when I'm reading the docs I get an option to hide the side navbar(the one on the left primarily)? It might be insignificant to some, but it would be nice if you consider it.

Lastly, I like the idea that you have replaced the class-based components completely with the functional ones. I say this because initially whenever came across the docs, I would stumble upon the class-based components, and stop there itself as the functional ones seemed hard to understand, especially the concept of the hooks. However now, when I'm actually reading and creating stuff via functional components, I find it not that hard.

[officialrajdeepsingh]

Hey everyone I'm trying to join react.js beta to help update react.js docs weekly. But I don't have any idea how to join reactjs team. Check out my work as a front-end developer.

https://officialrajdeepsingh.medium.com/

[gaearon]

There's been a bunch of feedback on how the current Quick Start doesn't make sense. I tried to write a new one. Feedback welcome.

https://github.com/reactjs/reactjs.org/pull/4245

[shotius]

I think, the old version of react docs has better fonts. It is more readable and does not strain eyes.

[HzK-0210181]

is the the new https://beta.reactjs.org/ postponed or what's happening it's still in 70% of the react content and 5% api reference and do you consider a good alternative ??

[gaearon]

We’ve had a break from December to February because of holidays, vacations, and planning, but we’re actively working on it now.

[wy2022]

Great programmers, working overtime on new documentation. Not limited to 996 working hours

[StanislavAlexandrov]

https://beta.reactjs.org/learn/state-a-components-memory

In the second example there is no check for end of SculptureList so once we get past the last index the example crashes. Not sure if it's important, but it's there.

[harish-sethuraman]

It is intentional since first challenge on the page state a component's memory is based on fixing this. :)

https://beta.reactjs.org/learn/state-a-components-memory#challenges

[HzK-0210181]

for the mean time, which website/websites/courses does react developers recommend for people to learn the new react-js ( with hooks ) i bumped into this one what do you guys think https://reactwithhooks.netlify.app/docs

[armenic]

for the mean time, which website/websites/courses does react developers recommend for people to learn the new react-js ( with hooks ) i bumped into this one what do you guys think https://reactwithhooks.netlify.app/docs

@HzK-0210181, I also started with reactwithhooks when there was no alternative. I think current state of Learn path in https://beta.reactjs.org/ is pretty good, at least I am enjoying it 👍

[dmitriid]

Text is too gray and too small.

A simple change:

.text-secondary {
   color: #111;
   font-size: 1.1em;
}

This makes the text so much more readable (looking at it on a 1080p 27" display) (no idea why main text is .text-secondary though)

Before:

After:

[yidingww]

I don't think this example of useRef 👇🏻 on https://beta.reactjs.org/learn/referencing-values-with-refs is good, in fact it can be quite confusing

It will make people confuse because if you change useRef to a pure function local variable like this below 👇🏻 , the same thing will still works (because the component never re-rendered), and it will make beginner to assume that local variable will also be persistent on each render 🤔

import { useRef } from 'react';

export default function Counter() {
  let ref = 0;

  function handleClick() {
    ref = ref + 1;
    alert('You clicked ' + ref + ' times!');
  }

  return (
    <button onClick={handleClick}>
      Click me!
    </button>
  );
}

[joaoeira]

You can delete text from the code examples by selecting text and pressing Ctrl+X even when the code example isn't interactive:

[dehghani-mehdi]

I just want to file an issue about using class component instead of hooks in the docs and saw this issue. Hope to see advanced react patterns (Render Prop, Prop Getters, ...) is the new docs too.

[ITenthusiasm]

Is there still going to be a section in the new docs that discusses how to handle uncontrolled inputs in React? I've found the current React docs a little misleading, as they seem to suggest that you need refs to access an input's value during form submissions. I'm assuming that isn't the intent.

I understand that since it's in React land, it's a little weird to hit on basic HTML/JS that could be touched up on simply by looking at the MDN docs. But at the same time, I feel like people starting off with React are just going to run with whatever the docs say -- forgetting/ignoring that there's even a normal HTML/JS world out there. That was at least my experience when I started with React. So if an uncontrolled section is included, I feel like some information on the non-React features could be helpful.

[markerikson]

I want to express some concerns with the current pace of progress on the new React beta docs.

First, let me prefix this by saying:

• The new beta docs are amazing and I absolutely love everything about the new content and structure
• I understand that the React team itself is small
• I know that React 18 release prep has been taking up the majority of the team's time
• I know that since the beta docs were first made available late last year, we've had Christmas break and start-of-year planning taking up time
• I've been closely following Dan's recent effort to work on the API docs pages and think those are wonderful

Having said that:

I am concerned at the somewhat slow pace of new content, the lack of a clear timeline for completing the docs and replacing the old ones, and the inability of the community to contribute to this effort.

As far as I can see, currently Dan is the only person working to fill out the new docs. I know Rachel has been a big part of the effort as well, but Rachel just announced today that she is leaving the React team. This leaves us with an apparent bus factor of 1 in regards to authoring the new docs.

This thread was started in October 2020. It took a year before the first new content went live. As of today, the content includes:

• Getting started instructions
• Tutorial content covering components, props, state, and reducers / context
• API reference pages for useState, useContext, and useRef

Just looking at the existing docs site, here's some topics that aren't covered yet:

• useEffect and side effects in general
• Forms
• Refs as a whole
• Performance
• Accessibility
• Fragments
• Reconciliation
• Interacting with non-React code
• Portals
• Code-splitting
• Patterns like render props and HOCs
• Data fetching and other async logic
• The rest of the hooks APIs
• The rest of the React APIs
• Testing
• The FAQ section
• Static typing (TS)

and that's without taking into account any other content that would be useful to have (JS core concepts like "closures", more details on how rendering works as a whole, more details on working with useEffect, new APIs in React 18, any potential discussion of additional tools and libraries from the community, etc).

Again, I think everything that is in the new docs so far is wonderful and I deeply appreciate the effort so far. But: at the current pace of progress, this feels like it's going to take at least the rest of 2022 to bring the docs to anything resembling a "completed" state, if not longer.

I understand the strong desire to have a single authoritative and consistent voice in the docs material.

But at this point, I would strongly request that we find a way to get the rest of the React community involved in contributing and filling out the rest of the new docs content! There's enough examples of the desired content and tone at this point that I think it's time to get the rest of the community involved, and focus on completing the content and fully switching over to the new docs site.

I realize that opening up the docs to a full free-for-all would likely become chaotic and hard to manage.

My suggestion would be a new "React Docs Working Group", using the same model as the existing React 18 Working Group. That way there's a specific list of contributors who can collaborate, a discussions forum to have discussions about the planned content, and it would be possible to help maintain some consistency in content and "authorial voice". (Plus, frankly, this thread has gotten utterly ridiculously long and should really be wrapped up.)

update

Rachel had some follow-up thoughts on Twitter about how a similar process worked well for the React Native docs:

https://twitter.com/rachelnabors/status/1497352542908473349

[martinszeltins]

Any news on the progress of the new docs? When will it be released?

[armenic]

In https://beta.reactjs.org/learn/choosing-the-state-structure#challenges #2 it should say '..., if you mark an item as packed...' instead of '..., if you mark a place as completed...'

[gaearon]

@armenic Please feel free to send a PR if you'd like!

[armenic]

@armenic Please feel free to send a PR if you'd like!

Thanks so much дэн, this is done #4536

[a89529294]

In https://beta.reactjs.org/learn/queueing-a-series-of-state-updates#react-batches-state-updates, this is said React waits until all code in the event handlers has run before processing your state updates. But when I worked on challenge 1 on the same page I noticed three re-renders for every click. Maybe there should be a mention on how React batch setState() differently in sync and async event handlers.

[gfox1984]

In https://beta.reactjs.org/learn/add-react-to-a-website#try-react-with-jsx, the link inside this paragraph is not fully functional:

You can play with transforming HTML markup into JSX using this online converter.

The babel compiler shows the following error:

Unknown option: .assumptions. Check out https://babeljs.io/docs/en/babel-core/#options for more information about options.

It works if you re-target Latest though: https://babeljs.io/en/repl#?browsers=&build=&builtIns=false&corejs=3.21&spec=false&loose=false&code_lz=DwIwrgLhD2B2AEcDCAbAlgYwNYF4DeAFAJTw4B88EAFmgM4B0tAphAMoQCGETBe86WJgBMAXJQBOYJvAC-RGWQBQ8FfAAyaQYuAB6cFDhkgA&debug=false&forceAllTransforms=false&shippedProposals=false&circleciRepo=&evaluate=false&fileSize=false&timeTravel=false&sourceType=module&lineWrap=true&presets=es2015%2Creact%2Cstage-2&prettier=false&targets=&version=7.17.8&externalPlugins=&assumptions=%7B%7D

[gaearon]

Would you mind sending a fix?

[k-123456]

Is there any React.js book available to learn for beginner like head first's brain friendly book series??

[fbclh]

@k-123456, not sure about Head First but there are a few good options: https://flaviocopes.com/page/react-handbook/ https://www.purereact.com/ https://www.roadtoreact.com/

[gaearon]

Let’s keep this on topic please.

[martinszeltins]

What to expect We’re aiming to launch the new docs in early 2021.

Is there a new timeline when the new docs will launch?

[gaearon]

We haven't been historically great at timelines, and I don't know if pulling a number out of my hat is going to be very helpful. But I'd like to have most of the remaining work done by mid summer.

[omrishooshan]

amazing content ! i enjoy the docs a lot, its like something ive never seen before in offical docs its actualy fun to learn

[zzz6519003]

so in which repo can we help to translate?

[thenewpark]

May I report a typo here? 🤔 In the sentence

Fortunately, you can remove isEmpty and instead check message.length === 0.'

from Reacting to input with state section, it seems message should be replaced with answer since a state named message doesn't exist in the example code. If it's intentional and I missed something, please let me know! 🙂

[Baribj]

Absolutely loved the new docs. can't wait for the new rest to come out.

There seems to be a bug with routing on Safari. See details beloe:

Bug description

On Safari iPhone (latest IOS and Safari Versions), the Safari native back button doesn't work as expected and clicking it causes screen to randomly jump here and there.

Steps to reproduce:

1- Go to Learning tab 2- Go to any topic 3- Scroll down to bottom 5- Click Safari back button

What should happen:

User should be taken back to the previous page.

What happens instead:

The page jumps around to seemingly random parts of the page with every back button click, when the back button is clicked multiple times, the page "tries" to load or something, and the blue progress bar at the top gets stuck.

Video of the issue

https://user-images.githubusercontent.com/94167701/164198642-bc14e402-a7cf-4209-b4a4-b31b0845dae2.mp4

[gfox1984]

In JavaScript in JSX with Curly Braces, challenge 3. Write an expression inside JSX curly braces, there is a note at the bottom that says:

To check that your fix worked, try changing the value of imageSize to 'b'. The image should resize after your edit.

Although changing the imageSize to b does change the source of the image, the image doesn't actually resize. This is because of the avatar class on the image, which enforces a height of 90px:

Either remove the note, or make sure the image visually resizes when its sources change. Else it will confuse the learner.

[moussa32]

How can i contribute and helping write in docs?

[asep19]

love so much the new docs. the ui is pleasant, the content is very well structured and easy to understand. Thank You, Thank You and Thank You

[dorward]

https://beta.reactjs.org/learn#adding-styles says:

In React, you specify a CSS class with className. It works the same way as HTML class attribute:

But that specifies an HTML class. CSS references HTML classes with class selectors. JavaScript references HTML classes with DOM methods. Other tools can reference them too.

Referring to them as CSS classes is a common mistake, but one which dismisses other ways of using them, so I would avoid it in any documentation.

[dorward]

https://beta.reactjs.org/ says:

Additionally, each page has a Feedback button in the corner. If you spot something that doesn’t make sense, please tell us!

The only feedback system I can see is a pair of thumbs up/down buttons which doesn't let any useful feedback be provided (even after switching to a browser which I don't have adblockers installed on).

[gaearon]

Yea sorry, we removed the freeform feedback on the website because the provider we used was pretty slow. I'd suggest using this thread for feedback.

[markerikson]

I'd like to re-request that the new beta docs at least be linked, visibly, from the existing docs site.

We consistently see questions in Reactiflux and the /r/reactjs Reddit with users saying "I heard that class components are old, but the tutorials still show them - what should I learn?", and have to respond to them by saying "here's the link to the beta docs, please read those instead".

Some recent examples of users wondering why the existing docs are outdated:

• https://www.reddit.com/r/reactjs/comments/uet337/whats_going_on_with_the_new_documentation/
• https://www.reddit.com/r/reactjs/comments/unnv3i/any_good_2022_react_documentation/

Unfortunately, the beta docs aren't visible anywhere on the main reactjs.org site :( There's no indication that they even exist, unless you read this thread.

Ideally, the existing docs site would have a banner saying "Check out the new beta docs -->", and also have callouts on the tutorial pages saying "see our new tutorials here -->". That would really help reduce the confusion.

As I've said several times, the content in the new beta docs is fantastic, and vastly better than the existing tutorials. Making readers aware that the new content is available will be a huge benefit to people who are trying to learn React right now, even if the rest of the beta docs material isn't filled out yet.

[cpwong]

Looking forward for the docs to go out of beta soon. This version is much better at guiding new learners to use hooks and functional components.

[gaearon]

I think docs on effects are a prerequisite before we can put any kind of banner. (I am working on them now.) Effects are what people struggle with the most. Maybe memo and callback too. After those I’d feel ok with a banner.