[Early Preview] New React Documentation

[rachelnabors]

Since announcing the start of the new React documentation effort, we’ve been busy writing the content and building a custom website designed around the learning experience. We are now ready to share this early preview of what we’ve created so far to get your feedback.

This early preview is deployed at beta.reactjs.org and is in active development.

Please leave any feedback in #3308.

TLDR

Visit the early preview of the new React Docs at beta.reactjs.org to find:

• All new learning materials featuring Hooks
• Interactive examples and challenges
• “Code diagrams” that visually dissect how Hooks work
• Illustrations and diagrams that explain how React works
• New site designed around learning experience

You may encounter some broken links—pardon our dust! Some content is yet to be released!

What's in the beta

The beta has two major sections:

• Learn React—a comprehensive, step-by-step guide to React. This section is roughly 70% complete. This content is stable and unlikely to change much beyond a few edits and fixes. Some content is still being written (notably, guides for effects, performance optimizations, and React DevTools).
• API Reference—detailed explanations of each API This section currently only has a few pages, so there is a lot left to write here! Have a look at the useState page to get a sense of what’s coming.

The landing page is a temporary stub and will be replaced closer to the end of the project. Similarly, the Home tab is a bit empty now—we intend to port over more things from the existing site, like Blog, after most of the remaining work is done.

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!)
• Performance. When we say “beta,” we mean the site as well as the content! We still have some perf optimizations to make like code splitting at a later stage.
• Accessibility. While we have been mindful of accessibility during production, we’re waiting until the site is close to getting out of beta to run a comprehensive accessibility audit.

What’s next

We will make an official post on the blog and put up a banner on the existing site to let visitors know where to find the new docs sometime after gathering feedback from this soft launch.

Once we achieve content parity with the old site, we’ll be ready to switch over to this one and keep the old one archived at a subdomain. We'll figure out which pages to redirect to which site at that stage—for now it's too early to discuss a plan. We intend to document all the stable React APIs before we switch over. That includes classes—however, they will be described on a separate page, while most of the docs will use Hooks.

Please note that:

