useControlledState: parent-driven value changes are ignored when there is no DOM

[caycecollins]

Provide a general summary of the issue here

useControlledState tracks the current value in valueRef and resyncs it after each render via useEarlyEffect. That effect is a no-op whenever there is no DOM:

const useEarlyEffect = typeof document !== 'undefined'
  ? (React['useInsertionEffect'] ?? React.useLayoutEffect)
  : () => {};

typeof document reads as an "am I server-rendering?" test, but it isn't one — React Native, react-test-renderer under node, Ink and any other custom reconciler are real, interactive renderers with no DOM. In all of them valueRef is only ever advanced from inside setValue. Once the parent changes the controlled value on its own, the ref is stale, Object.is(valueRef.current, newValue) starts matching for the wrong reason, and setValue returns early without calling onChange.

🤔 Expected Behavior?

After the parent changes the controlled value, calling setValue with a different value calls onChange.

😯 Current Behavior

onChange is never called again, and the control is stuck permanently — every later setValue computes the same value that is sitting in the stale ref, so it keeps short-circuiting.

Via useToggleState, a checkbox that the user checks once and the parent then unchecks can no longer be checked at all.

💁 Possible Solution

Fall back to useEffect rather than to a no-op — the usual useIsomorphicLayoutEffect shape:

 const useEarlyEffect = typeof document !== 'undefined'
   ? (React['useInsertionEffect'] ?? React.useLayoutEffect)
-  : () => {};
+  : useEffect;

Effects don't run during SSR, so that stays warning-free, and the ref stays synced anywhere effects do run. I've confirmed this makes the repro below pass.

🔦 Context

Hit through useToggleState in a React Native app: a checkbox is checked by the user, the parent later resets it to false in response to an unrelated edit, and from then on tapping it does nothing. A submit button was gated on that checkbox, so there was no way forward on the screen.

🖥️ Steps to Reproduce

No React Native needed — any environment without a DOM shows it. react-test-renderer in a plain node process is enough.

import {useState} from 'react';
import TestRenderer, {act} from 'react-test-renderer';
import {useControlledState} from 'react-stately/useControlledState';

globalThis.IS_REACT_ACT_ENVIRONMENT = true;

test('onChange still fires after the parent changes the controlled value', () => {
  const calls = [];
  let setParent;
  let setInner;

  function Child({value, onChange}) {
    const [, setValue] = useControlledState(value, false, onChange);
    setInner = setValue;
    return null;
  }

  function Parent() {
    const [value, setValue] = useState(false);
    setParent = setValue;
    return <Child value={value} onChange={(v) => { calls.push(v); setValue(v); }} />;
  }

  act(() => { TestRenderer.create(<Parent />); });

  // 1. the control sets it -> onChange fires, parent goes true
  act(() => { setInner(true); });
  expect(calls).toEqual([true]);

  // 2. the parent resets it on its own, NOT through the control
  act(() => { setParent(false); });

  // 3. the control sets it again -> onChange should fire again
  act(() => { setInner(true); });
  expect(calls).toEqual([true, true]);   // fails: still [true]
});

Step 3 works if step 1 is skipped, which is what makes this easy to miss in practice.

Adding globalThis.document = {} before react-stately is first imported — changing nothing else — makes the same test pass, which isolates the guard as the cause. valueRef.current is true throughout steps 2 and 3 while the rendered value is false.

Version

react-stately 3.49.0. The guard is unchanged on main, and is present in 3.46.0–3.48.0 as well, so this is not fixed by upgrading.

What browsers are you seeing the problem on?

Other

If other, please specify.

Not a browser — any renderer without a DOM. Verified on React Native (0.81, Hermes, both iOS and Android) and with react-test-renderer in node. The web is unaffected.

What operating system are you using?

macOS (host); reproduced on iOS and Android

[snowystinger]

