How to fix Warning: Non-string ref will not work with function components in React

ReactBEGINNERMEDIUMUpdated Dec 11, 2025· 116 views

React throws this warning when you attach a ref object or callback to a function component because the component does not expose an instance for React to assign the ref. The runtime is protecting you from leaking a DOM node reference into a place that cannot safely receive it.

Quick fix

Fixes Warning: Non-string ref will not work with function components

function TextInput(props: {}) {
  const inputRef = useRef<HTMLInputElement>(null);

  useImperativeHandle(props.forwardedRef, () => ({
    focus: () => inputRef.current?.focus(),
  }));

  return <input ref={inputRef} />;
}

const ForwardedTextInput = forwardRef((props, ref) => (
  <TextInput {...props} forwardedRef={ref} />
));

Keep the ref on the DOM node rather than the function component
Wrap the component with React.forwardRef
Check third-party components for forwardRef support
Avoid string refs and prefer hooks-based refs

react — error

$function TextInput(props: {}) {
  const inputRef = useRef<HTMLInputElement>(null);
  useImperativeHandle(props.forwardedRef, () => ({
    focus: () => inputRef.current?.focus(),
  }));
  return <input ref={inputRef} />;
}
const ForwardedTextInput = forwardRef((props, ref) => (
  <TextInput {...props} forwardedRef={ref} />
));
Warning: Non-string ref will not work with function components

What this error means

React only assigns non-string refs (object refs or callbacks) to DOM elements and class components because they expose an instance for the ref to point at. Function components do not have instances, so when a parent tries to set a ref on one of them, React warns instead of failing silently. The proper fix is to either move the ref down to the DOM node rendered by the function component or wrap the component with `React.forwardRef` so it can explicitly hand the ref to a DOM node or an imperative handle. If you still need to expose some imperative API, use `forwardRef` together with `useImperativeHandle` so you control exactly what the parent sees. Avoid relying on string refs because they are legacy and were never supported on function components in the first place.

Typical symptoms

Console repeatedly prints "Warning: Non-string ref will not work with function components" during renders that touch the affected component tree
The ref value you passed from the parent remains null or undefined even after the child renders
Attempting to call methods or read DOM properties through the ref is no longer possible
The warning spikes whenever the parent tries to pass refs to inline function components inside loops or JSX expressions

Common causes

You provided `ref={someRef}` or a callback ref to a function component that does not forward refs
A child function component renders a DOM element that needs to be referenced, but the parent attaches the ref directly to the component instead of the DOM node
Third-party function components do not expose a forwardRef API, yet the consumer still tries to attach a ref
Legacy string refs were replaced with objects or callbacks, and the new ref is still being passed to a function component that lacks `forwardRef` support

How to fix "Warning: Non-string ref will not work with function components"

1Keep the ref on the DOM node rather than the function component

If the child function component simply renders a DOM element, move the ref to that element and expose any public APIs through props instead. Example:

tsx

function TextInput(props: {}) {
  const inputRef = useRef<HTMLInputElement>(null);

  useImperativeHandle(props.forwardedRef, () => ({
    focus: () => inputRef.current?.focus(),
  }));

  return <input ref={inputRef} />;
}

const ForwardedTextInput = forwardRef((props, ref) => (
  <TextInput {...props} forwardedRef={ref} />
));

This keeps the actual DOM reference inside the component while still letting the parent interact with the exposed methods.

2Wrap the component with React.forwardRef

React cannot make refs point at function components unless you opt into forwarding. Wrap the component declaration with forwardRef and pass the ref down to a DOM node or into useImperativeHandle:

tsx

const Button = forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => (
  <button ref={ref} {...props} />
));

Now parents can safely attach refs to <Button /> without hitting the warning.

3Check third-party components for forwardRef support

Not every function component automatically accepts refs. Inspect the documentation or source code of libraries (e.g., React Router, Radix UI, etc.) to see if they expose a forwardRef API or supply a helper prop such as componentRef.

If the component cannot forward refs, wrap it with another forwardRef container that renders a DOM node you control and forwards the ref there.

4Avoid string refs and prefer hooks-based refs

String refs are legacy and have never worked on function components. Stick with const ref = useRef<T>(), createRef(), or callback refs and keep them attached to DOM nodes. When you need to forward them through multiple layers, explicitly forward the ref at each layer.

Advanced notes

String refs are legacy, difficult to type, and slated for removal (see React docs). Always pass objects or callbacks to ref, and keep forwardRef/ useImperativeHandle handy when you need to expose imperative handles from function components.

Function components cannot receive string refs because React never created an instance for them. Even when you bind callbacks, React still needs to resolve the ref to an actual DOM node or class instance, so you still must forward it explicitly.

Frequently asked questions

What does "Warning: Non-string ref will not work with function components" mean?: React only assigns non-string refs (object refs or callbacks) to DOM elements and class components because they expose an instance for the ref to point at. Function components do not have instances, so when a parent tries to set a ref on one of them, React warns instead of failing silently. forwardRef so it can explicitly hand the ref to a DOM node or an imperative handle.
How do I fix "Warning: Non-string ref will not work with function components"?: React throws this warning when you attach a ref object or callback to a function component because the component does not expose an instance for React to assign the ref. The runtime is protecting you from leaking a DOM node reference into a place that cannot safely receive it.
What causes "Warning: Non-string ref will not work with function components"?: You provided ref={someRef} or a callback ref to a function component that does not forward refs A child function component renders a DOM element that needs to be referenced, but the parent attaches the ref directly to the component instead of the DOM node Third-party function components do not expose a forwardRef API, yet the consumer still tries to attach a ref
Is the "Warning: Non-string ref will not work with function components" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚React Official Documentation
📖
React docs: Refs and the DOM(Official Docs)
📖
React docs: Forwarding refs(Official Docs)