• We are not ready to kick off any official translation efforts at this time because the content is still in a state of flux. (Update: we're kicking them off in [Beta] Translating New React Docs #4135.)
• To keep the tone cohesive, we are writing the primary new content ourselves. While offers to write are much appreciated, we must regretfully decline for now!

You can help!

• Read and share the docs with friends, colleagues, family!
• Report bugs! If you see one, please don’t hesitate to leave a comment here or send a fix to the beta folder in the main branch with the [Beta] tag in the title.
• Tell us what you think!

Where to leave feedback?

• Leave your general feedback in a comment in New React Docs #3308 or using this handy survey.
• Leave feedback as you read using the feedback button on the site

High-level feedback is more useful than e.g. typos since we'll be doing more editing passes on all the content (bug fixes for typos much appreciated!). We'd particularly appreciate feedback on how to organize the content (see #3965 (comment)).

Special thanks

Getting to this stage required a lot of effort from different people, whom we would like to thank and acknowledge. This includes:

• Rachel Nabors: editing, writing, illustrating
• Dan Abramov: writing, curriculum design
• Sylwia Vargas: example code
• Dan Lebowitz: design
• Razvan Gradinar: design
• Maggie Appleton: diagram system (not integrated yet)
• Jared Palmer: site development
• ThisDotLabs (Dane Grant, Dustin Goodman): site development
• CodeSandbox (Ives van Hoorne, Alex Moldovan, Jasper De Moor, Danilo Woznica): sandbox integration
• Rick Hanlon: site development

We'd also like to thank countless alpha testers and community members who gave us feedback along the way. Your support and encouragement meant the world to us over this longhaul project!

[simonw]

Bug report: on iOS in Mobile Safari I can type to edit the examples and it mostly works, but the "return" key fails to insert a new line for some reason (see how I'm pressing the return key here and it's not working)

FullSizeRender.mov

[weyert]

You have included an API key in this PR in one of your config files

[timdorr]

Just some immediate organizational feedback:

Since the sidebar is on the left now, that's where my eye is drawn first (ahead of the page content). Hence, when I saw this:

It looked rather barren to me. I don't know if it's the tab design, but it was non-obvious that the majority of the content I'm looking for is behind that Learn tab.

I would do one of the following:

1. Combine the Home and Learn tabs into one.
2. Make the Learn tab the default.
3. Improve the tab design to make clicking Learn more obvious somehow.

Honestly, I think combining Home and Learn is best. There's not much content on that tab anyways, so combining it with Learn doesn't create something too huge. Home also has content I'm not likely to be going to the docs for. I want to get info on a feature or API, not meet the React Core Team (no offense! I already know who you are 😄).

Perhaps you have more stuff planned for that section, which may make this a moot point. Still, I think it would be helpful to have the most likely destination immediately visible on page load.

Anyways, I hope that's helpful!

[gaearon]

@weyert

You have included an API key in this PR in one of your config files

Do you mind sharing which one? I assume it's probably intentional, e.g. Algolia needs one for search. Feel free to mail me <my username>@fb.com if there's something I overlooked.

[gaearon]

@timdorr

[The Home tab] looked rather barren to me. I don't know if it's the tab design, but it was non-obvious that the majority of the content I'm looking for is behind that Learn tab.

Home has very little content now, but we will later move Blog and a few other things there. So it seems a bit premature to restructure before we know how the rest of the things will look together, as we might have to split it back up. There will also be a different landing that will help decide "where to go" as well. But yeah, we'll definitely want to revisit the top-level grouping after 80% of the content is there.

[weyert]

You have included an API key in this PR in one of your config files

Do you mind sharing which one? I assume it's probably intentional, e.g. Algolia needs one for search. Feel free to mail me <my username>@fb.com if there's something I overlooked.

@gaearon Ah sorry for the false alarm, yes, it was Algolia. I have to admit I didn't bother to check what it was (it's sleeping time here)

[gaearon]

No worries, appreciate the diligence :)

[mochi-sann]

On a small screen like a smartphone, the line numbers overlap with the body of the code when scrolling horizontally, so I think the background of the line numbers should be colored.

RPReplay_Final1634870477.MP4

[gaearon]

On a small screen like a smartphone, the line numbers overlap with the body of the code when scrolling horizontally, so I think the background of the line numbers should be colored.

Oops. Pretty sure I broke it ... today. Thanks.

[valtism]

So happy this has landed 💙💙💙

Just noticed that with a mouse plugged in (macOS, Safari 15.4), the nav scrollbar is white. I don't know why this is the case, because when the content expands to fill more than 100vh it disappears and is dark again.

Also, dark mode selection does not persist. Would like it to be stored in localstorage or something.

[valtism]

Also, I can guess this may be in the works, but I'd love for the code (blocks as well as edit / runnable sections) to have a dark mode variant.

[gaearon]

I want to move a discussion from Reddit here because I'd love to hear more people's thoughts about this problem.

Original comment:

Is it just me or is the "Learn" section terribly organized? The quick start section has multiple chapters, each of which has a link at the end of it that brings you to another page that explains the same topic but in more detail? Then those pages have another "What you'll learn" section that link to yet more pages that seem to repeat the same or similar information as the sections on the previous page. None of this flows well from one section to another, and you can end up getting lost very easily. Why not just have a single page that fully describes each topic? Have it start of with introductory info and then continue into the more nuanced stuff. Then you'd have less pages, less linking, less repeat data, and a far easier to follow introduction for new people while still having an easy to parse doc for more experienced people looking for specific things.

this design is not something I see them changing at this point. But I hope that do.

---

My response:

The quick start section has multiple chapters

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.

