Replacing render with createRoot

[rickhanlonii]

Overview

React 18 ships two root APIs, which we call the Legacy Root API and the New Root API.

• Legacy root API: This is the existing API called with ReactDOM.render. This creates a root running in “legacy” mode, which works exactly the same as React 17. Before release, we will add a warning to this API indicating that it’s deprecated and to switch to the New Root API.
• New root API: The new Root API is called with ReactDOM.createRoot. This creates a root running in React 18, which adds all of the improvements of React 18 and allows you to use concurrent features. This will be the root API moving forward.

Note: the New Root API is available by importing react-dom/client:

import * as ReactDOMClient from 'react-dom/client';

ReactDOMClient.createRoot(/*...*/);

ReactDOMClient.hydrateRoot(/*...*/);

For more information see #125.

What is a root?

In React, a “root” is a pointer to the top-level data structure that React uses to track a tree to render. In the legacy API, the root was opaque to the user because we attached it to the DOM element, and accessed it through the DOM node, never exposing it to the user:

import * as ReactDOM from 'react-dom';
import App from 'App';

const container = document.getElementById('app');

// Initial render.
ReactDOM.render(<App tab="home" />, container);

// During an update, React would access
// the root of the DOM element.
ReactDOM.render(<App tab="profile" />, container);

In the New Root API, the caller creates a root and then calls render on it:

import * as ReactDOMClient from 'react-dom/client';
import App from 'App';

const container = document.getElementById('app');

// Create a root.
const root = ReactDOMClient.createRoot(container);

// Initial render: Render an element to the root.
root.render(<App tab="home" />);

// During an update, there's no need to pass the container again.
root.render(<App tab="profile" />);

What are the differences?

There are a few reasons we changed the API.

First, this fixes some of the ergonomics of the API when running updates. As shown above, in the legacy API, you need to continue to pass the container into render, even though it never changes. This also mean that we don’t need to store the root on the DOM node, though we still do that today.

Second, this change allows us to remove the hydrate method and replace with with an option on the root; and remove the render callback, which does not make sense in a world with partial hydration.

What about hydration?

We’ve moved the hydrate function to a hydrateRoot API.

Before:

import * as ReactDOM from 'react-dom';
import App from 'App';

const container = document.getElementById('app');

// Render with hydration.
ReactDOM.hydrate(<App tab="home" />, container);

After:

import * as ReactDOMClient from 'react-dom/client';

import App from 'App';

const container = document.getElementById('app');

// Create *and* render a root with hydration.
const root = ReactDOMClient.hydrateRoot(container, <App tab="home" />);
// Unlike with createRoot, you don't need a separate root.render() call here

Note that unlike createRoot, hydrateRoot accepts the initial JSX as the second argument. This is because the initial client render is special and needs to match with the server tree.

If you want to update a root again after hydration, you can save it to a variable, just like with createRoot, and call root.render() later:

import * as ReactDOMClient from 'react-dom/client';
import App from 'App';

const container = document.getElementById('app');

// Create *and* render a root with hydration.
const root = ReactDOMClient.hydrateRoot(container, <App tab="home" />);

// You can later update it.
root.render(<App tab="profile" />);

What about the render callback?

In the legacy root API, you could pass render a callback that is called after the component is rendered or updated:

import * as ReactDOM from 'react-dom';
import App from 'App';

const container = document.getElementById('app');

ReactDOM.render(container, <App tab="home" />, function() {
  // Called after inital render or any update.
  console.log('rendered').
});

In the New Root API, we’ve removed this callback.

With partial hydration and progressive SSR, the timing for this callback would not match what the user expects. To avoid the confusion moving forward, we recommend using requestIdleCallback, setTimeout, or a ref callback on the root.

So instead of this:

import * as ReactDOMClient from 'react-dom/client';

function App() {
  return (
    <div>
      <h1>Hello World</h1>
    </div>
  );
}

const rootElement = document.getElementById("root");

