New "Learn" Docs Section for Async

[crutchcorn]

At React Conf 2025, there were a number of conversations around how we could improve the React.dev docs story around async features in React. In particular, it feels like many APIs are solely documented in the reference documentation section.

I'd like to propose that we introduce a new section in the "Learn" docs that covers:

• Suspense/Suspending
• Transitions/Actions
• Optimistic/Pending
• Concurrent Stores (eventually)

Maybe we could name this section as something like "Handling Data"? In my opinion, it would make sense to structure these pages as:

1. Fetching asynchronous data (use, Suspense, cache, cacheSignal)
2. Handling user interactions (<form action>, startTransition)
3. Improving user experience around data (useOptimistic, useTransition)

And going from there.

Bike-sheds on terms here are welcomed as I know naming can be critical for others' understanding.

Once we figure out a good structure for these docs, I'm happy to begin working on the docs pages related to this and we can do a more in-depth review in PRs

[markerikson]

I think @rickhanlonii 's talk from ReactConf is a good conceptual starting point for these docs. I'm generally picturing some sections that cover:

• Common async patterns with React
• How modern React makes those patterns simpler and provides better UX
• Introduces concepts like "transitions" in a unified way and shows what problems they help solve so that learners even know what they are and why they're useful (without knowing to look at a page like the useTransition docs ahead of time)

[crutchcorn]

Absolutely agree, especially on the "how React makes patterns in UX easier". I want to make sure that these pages demonstrate pragmatic challenges in even non-concurrent variants of React code.

I think we can do this with a number of Before and After demos and videos

[gaearon]

I'd generally try to steer in favor of "just explaining how to use it" rather than "before/after". Since the majority of React users always exist in the future, and comparing with the past does not necessarily help them understand.

The Learn section generally assumes React is the first programming language/library they're learning. This is not necessarily best for everyone, but for an increasing number of people, this will be true over time. And we want to make sure that the Learn section doesn't suffer from getting stale over time as e.g. blogs do. This is why "just show how it works" is generally favored over "here's why it's better than approach A or approach B you've been using before".

That said, sometimes there's some fundamental shift we need to explain, e.g. first part of https://react.dev/learn/reacting-to-input-with-state is a concession to that (understanding imperative vs declarative is too useful, even if you're not writing imperative UI code). I don't think it hurts to have these, but we should always think about what it feels for someone who's learning programming now and this is their first UI framework.

If we think Async React is better, we should be able to mostly explain it "on its own".

[rickhanlonii]

Thanks for starting this convo, I have some ideas for this so I'll do a brain dump.

Quick

Some quick things we can ship:

• Better use(promise) reference docs: these docs should provide some basic examples of using use(promise). The only docs there assume you're passing the promise from the server. I think we could document using a global Map() cache that is useful as a replacement for fetching in an effect, and provide a deep dive on revalidation (i.e. how and when to clear the cache and trigger a refresh).
• Better useOptimistic reference docs: these docs should provide better explanation of what useOptimistic is. It currently only documents using it with form actions, doesn't say that the reducer arg is optional, and doesn't really help you understand what it is. We also need to provide a ton more usage examples including:
  • Adding optimistic updates for action props: show how to use useOptimistic in a design component so the component always updates immediately while the Action is in progress. Like the tab bar from my talk demo.
  • Adding optimistic updates to your app: Even if you're using an action prop, there are many use cases where the product code may want to add some additional optimistic state, in addition to the automatic optimistic feedback provided. For example, in my demo you might want to also cross out the item when it's marked complete while the mutation is in progress, or you might want to optimistically move the item to the complete tab.
  • Using the reducer: There should be a good, canonical example for when and how to use the reducer arg.
  • Handling errors / mismatched: If an action errors, or the value resolves to a different value than the optimistic one (like the value from the server has changed from a different user or tab) the optimistic value will automatically commit the newest actual value passed in.
• Better useActionState reference docs: these currently only explain how to use it with form actions. We need a better explain for when to use it, and good canonical examples of when you should use useActionState instead of Actions directly (like when you need to sequence Actions and reduce over the result for each submission).
• Add fragment refs to You Don't Need An Effect: The Sending a POST request is doing visibility logging, but this really should be done with an intersection observer instead of an effect or your impressions will be wrong in subtle ways (this is true of all UI frameworks, not a React thing). This could be updated to use a fragment ref and observeUsing.
• Add Actions to You Don't Need an Effect: Also in Sending a POST request, when you do need to do non-logging POSTs, we should recommend moving it to an event using an async action, and explain the benefits.
• Add use(promise) to You Don't Need an Effect: The Fetching Data explains how to fetch in an effect, I think this should get updated to how to use use(promise) instead.

Medium-ish

These are less concrete, but fairly straight forward:

• Design Component patterns: in the old concurrent mode patterns docs we recommended that design components call callbacks in transitions, but had to walk that back because we didn't have features like async transitions or use optimistic. Now that we do, we should have some kind of recommendation somewhere, and explanations for how to implement it. We kind of have this with the action prop docs, but we need more.
• Action props in existing Learn docs: This is tricky because the learn docs currently do a good job at incrementally introducing ideas like events and state, but in Async React world the Adding Interactivity section would be a log different. Instead of being event-handler first, I think it would be action prop first.
• Fragment refs learn docs: This could probably be in the Escape Hatches section with the other refs stuff. We also need to update the existing pages to use fragment refs where appropriate.