So the idea behind this organization is to let you "zoom in" and "zoom out" of content. Each individual page is pretty detailed, so chapter index and site index are meant to let you skim through it (and decide whether you need to dive deeper or not).

But I know this idea is pretty polarizing so maybe we'll replace it by a regular short "list of chapters". The downside of that would be that there's no way to skim through the entire site/chapter's content without actually visiting every page.

this design is not something I see them changing at this point. But I hope that do.

On the contrary, index design is something we're very open to changing. I just hope we can come up with something better than a plain list of pages because that would make skimming very difficult. I've edited the announcement to clarify we'd love to hear more feedback on that.

One possible alternative approach we've been considering is to move all the "skimming" content into a separate subsection, like a React Crash Course, while keeping the indexes short and to the point. Then you decide which way to go.

---

I'd love to hear more thoughts on this. I feel like this criticism is very valid while also being a fan of "zoomable" content and not sure how to find the right balance and architecture here.

[gaearon]

(I will be cancelling builds despite merge because the deployment setup is.. not ideal. :P I need to figure out how to have two sites with different frameworks in one repo without them breaking each other. Something to do next week.)

[rmorshea]

Little typo:

With React, you will describe visual your logic in JavaScript.

[mayank99]

Just noticed that with a mouse plugged in (macOS, Safari 15.4), the nav scrollbar is white. I don't know why this is the case, because when the content expands to fill more than 100vh it disappears and is dark again.

Also, dark mode selection does not persist. Would like it to be stored in localstorage or something.

I noticed the same white scrollbars in dark theme (Chrome 95, Windows). I was able to fix it by setting color-scheme: dark light in Stylus, but I think a custom scrollbar would look even better (especially on Windows) and match the modern theme of the site.

[nickmccurdy]

Personally I like the new page structure, though the blog feels a bit out of place in the sidebar. Perhaps it should be its own tab like the other three sections.

[celmaun]

https://beta.reactjs.org/learn#chapter-2-overview-adding-interactivity

Why are the code examples full of state-staleness prone code?

const [person, setPerson] = useState({
  firstName: 'Barbara',
  lastName: 'Hepworth',
  email: 'bhepworth@sculpture.com'
});

function handleFirstNameChange(e) {
  setPerson({
    ...person,
    firstName: e.target.value
  });
}

function handleLastNameChange(e) {
  setPerson({
    ...person,
    lastName: e.target.value
  });
}

shouldn't it be...:

function handleFirstNameChange(e) {
  const firstName = e.target.value;

  setPerson((person) => ({
    ...person,
    firstName,
  }));
}

[rmorshea]

I think the "Quick Start" and "Describing the UI" titles could use some work.

To the first, I don't think it adequately summarize its contents. 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 that will allow me to gain a foundational understanding for what React is and how I should use it before actually running anything. Not inherently bad - just not what I expected.

To the second, from an inclusivity perspective, the use of the UI acronym in the title doesn't feel right. Most people will know what it means, but it feels like there ought to be a better way to summarize the content. Especially when in the first sentence of that page, the full term is used and then followed by the acronym:

React is a JavaScript library for rendering user interfaces (UI).

[spoike]

Chiming in from a non-mac keyboard user, search short-cut is Ctrl on Windows (and Linux I guess?) and not as rendered with Mac's command.

I'm a regular Mac user, but you might want to keep that in mind. ;-)

[kamkry]

A horizontal scrollbar shows up on every page because of the w-screen class. There's probably a margin or something higher up, and the content stretches outside of the page.

Quick fix:

Suggested change

	<article className="h-full mx-auto relative w-screen min-w-0">
	<article className="h-full mx-auto relative min-w-0">

[kamkry]

If we change overflow scroll to auto, the scrollbar will be visible only when needed

Suggested change

	<div className="h-auto lg:h-full overflow-y-scroll fixed flex flex-row lg:flex-col py-0 top-0 left-0 right-0 lg:max-w-xs w-full shadow lg:shadow-none z-50">
	<div className="h-auto lg:h-full overflow-y-auto fixed flex flex-row lg:flex-col py-0 top-0 left-0 right-0 lg:max-w-xs w-full shadow lg:shadow-none z-50">