ReactDOMClient.render(<App />, rootElement, () => console.log("renderered"));

You can do this:

import * as ReactDOMClient from 'react-dom/client';

function App({ callback }) {
  // Callback will be called when the div is first created.
  return (
    <div ref={callback}>
      <h1>Hello World</h1>
    </div>
  );
}

const rootElement = document.getElementById("root");

const root = ReactDOMClient.createRoot(rootElement);
root.render(<App callback={() => console.log("renderered")} />);

See codesandbox.

Why ship both?

We’re shipping the legacy API in React 18 for two reasons:

• Smooth upgrade: We want to avoid user upgrading to React 18 and immediately seeing a crash. Instead, we’re adding a warning to the legacy root API that recommends using the new API.
• Experimentation: Some apps may choose to run a production experiment to compare the legacy root with the new root which includes performance improvements out of the box. By including both, it’s easier to run experiments.

[M0nica]

Is it recommended that folks using ReactDOM.createRoot instead of ReactDOM.render should enable strict mode? #19 or is enabling strict mode only recommended for applications that are using React 18's using concurrent features?

[gaearon]

We'd like to think about these as two separate processes:

• render -> createRoot is part of the React 18 migration.
• StrictMode is optional in either case (before and after 18), but it helps surface bugs (before and after 18).

We'll describe how Concurrent Features interact with Strict Mode requirements a bit later separately. But the TLDR is:

• If your app runs well in Strict Mode after upgrading to createRoot, it's a good idea to keep it on.
• If your app breaks in Strict Mode, you probably want to figure out why and/or disable Strict Mode.
  • This doesn't necessarily mean you can't use Concurrent Features, but it's up to you to test that they work in your app.

Strict Mode is a bit pedantic, which is why even with createRoot it's not on by default. But it's helpful in general, and after more of the ecosystem is compatible with Strict Effects, it should be easier to just keep it on.

[markerikson]

Just to confirm: since ReactDOM.render() is shipped here, I assume it's technically possible to "update to React 18" by just bumping the package version and not changing the code here - just that you won't get any benefits, and that's not the intended upgrade path.

[gaearon]

I assume it's technically possible to "update to React 18" by just bumping the package version and not changing the code here - just that you won't get any benefits, and that's not the intended upgrade path.

It is technically possible but it will warn a deprecation message. This is for two reasons:

• Changes from createRoot itself are fairly limited and are on par with other React major releases. We expect that people will be able to upgrade without too much trouble (similar to migrating from React 15 to 16).
• We want libraries that declare 18 compatibility to not have to "worry" about being compatible both with createRoot and render. So in that sense it is assumed that 18 is createRoot, because render warns and it means you haven't fully completed the migration.

We kept both as a compromise so that it's possible to run both in production as an experiment and confirm the metrics didn't go down. But that is a temporary strategy, and we'd like to eventually remove render.

[chantastic]

Thanks for the clarification, @rickhanlonii. It's really nice to see the considerations invested into the root API change. I like that you jump right to it with terms: Legacy Root API and New Root API.

I haven't used the render callback in quite some time. But if there are known, legitimate use cases, it could be nice to see equivalent requestIdleCallback and setTimeout examples.

[rickhanlonii]

This is great feedback, I've added an example using a ref callback.

requestIdleCallback and setTimeout are more straight forward:

// Instead of this
ReactDOM.render(<App />, rootElement, callback);

// You can do this
ReactDOM.createRoot(rootElement).render(<App />);
requestIdleCallback(callback);

// Or this
ReactDOM.createRoot(rootElement).render(<App />);
setTimeout(callback, 0);

[chantastic]

Great thanks!

It's obviously been long enough that I didn't realize it wasn't doing anything that code-order couldn't :) Thanks you still for the examples 🙏

[lintonye]

// Or this
ReactDOM.createRoot(rootElement).render();
setTimeout(callback, 0);

@rickhanlonii Do you mind explaining the setTimeout example a bit more? Why does it achieve the same effect as the render callback?

