Intent to Ship: useId

[acdlite]

This feature is now available in the latest alphas

• useId facebook/react#22644

---

useId is an API for generating unique IDs on both the client and server, while avoiding hydration mismatches. We haven't documented it yet, but the API is probably what you expect:

function Checkbox() {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>Do you like React?</label>
      <input type="checkbox" name="react" id={id} />
    </>
  );
);

This solves an issue that already exists in React 17 and below, but it's even more important in React 18 because of how our streaming server renderer delivers HTML out-of-order. Solutions that may have worked previously, like using a counter to generate IDs, don't work in 18.0 because you can't rely on a consistent sequence.

@lunaruan implemented this API as useOpaqueIdentifier last year (facebook/react#17322), but because of some known bugs and limitations, we had intended to delay its release until after 18.0.

We've now fixed all the known bugs, and have a plan to address some of the limitations, so we do intend to ship it in React 18.

useOpaqueIdentifier -> useId

In the original proposal, useOpaqueIdentifier returns an opaque value. On the server, it's a string. But on the client, it's a special object that warns if you attempt to access the toString-ed value in userspace (as opposed to passing it directly to a DOM attribute). The reason for this is because React needs to be able to detect when an id is referenced inside a tree that wasn't server-rendered, so that it can resolve server-client mismatches. In the current implementation, we do this with a brand check: obj.$$typeof === REACT_OPAQUE_ID_TYPE. It also relies on the object's toString method to detect when the id is read on the client outside of a server-rendered tree (taking advantage of the fact that we don't modify attributes during hydration).

However, we received feedback that this restriction was too limiting. Some of the drawbacks include:

• Because the API is a hook, you can't create new ids dynamically — they must obey the hook rules. This doesn't scale well in practice. For example, to implement a form, you'd need a separate useOpaqueIdentifier hook instance per distinct form field. Example: Introducing an RFC for isomorphic IDs reactjs/rfcs#32 (comment)
• Some APIs like aria-labelledby accept multiple ids via a space-separated list. If you attempt to do this today, React will warn when you concatenate the ids.

To address both of these issues, we're changing the type to be a regular, non-opaque string.

React still needs to be able to detect these special ids when you pass them to an attribute. Instead of a brand check, when applying the attribute, React will check if the string includes a special sequence of characters (i.e. with str.indexOf(...) !== -1). The rest of the algorithm is unchanged. This new substring mechanism means you can add extra stuff to the beginning or end of the string, as long as the original string is still intact. [edit: Will likely go with a different implementation without this restriction.]

Now instead of generating a separate hook N times for N different ids, you can create a single base id for the whole form, then derive further ids from that one by appending a suffix:

function NameFields() {
  const id = useId();
  return (
    <div>
      <label htmlFor={id + '-firstName'}>First Name</label>
      <div>
        <input id={id + '-firstName'} type="text" />
      </div>
      <label htmlFor={id + '-lastName'}>Last Name</label>
      <div>
        <input id={id + '-lastName'} type="text" />
      </div>
    </div>
  );
}

In this example, because the React-generated id is globally unique, and the suffixes are locally unique, the derived ids are globally unique, too.

[eps1lon]

We've now fixed all the known bugs, so we intend to ship it in React 18.

So facebook/react#20127 is not a bug then?

There's also two use cases from the RFC that weren't adressed yet:

• feat: allow multiple opaque identifiers in HTML attributes facebook/react#18594
• Introducing an RFC for isomorphic IDs reactjs/rfcs#32 (comment)

I was under the impression that these would be adressed (#9 (reply in thread)) but this intent to ship makes it sound like this won't happen anymore?

[acdlite]

We have a plan for this, will write it up separately and publish soon (later today, maybe). API shape will be the same (but we'll likely rename the hook).

[acdlite]

Updated the post with additional information

[eps1lon]

Did I read this right and basically every issue I mentioned is now covered by this new hook? I'm so glad about his new API. Really appreciate the work that's gone into this hook and the responses to feedback 👍🏻

[devongovett]

This is awesome! We have a solution to this in React Aria, but the implementation is quite complex. Excited to use this instead once we can drop older React versions. 🥳

I'm curious how it's implemented in React. How are the ids generated on the server so they match on the client? Is it a counter that resets at every React root? How do you handle async/suspense boundaries? We had to introduce an extra context provider to wrap these to ensure the ids are generated consistently no matter the loading order, but I guess React could do that in the Suspense component? Would be curious to know more about how it works! (I guess I could also go read the code haha... 😉)

[acdlite]

The server maintains a counter, yeah. In the simple case, the client doesn't have to do anything special, because we don't patch attributes during hydration. We leave intact whatever the server sent.

The special case is when an id is referenced during a regular (non-hydration) client render. The first time that happens, we force the useId hook to upgrade to a client-generated id. That will cause everything that references that id to re-render with the new value. If some of those trees haven't hydrated yet, React will hydrate them first before applying the update (which is what we do for all updates that flow into dehydrated trees).

[sebmarkbage]

Note that the React Aria implementation wouldn't have worked if you have two different suspense boundaries within that context since they can be hydrated in either order, which may or may not have been the order they rendered on the server.

Also if you have two sibling contexts, you would've had to ensure that nothing suspends around either one because then they might get rerendered. Like if you suspend a sibling during hydration, it might rerender again without the memoized value. Or if you suspend a parent of the first context, but not the second one, it can continue render the second one on the server before the first one. Actually any component that's a sibling or parent of useSSRSafeId suspending could be causing this to be out of order.

That's why this is so important to ship as part of 18 because there's not really a good user space solution.

[sebmarkbage]

One implementation that could work would be to hash the key path of every component along the parents. That wouldn't be very efficient though.

Instead, we cheat and just make them not the same and deal with the edge cases where that matters.

[devongovett]

Yeah we currently require apps to wrap each suspense boundary in an additional nested SSRProvider to avoid the issue with loading order. This appends an additional counter to a stack so that each async boundary has a unique key space no matter what order the children load in.

Definitely based on the assumption that synchronous children render in a well defined order though. Is that not the case anymore? If not and this current implementation is not going to work anymore in 18, then I suppose we'll need to find a way to swap implementations depending on React version somehow. I doubt we'll be able to drop older versions soon...

[sebmarkbage]

Our general assumption is that you don't use Suspense boundaries nor suspending on the server before 18 since they error on the server. Similarly, we assume that you don't use those during hydration since you didn't use them on the server.

If you don't, then you can just use a global counter for the whole request and the whole hydration.

So the before 18 polyfill just needs to be useState(() => '' + (id++))

[sebmarkbage]

This implementation might rely on a hardcoded list of ID attribute names so list your favorite ID related attributes (aria or not) here!

[eps1lon]

Attributes related to one or less referenced elements:

• for
• form
• list
• Every ARIA attribute with the type of "ID reference":
  • aria-activedescendant
  • aria-errormessage

Attributes related to one or more referenced elemetns:

• for (only relevant for output with regard to one or more referenced elements): https://html.spec.whatwg.org/multipage/form-elements.html#the-output-element
• Every ARIA attribute with the type of "ID reference list":
  • aria-controls
  • aria-labelledby
  • aria-describedby
  • aria-details
  • aria-owns
  • aria-flowto

Other attributes:

• fill (see Intent to Ship: useId #111 (reply in thread))
• id for obvious reasons
• name (see Intent to Ship: useId #111 (reply in thread))
• data-* attributes may be used for debugging purposes? Don't have any concrete use cases though.

[sophiebits]

fill="url(#spaghetti)"

[eps1lon]

Adding name to this list to implement https://www.w3.org/TR/wai-aria-practices-1.1/#radiobutton by leveraging browser behavior. https://codesandbox.io/s/useid-for-name-hjfjd?file=/src/Demo.js has a full example.

[sebmarkbage]

From Twitter: https://twitter.com/sebmarkbage/status/1451358419546431489

If we used the tree index approach, we'd need to involve every node (Fiber) in the ID generation. Suspense boundaries only is not enough.

That's a long path. However, since we can assume that the number of children at each level is fixed (hydration should match exactly). We can allocate only as many bits for each level as there are children.

E.g. you can think of it as an S-expression tree. That's how many bits we need.

That might not actually lead to too long ID names. So we could try that approach too with same API.

[Andarist]

Somewhat related to the comment above: #111 (comment)

In Emotion we are, at the moment, conditionally wrapping (on the server) a top-level Emotion-aware component with a provider:
https://github.com/emotion-js/emotion/blob/516fe458058c9ec8218740472b301e935801ebbc/packages/react/src/context.js#L44-L67

This allowed us to provide a "zero-config" solution so far because this means that a separate cache gets created, automatically, per each server-side render (per request).

Given the concerns about the React tree having to be identical on the client and on the server, for useId to work properly - should we refactor this immediately? Or is usage like this "safe" (even if wonky)?

[gaearon]

I think this is a fair question we need to provide more clarity on: facebook/react#22733

[ad1992]

As mentioned in the post, using counter to generate id will not work anymore with html streaming on server, so this would be a breaking change for apps using a counter to generate ids, which should be addressed as part of migration guide ?

[gaearon]

The way I understand it, it would start affecting someone after they enable streaming and start using Suspense boundaries on the server (which is what enables content to be split into pieces). So you’re not running into this until you opt in. But yeah we should call that out as part of the adoption guide for streaming server rendering.

[ad1992]

yes exactly, mentioning it in adoption for streaming SSR guide would be helpful.

[gaearon]

We don't have a good one at the time yet so I think it's ok to defer. E.g. it's on a similar level to: ensuring you use a compatible CSS solution, <Head> solution, etc. We'd need to address all of these together when we write a guide for end users.