What it looks like now:

After the change:

[valtism]

If we change overflow scroll to auto, the scrollbar will be visible only when needed

This was my first instinct too, but it's important because with the expanding categories you don't want the content to change width on expand. Having the scrollbar always visible solves that issue.

[kamkry]

Redux documentation works that way and I see no problems. An other option could be to just styling the scrollbar in the dark mode and maybe shrinking it to not take as much space as the native one.

[li-kai]

scrollbar-gutter is not very well supported yet, but it could be worth to go the extra mile to use overflow-y: auto; scrollbar-gutter: stable for browsers that support it and for those that don't, overflow-y: scroll.

[dcastil]

Congrats on the beta release, really enjoy the interactivity of the docs! ❤️

I have some feedback regarding the search. I saw that I can use cmd + K to search at the beginning and after a little browsing I hit the shortcut. I have the browser tab opened in fullscreen on a 24" monitor and the site looked broken to me because I just saw the overlay but not the expected modal. Just after a while I realized that the search input is on the left side.

Maybe it would make sense to put the search into the middle of the page when opened with cmd + K. Because no click happens, it's not obvious where to look for it.

Here is a comparison of the search bars after hitting cmd + K of the React docs and other web developer websites:

beta.reactjs.org	tailwindcss.com	create-react-app.dev	vercel.com

[gmoniava]

@gaearon
In the table from here:

You shouldn’t read (or write) the current value during rendering.	You can read state at any time. However, each render has its own snapshot of state which does not change.

Nothing is said about writing state during render, while about ref both read and write are mentioned. Why info about writing state during render is omitted from the table? (maybe I am allowed to write but inside if condition like getDerivedStateFromProps from old docs)

---

I had similar comment from here, says: "not change any objects or variables that existed before rendering—that would make them impure". Does this include state variables? What about getDerivedStateFromProps pattern?

Would be nice if we get some feedback on our comments, maybe at least "reaction"- otherwise it feels sometimes it is waste of our time.

[lintonye]

It's not immediately clear to me what this sentence means: "Where once you might have seen a forest, after working with React, you will appreciate the individual trees."

What do forest and trees refer to in this context?

[bobaekang]

I believe they're referring to an idiomatic expression: "can't see the forest for the trees".

Even so, I do agree that it's unclear how this expression/metaphor relates to the point they're trying to make: how React changes the way we think about designing apps. My best guess is that components-trees and the whole UI-forest, I.e. React allows us to see UI as a collection of components and pay attention on the latter.

[gaearon]

Yea I think this doesn't work here and needs to change.

[gaearon]

@gmoniava

Would be nice if we get some feedback on our comments, maybe at least "reaction"- otherwise it feels sometimes it is waste of our time.

We always go through comments in batches. Right now there are bigger things to do than address each individual one. (For example, we need to set up the builds so that they don't fail, and figure out how to run deploys for both sites without breaking each other.) So please be patient. You can be assured we will read all the feedback but please don't count on fast responses at this time. Also, due to the volume of feedback we get (here and elsewhere), I don't think it's reasonable to expect that we will "thumbs up" every single comment. However, as I said earlier, we do read them all.

[gaearon]

Thanks to everyone for commenting! We've decided to merge the beta website into a beta/ folder in the main branch of this repo so that we can keep iterating without having to maintain two drastically separate branches. (This will also fix the failing deployments that prevented PRs to this branch from building correctly.)

Since this PR is merged, to avoid confusion, we'd like to ask to direct all future feedback to #3308.

We haven't had a chance to go through all feedback in this thread yet, but it's all recorded in our todo list, so we will be making a pass over it as we get closer to completion.

[gaearon]

We're kicking off the translation process in #4135.