[rickhanlonii]

@lintonye good question, they're not intended to be equivalent. Use the ref callback if you want to wait until the root component commits, use requestIdleTimeout if you want to just wait for low-priority idle time, and use setTimeout if you just want to wait until after React yields the first time.

[eps1lon]

Thanks for writing this down. It was one of the concerns that immediately jumped out when working on concurrent rendering in @testing-library/react.

Though this new API feels more awkward for our particular use case. In the default use case we create the container on the fly and already solve the "you don't need to constantly pass a container" problem. But now we have to make sure we're always keeping the container and root together (since we need to cleanup the container) which seems brittle to me.

And then there's ReactDOM.unmountComponentAtNode which no longer works with concurrent roots and already tricked one person up. It's not clear what root.unmount() solves over ReactDOM.unmountComponentAtNode() other than shifting from "tracking the container" to "tracking the root". Why this shift is valueable isn't entirely clear.

So for @testing-library/react all the new API does is adding more things to track. It's not a blocker as far as I can tell. It just feels like unnecessary churn to me personally.

[eps1lon]

Just a very naive ReactDOM.concurrentRender and ReactDOM.concurrentHydrate. Though I'm not sure how error prone that is (or if it even is problematic) when people alternate render with concurrentRender on the same container. And as you said, you probably want to stay in one "mode" so the new root API does make more sense in that regard.

Not very help, sorry. It's really just a nit at the end of the day.

[gaearon]

So concurrentRender doesn’t work great for a few reasons.

• It looks super technical. Concurrency is implementation detail! It’s the same reason we have useTransition rather than useBackgroundLaneConcurrently or such. What you’re trying to do is to make a React root and render something into it. We want naming to be user-centered, not implementation-centered.
• New root doesn’t actually activate concurrent behaviors on its own (if you don’t use new features). So it would be misleading too.

In terms of simplicity it’s hard to “beat” render. So the new API name needs to be similarly plain. And yes, if there’s no root object, this opens the door for thorny questions like how do you deal with different methods called on the same DOM node. Or if we introduce a new API that only works with new roots, where does that go.

[wardpeet]

If we accept that it’s separate then there’s a question of shape. Initially we made createRoot because we were planning other methods on the object. In addition to render and unmount. For example we had an explicit batching API directly on the root. We ended up removing that. But it’s nice to have this option to add more things to it in long term without cluttering the top-level namespace with more magic “associated with DOM node” APIs.

Adding it to the createRoot object does prevent bundlers from removing the code while minifying. However, it doesn't have to be a problem if the code is used in other parts of the framework.

[gaearon]

In case of React, almost all logic is shared so it doesn't benefit from tree shaking.

[sebmarkbage]

One change I'm planning on doing is moving scheduleHydration to the root instead of globally (or at least require it as an argument).

One benefit of a first class exposed object is that sequencing can be enforced. E.g. you can only scheduleHydration and unmount something that has already been created. We also had other similar plans for this that required a root to already have been created before you can do things with them. It's easy to get tripped up in imperative land when it's implied by sequence and you change the sequencing subtly by refactoring but there's nothing to tell you about it. This happened at FB.

Another benefit of the separate object is that we can warn if it gets cleaned up by GC using weakrefs. Because that means you're not ever calling unmount() on it. If it's a single root maybe you never need to, but if it's a multi root environment you probably should build that in.

Another goal was to get rid of the return argument from render. It's kind of a special ref that has synchronous constraints and has weird semantics compared to refs.

[wardpeet]

The callback example is great! In Gatsby we've now implemented it as a useEffect. Is there any difference in doing it as an effect or a ref?

root.render(<App callback={() => console.log("renderered")} />);

import ReactDOM from "react-dom";

function App({ callback }) {
  // Callback will be called when the div is first created.
  return (
    <div ref={callback}>
      <h1>Hello World</h1>
    </div>
  );
}

const rootElement = document.getElementById("root");