In cases like React Native, do they not have useLayoutEffect? I ask because the reason it's useInsertionEffect and falling back to useLayoutEffect is that there are some timing sensitive problems that can result in a stale state anyways when it's as late as useEffect because it's not run synchronously like the other two.

[caycecollins]

Yep, RN has both, and you're right — my suggestion was the wrong fix. Scratch it.

Digging into it, the effect choice was never really the problem. The condition is. typeof document tests for a DOM, but the thing it's guarding against is SSR — where effects don't run and useLayoutEffect warns. React Native has no DOM and isn't SSR, so it takes the no-op branch for a reason that doesn't apply to it.

window splits those apart. RN sets global.window = global in Libraries/Core/setUpGlobals.js; a Node SSR process has neither:

-const useEarlyEffect = typeof document !== 'undefined'
+const useEarlyEffect = typeof window !== 'undefined'
   ? (React['useInsertionEffect'] ?? React.useLayoutEffect)
   : () => {};

Synchronous effect stays exactly as-is, SSR still no-ops.

On your timing point — I went and tested it rather than guessing, and you were right to flag it. A setValue fired during the layout phase runs before passive effects, so with a useEffect resync the ref is still stale and onChange is still swallowed. Under RN's global shape (window defined, document undefined, no DOM):

resync	original repro	setValue from a layout effect
() => {} (today)	fails	fails
useEffect (what I suggested)	passes	fails
useInsertionEffect ?? useLayoutEffect	passes	passes

We're shipping the typeof window version as a patch on our side and it's green against a real Hermes build, which also confirms RN does define window — otherwise it'd no-op and our regression test would've caught it.

One caveat I should flag rather than let you find: typeof window fixes React Native, but it doesn't help a DOM-less renderer hosted in Node — Ink, or react-test-renderer in a plain node process — since those look exactly like SSR to any global sniffing. If you'd want those covered too, it'd need a signal that isn't a global. RN is the case with real users behind it, so that may not be worth it, but it's your call and I didn't want to oversell the one-liner.

[snowystinger]

The check for window looks correct, we use that in other places. Would you like to open a PR?

Please try to keep the copy and paste from AI Agents to a minimum, it's a ton of text to read (time consuming) and it's pretty demoralising. If I wanted to talk to an AI Agent, I'd go talk to an AI Agent.

[caycecollins]

The check for window looks correct, we use that in other places. Would you like to open a PR?

Please try to keep the copy and paste from AI Agents to a minimum, it's a ton of text to read (time consuming) and it's pretty demoralising. If I wanted to talk to an AI Agent, I'd go talk to an AI Agent.

sorry, this was an issue that came up in my claude code session today and it seemed fine to let it post and respond automatically (via gh api), most open source repos appreciate the detail it provides.

I can try to get PR up, but frankly it would be through a claude code session. If you're fine with that then sure, but as you said you could probably do it yourself just the same and avoid the demoralizing ai contribution(s) that I would bring with it due to time constraints.

[snowystinger]

Thank you for taking the time to respond. We are fine with AI contributions, we just want the human involved as well. Apologies that you were the one to end up with the message. It's become a bit of a slog as many times the AI doesn't stop to consider what they are doing, they just want to "minimize the blast radius" or whatever, and as a result we end up in long reviews that feel like we are against them. AI still isn't great at working on UI, especially in this library, as we deal with really low level bugs a lot of times that haven't been seen before. I think your issue is plenty straightforward though that AI shouldn't have a problem with it.

[su-jin1425]

Hi, I’d like to work on this issue if it’s still available. I’ll investigate the useEarlyEffect environment check, add a regression test for non-DOM environments, and prepare a focused fix. Please let me know if anyone is already working on it.

[caycecollins]

Hi, I’d like to work on this issue if it’s still available. I’ll investigate the useEarlyEffect environment check, add a regression test for non-DOM environments, and prepare a focused fix. Please let me know if anyone is already working on it.

I have not, feel free to take it

[su-jin1425]

Great i will work on it.