[Compiler Bug]: Error when calling `React.createElement(..., { ref })`

[jthemphill]

What kind of issue is this?

• React Compiler core (the JS output is incorrect, or your app works incorrectly after optimization)
• babel-plugin-react-compiler (build issue installing or using the Babel plugin)
• eslint-plugin-react-compiler (build issue installing or using the eslint plugin)
• react-compiler-healthcheck (build issue installing or using the healthcheck script)

Link to repro

https://playground.react.dev/#N4Igzg9grgTgxgUxALhAMygOzgFwJYSYAEMCaAkpgBI4C2ANgKL0K0KY4AUAlEcADrEicQmBwkyRALxEoYBACUynTFHr1uAbkFEJOWMSUBDXADo4pIzgTNW7LvxBwjmAG5GwjgDR8JaIgC+WoIBIAFAA

Repro steps

Playground link

This code:

function refInHtmlElement() {
  const ref = useRef(null);
  return React.createElement("canvas", { ref });
}

Has this error:

InvalidReact: Ref values (the current property) may not be accessed during render. (https://react.dev/reference/react/useRef) (3:3)

Even though we're using a ref in the way it's meant to be used. If we rewrite it in JSX, the error goes away:

function refInHtmlElement() {
  const ref = useRef(null);
  return <canvas ref={ref} />;
}

I find this behavior surprising, because I always thought that JSX desugared down to React.createElement anyway....

How often does this bug happen?

Every time

What version of React are you using?

Playground

What version of React Compiler are you using?

Playground

[duncpro]

I'm going to take a look at this

[duncpro]

As far as I understand this is perfectly normal usage of refs. It should not be considered an error.

After some testing I've determined the error originates here.

react/compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoRefAccesInRender.ts

Lines 608 to 633 in cae764c

	function validateNoRefAccess(
	errors: CompilerError,
	env: Env,
	operand: Place,
	loc: SourceLocation,
	): void {
	const type = destructure(env.get(operand.identifier.id));
	if (
	type?.kind === 'Ref' ||
	type?.kind === 'RefValue' ||
	(type?.kind === 'Structure' && type.fn?.readRefEffect)
	) {
	errors.push({
	severity: ErrorSeverity.InvalidReact,
	reason:
	'Ref values (the `current` property) may not be accessed during render. (https://react.dev/reference/react/useRef)',
	loc: (type.kind === 'RefValue' && type.loc) || loc,
	description:
	operand.identifier.name !== null &&
	operand.identifier.name.kind === 'named'
	? `Cannot access ref value \`${operand.identifier.name.value}\``
	: null,
	suggestions: null,
	});
	}
	}

This comment might explain the behavior.

react/compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoRefAccesInRender.ts

Lines 27 to 46 in cae764c

	/**
	* Validates that a function does not access a ref value during render. This includes a partial check
	* for ref values which are accessed indirectly via function expressions.
	*
	* ```javascript
	* // ERROR
	* const ref = useRef();
	* ref.current;
	*
	* const ref = useRef();
	* foo(ref); // may access .current
	*
	* // ALLOWED
	* const ref = useHookThatReturnsRef();
	* ref.current;
	* ```
	*
	* In the future we may reject more cases, based on either object names (`fooRef.current` is likely a ref)
	* or based on property name alone (`foo.current` might be a ref).
	*/

If I'm interpreting this correctly, it is forbidden to pass a ref outside the component during render because that function might access ref.current.

So, we should suppress this error if the function the ref is passed to is React.createElement.

I will work on a PR for this.

[josephsavona]

Thanks for posting. Yeah, we'll have to special-case React.createElement(). To do this we'll need to add a builtin type for the createElement function so that we can easily identify that specific function, and then update ValidateNoRefAccessInRender to allow passing refs (but not ref.current) to that function.

[duncpro]

I'm thinking to filter by callee in here.

react/compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoRefAccesInRender.ts

Lines 361 to 396 in cae764c

	case 'MethodCall':
	case 'CallExpression': {
	const callee =
	instr.value.kind === 'CallExpression'
	? instr.value.callee
	: instr.value.property;
	const hookKind = getHookKindForType(fn.env, callee.identifier.type);
	let returnType: RefAccessType = {kind: 'None'};
	const fnType = env.get(callee.identifier.id);
	if (fnType?.kind === 'Structure' && fnType.fn !== null) {
	returnType = fnType.fn.returnType;
	if (fnType.fn.readRefEffect) {
	errors.push({
	severity: ErrorSeverity.InvalidReact,
	reason:
	'This function accesses a ref value (the `current` property), which may not be accessed during render. (https://react.dev/reference/react/useRef)',
	loc: callee.loc,
	description:
	callee.identifier.name !== null &&
	callee.identifier.name.kind === 'named'
	? `Function \`${callee.identifier.name.value}\` accesses a ref`
	: null,
	suggestions: null,
	});
	}
	}
	for (const operand of eachInstructionValueOperand(instr.value)) {
	if (hookKind != null) {
	validateNoDirectRefValueAccess(errors, operand, env);
	} else {
	validateNoRefAccess(errors, env, operand, operand.loc);
	}
	}
	env.set(instr.lvalue.identifier.id, returnType);
	break;
	}

Specifically guarding this block...

react/compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoRefAccesInRender.ts

Lines 388 to 392 in cae764c

	if (hookKind != null) {
	validateNoDirectRefValueAccess(errors, operand, env);
	} else {
	validateNoRefAccess(errors, env, operand, operand.loc);
	}

with the following condition...

If callee is React.createElement and isNotAccessed is true (see below), then there's no need to call either validateNo* function.

const type = destructure(env.get(operand.identifier.id));
const isNotAccessed = (type?.kind === 'Ref');

---

I'm not sure yet how we can match callee's identifier against React.createElement though. I notice that the identifier name isn't directly accessible in callee, although its extent in the source file is.

Ideally we'd also want to make sure React.createElement is actually coming from the react module, and is not some other user defined function (unlikely but still).

To do this we'll need to add a builtin type for the createElement function so that we can easily identify that specific function

@josephsavona Can you give guidance? I will investigate in the meantime.

prototype fix

// compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoRefAccesInRender.ts#L388
 if (fn.env.code !== null) {
  // @ts-ignore
  const start = callee.loc.start.index;
  // @ts-ignore
  const end = callee.loc.end.index;
  const fname = fn.env.code.substring(start, end);
  const type = destructure(env.get(operand.identifier.id));
  const isNotAccessed = (type?.kind === 'Ref');
  if (fname === 'React.createElement' && isNotAccessed) continue;
}

[stipsan]

@josephsavona the same appears to be true for React.cloneElement, do you want a separate report for it?

[alexreardon]

As @stipsan noted, this also affects cloneElement, not just createElement.

This is a runtime bug — the ref does not reach the DOM.

Reproduction (requires reactCompiler: true in next.config.ts):

import { cloneElement, useLayoutEffect, useRef, useState } from 'react';

// Child component — the compiler memoizes its JSX output.
function MyButton({ children, ref, onClick }) {
  // 'use no memo'; // uncomment to fix
  return <button ref={ref} onClick={onClick}>{children}</button>;
}

// Parent injects a ref via cloneElement (common pattern: Radix, popups, tooltips)
function Trigger({ children }) {
  const injectedRef = useRef(null);

  useLayoutEffect(() => {
    // BUG: injectedRef.current is null when MyButton is compiled
    console.log('ref:', injectedRef.current);
  });

  return cloneElement(children, { ref: injectedRef });
}

export default function App() {
  return (
    <Trigger>
      <MyButton>Click me</MyButton>
    </Trigger>
  );
}

Expected: injectedRef.current is the <button> element.
Actual: injectedRef.current is null. Adding 'use no memo' to MyButton fixes it.

This silently breaks any compound component that uses cloneElement to inject refs (CSS Anchor Positioning, focus management, ARIA attributes, etc.).