const root = ReactDOM.createRoot(rootElement);
root.render(<App callback={() => console.log("renderered")} />);

[gaearon]

Ref will fire synchronously when the div is added to the DOM. Effects fire with a small delay (after the browser paint). So this depends on what exactly you want to do in this callback.

[wardpeet]

Thank you. useEffect is what we want 👍

[gaearon]

We've just made changes to hydration in the latest alpha cut. Specifically, createRoot(container, { hydrate: true }).render(<App />) from earlier Alphas becomes hydrateRoot(container, <App />). It still returns a root object with a render method in case you want to update it later. But since hydration is special and the first render has to match up the server-generated one (and has other semantic differences like never getting batched with other renders), we're special-casing it in the API.

This allows to clearly separate the hydration-only options from general createRoot options.

[timneutkens]

We've implemented the new hydrateRoot API in Next.js 👍 vercel/next.js#26664

[rickhanlonii]

Update: we will now warn when using ReactDOM.render in React 18.

See facebook/react#21652 for more details.

[eps1lon]

Continuing reduxjs/react-redux#1808 (comment) here. /cc @acdlite

I think this warning is fine for usage in user-facing code since it's a one-time warning.

However, in tests this warning can be excessive depending on the test runner (e.g. jest.resetModules) or unpredictable (changes depending on what test is run first).

It's also fairly common for tests to fail if any console warnings or errors are issued. In those scenarios there's little difference between outright removing ReactDOM.render and warning on ReactDOM.render because both scenarios cause a test failure.

Combined with the general direction that "createRoot is the default in React 18" we decided to default to createRoot in React Testing Library.

@acdlite voiced some concern that this overly negatively impacts adoption the more a test suite uses actions that are not part of React Testing Library. The thinking is that act is not widely adopted since the "missing act" warning was missing from a lot of updates. React Testing Library APIs are safe since we already wrap everything in act.

So we either

1. not use createRoot and tell people to "just ignore the warning" (which is not trivial and reduces confidence in warnings issued by React)
2. use createRoot and tell people to use act more

Both of these cases require teaching which won't reach everybody.

For a smoother migration path, it may make sense to export a render and hydrate from react-dom/test-utils that doesn't issue a deprecation warning. Though I would understand if this is rejected due to the added maintenance burden.

React Testing Library could also temporarily mock console.error and ignore the warning. Though I'm personally not a fan of adding more stackframes to console calls. Especially in tests it oftentimes negatively impacts debugging.

[sebmarkbage]

The main reason it's even there in the first place is to allow for the opportunity to find the callers which is not always trivial to do statically. However, for tests that fail, that's easy.

I'd argue that maybe the first thing as part of adoption is to update the tests before you turn it on in production. If you think of it from that perspective, it's an easy task to go through each failing test one by one and upgrade. This can be done without ever checking in the new version of React in your codebase.

If anything it's a good opportunity to flush out early errors that happen before you put it into production.

It's annoying because you don't get to the "fun" part as quickly but in terms of incrementally upgrading it doesn't add any additional burden - it just shifts the order of work.

If that's too burdensome, then I suspect there needs to be a different strategy all together because shifting around when you do it won't affect the end state much.

[rickhanlonii]

Agree with @sebmarkbage, we shouldn't make it easier to run createRoot in prod without your tests passing first, so I would just go straight to createRoot. Any major version upgrade may cause some tests to break (see also: Jest major versions), so it doesn't increase the burden of upgrading more than any other major might and in this case the fix is fairly straightforward.

[eps1lon]

If you want to update a root again after hydration, you can save it to a variable, just like with createRoot, and call root.render() later:

How would I know when this hydration is completed? For example, the following naive approach currently issues a hydration warning:

const ui = <input />;
const container = document.getElementById("root");
container.innerHTML = renderToString(ui);

const root = hydrateRoot(container, ui);
root.render(<h1 />);

I could imagine a UI that calls root.render from a hydrated boundary before the complete UI is hydrated. Would that still trigger hydration mismatch warnings?