Bigger

Like you mentioned in the post, we need learn docs for these patterns.

I was thinking a new top level section like:

• Handling data

  • Getting remote data (Suspense)
  • Handling user actions (overview of the three paint and transitions, related to next two guides)
  • Submitting forms (Form actions, useFormStatus, as in introduction to action props)
  • Creating user actions (implementing your own action prop)
  • Showing pending feedback (useOptimistic)
  • Queuing sequential actions (useActionState)

• Improving UX

  • Updating the current page (transitions in the background)
  • Navigating to a new page (transition to suspense fallbacks)
  • Removing fallbacks for new routes (Activity pre-render use case)
  • Keep state when leaving a page (Activity)
  • Adding animations (walk though css/js/view transition option)
  • Animating page transitions (ViewTransition)

Some of this is tricky because if you're using a framework, or router/data/design libraries that support these patterns, then these docs are not relevant to you - this is just the way it works. But I think we can explain that somehow, so you know why the app works the way it does when you see it.

[rickhanlonii]

Done, I excluded the Bigger section because that probably deserves more discussion and separate posts before it's ready to be tasked out.

[rickhanlonii]

Actually, should I just create a separate post for each item?

[crutchcorn]

Yeah, I think the Bigger items might make sense for separate posts. The more immediate stuff is probably fine as-is since we can start working through them actionably

[gaearon]

Also in Sending a POST request, when you do need to do non-logging POSTs, we should recommend moving it to an event using an async action, and explain the benefits.

I'm not sure I see how actions are relevant there. The point of that example was to show separation between "things that correspond to events" and "things that correspond to effects". We're already showing an example where an event makes sense there, so converting everything to event there would miss the point of example.

From the article:

When you choose whether to put some logic into an event handler or an Effect, the main question you need to answer is what kind of logic it is from the user’s perspective. If this logic is caused by a particular interaction, keep it in the event handler. If it’s caused by the user seeing the component on the screen, keep it in the Effect.

[gaearon]

This is tricky because the learn docs currently do a good job at incrementally introducing ideas like events and state, but in Async React world the Adding Interactivity section would be a log different. Instead of being event-handler first, I think it would be action prop first.

I agree. See #2 (comment) for more thoughts on this. If we introduce async components, <Suspense>, and <form> in a separate section, it makes sense to introduce action there too — and to place that section before Adding Interactivity.

[markerikson]

Related: @rickhanlonii , did you have a chance to publish the demo app repo anywhere? If not, could you do that? Saw some folks asking to see the code.

[rickhanlonii]

Yeah, I'm working on that now. Here's the repo: https://github.com/rickhanlonii/async-react

I'm just trying to deploy it before sharing but getting hung up on cloudflare configs.

[gaearon]

I'd add that originally (when the docs were being written) Fetching Data was supposed to be a section that comes between Describing the UI and Adding Interactivity. That's also why Describing the UI was written without any client features.

The idea was to show Suspense etc before showing state because Suspensey data fetching is router-driven (at least in RSC), and using router doesn't force you to learn about state. Explaining patterns like Transitions and Suspense just relies on having a router. (Look at examples on https://react.dev/reference/react/Suspense — most of this stuff is not related to state.)

Indeed, in the default RSC environment you can't use state directly even if you want to, so it kind of makes sense to explain async components, <Suspense> and <form> before introducing 'use client' and all the client-related features. If you start with an RSC framework (as we recommend), the first environment you land in should probably be described first.

So the idea was that Describing the UI is universal, then Fetching Data teaches you declarative data fetching and patterns around that (and animations), and the next section (Adding Interactivity) is when we teach about 'use client' and the entire client-side world. (At the time, we also thought we might have a client-only version of RSC-like Server components by then, so it would work for teaching on the client too. This isn't about selling RSCs, it's just about conceptual ordering.)

This ended up getting deprioritized because it involved making decisions for how sandboxes should work (eg. what should the mock router be like, should it use a framework or a fake framework, should it be "true RSC", "RSC in a worker", "client-side RSC-like" thing, something client-only but with right conventions, etc.)

I would highly encourage whoever decides to pick up this section to avoid tying explanations to state (even if it ends up after Interactivity in the end) or making them seem like we're explaining complex concepts. In the end it's just async/await for data fetching, declaring glimmers with <Suspense>, and some patterns around when to move <Suspense> up/down the tree or give it keys. Same for <ViewTransition>. This can be taught very early. This can also be taught in a very beginner-friendly way with no need to get PhD in React. The concepts themselves are very intuitive if you look at the actual user-facing API in a world where popular libraries are already designed for async React.

[gaearon]

Do keep in mind that Learn section is supposed to be linear, i.e. topologically sorted with zero circular dependencies. The reader should be able to read it top to bottom without ever bumping into an explanation that depends on knowing some concept that has not been introduced yet. This is a hard constraint in the structure.

Therefore, if Fetching Data depends on state somewhere, it must either explain state somewhere in a limited way, or it must come after Adding Interactivity. Personally I think it would be better if it came before Adding Interactivity, and state-specific parts were merged into Adding Interactivity (like the "optimistic" stuff). Not all "concurrent" stuff belongs together in one section, it's just React. We just need to flag which parts depend on "new world".