[sebmarkbage]

That’s a known bug we have in our tracker.

The initial render is not supposed to get batched with other renders (where as multiple render calls on the root can).

cc @acdlite

[eps1lon]

Following up that this is fixed now. We get an recoverable error issued: "Error: This root received an early update, before anything was able hydrate. Switched the entire root to client rendering." (https://codesandbox.io/s/react-18-hydrateable-root-early-update-47ps0h?file=/src/index.js)

[sebmarkbage]

You can wrap hydrateRoot in flushSync if you want to force two passes. You can alternatively make the second render async by wrapping it in startTransition instead.

[eps1lon]

Yeah sure. This was more about a potentially confusing error message ("hydration mismatch"). The new warning makes it clearer where the issue may lie.

[chantastic]

Hey friends!

There's "react-callback" implementation that I see making the rounds that I was hoping to get a sense for here.

In an effort to return a ref, without inserting a wrapping element, it does the following:

• renders children inside a fragment
• renders a sibling div with the ref callback
• onMount removes the temporary element

https://github.com/Tyson-Skiba/react-callback/blob/main/index.tsx#L1-L26

// https://github.com/Tyson-Skiba/react-callback/blob/main/index.tsx#L1-L26
type Callback = (() => void) | undefined;

interface CallbackProps  {
    callback?: Callback;
    children: React.ReactChild | React.ReactNodeArray;
}

const onMount = (element: HTMLDivElement | null, callback: Callback) => {
    if (callback) callback();
    if (element && element.parentElement) element.parentElement.removeChild(element);
}

export const CallbackWrapper: React.FC<CallbackProps> = ({
    callback,
    children
}) => (
    <>
        { children }
        <div
            ref={element => onMount(element, callback)}
            style={{ display: 'none' }}
        />
    </>
)

I guess my big question is: is there a case where this is actually a recommended practice?

In this case, the returned DOM element has no utility.
But does the method serve any utility that a post-render setTimeout doesn't?

[sebmarkbage]

No. The problem with how this works is that it triggers reflows of layout unnecessarily and for SSR likely messes with measurements like LCP that Google uses.

There's actually a warning if you try to pass a callback to the render() method.

render(...): does not support the second callback argument. To execute a side effect after rendering, declare it in a component body with useEffect().

You can achieve the same effect by just using useEffect instead of a ref (or useLayoutEffect which gives you the same timing).

But does the method serve any utility that a post-render setTimeout doesn't?

Not sure about what you mean about setTimeout. That would potentially fire post-paint and maybe not be equivalent so that wouldn't work but useLayoutEffect would be exactly the same.

[sebmarkbage]

Strict Mode does tend to fire effects twice since it needs to be resilient to hiding and showing. However, it should also do that for refs and if it doesn't, that's a bug.

You can avoid the duplications with a ref.

export const CallbackWrapper: React.FC<CallbackProps> = ({
    callback,
    children
}) => {
  let once = useRef(false);
  useLayoutEffect(() = {
    if (once.current) return;
    once.current = true;
    callback();
  }, [callback]);
  return children;
}

[chantastic]

Thanks @sebmarkbage for the clarification around the timing issues. And I really appreciate the useLayoutEffect example. I'll propose this in the places I've seen it crop up and link this discussion.

[sebmarkbage]

Some background on this change, it's sometimes assumed that this callback refers to the whole tree. However, with Suspense and its surrounding features, you can only be sure that a particular component is done. Since the Suspense boundaries are done later.

Similarly, you can't use this measure that "hydration" is done since those other boundaries can be hydrated later asynchronously.

That's why this API as a global callback doesn't make sense. It's more associated with a particular component, which the workaround makes clear. Depending on use case, this distinction might or might not matter.

[chantastic]

Thanks for the additional clarification.

It's an interesting time rn, because I see a lot of folks trying to "add Concurrent rending support" in the abstract without any concrete code to take advantage of it. So knowing precisely why this is discouraged is great.