ReactRefsError Fix2026 Updated

React forwardRef Not Working— ref is null [Fixed 2026]

Also covers: attaching ref to DOM · TypeScript generics · useImperativeHandle · React 19 ref-as-prop · multi-layer forwarding

January 20265 min readReact 18/19 · TypeScript

⚡ The Problem

Error
// ref.current is always null — forwardRef not attached correctly
const inputRef = useRef<HTMLInputElement>(null)
<CustomInput ref={inputRef} />
console.log(inputRef.current)  // null

✅ Correct forwardRef pattern

components/custom-input.tsx
import { forwardRef } from "react"

// ✅ ref passed INTO the component via forwardRef, then attached to DOM element
const CustomInput = forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => {
    return <input ref={ref} {...props} />   // ← ref attached here
  }
)
CustomInput.displayName = "CustomInput"

Why forwardRef ref Is Null

React function components ignore the ref prop by default — it doesn't get forwarded to anything. forwardRef is the mechanism to receive the ref and pass it to a specific DOM element. The most common mistake is wrapping the component in forwardRef but forgetting to actually attach the received ref to the <input> or <div> inside.

1

Attach the ref to the Actual DOM Element

ref received but never attached — stays null
2 min
forwardRef — complete correct pattern
import { forwardRef, type InputHTMLAttributes } from "react"

// ❌ Wrong — ref received but never attached to any element
const BadInput = forwardRef<HTMLInputElement, InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => {
    // ref is received here but never used!
    return <input {...props} />   // ← no ref={ref}
  }
)

// ✅ Correct — ref attached to the DOM element
const GoodInput = forwardRef<HTMLInputElement, InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => {
    return <input ref={ref} {...props} />  // ← ref={ref} here
  }
)
GoodInput.displayName = "GoodInput"

// Parent usage
function Form() {
  const inputRef = useRef<HTMLInputElement>(null)

  function focusInput() {
    inputRef.current?.focus()   // works — ref is attached to the input DOM node
  }

  return (
    <div>
      <GoodInput ref={inputRef} placeholder="Type here..." />
      <button onClick={focusInput}>Focus Input</button>
    </div>
  )
}
2

TypeScript Types for forwardRef

TypeScript errors — ref type mismatch
3 min
Correct TypeScript generics for forwardRef
import { forwardRef, type ForwardedRef } from "react"

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary"
  isLoading?: boolean
}

// forwardRef<RefType, PropsType>
const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = "primary", isLoading, children, ...props }, ref) => {
    return (
      <button
        ref={ref}                    // ← ForwardedRef<HTMLButtonElement>
        className={`btn btn-${variant}`}
        disabled={isLoading}
        {...props}
      >
        {isLoading ? "Loading..." : children}
      </button>
    )
  }
)
Button.displayName = "Button"

// Export the type for consumers
export type ButtonRef = React.ElementRef<typeof Button>  // = HTMLButtonElement

// Parent with typed ref:
const btnRef = useRef<HTMLButtonElement>(null)
<Button ref={btnRef} variant="primary">Submit</Button>
3

Expose Methods with useImperativeHandle

Expose focus/reset/scroll instead of the raw DOM node
4 min

Use useImperativeHandle when you want to expose specific imperative methods to the parent, rather than the entire DOM element.

useImperativeHandle — controlled API surface
import { forwardRef, useRef, useImperativeHandle } from "react"

// Define the methods you want to expose
interface SearchInputHandle {
  focus: () => void
  clear: () => void
  getValue: () => string
}

const SearchInput = forwardRef<SearchInputHandle, { placeholder?: string }>(
  (props, ref) => {
    const inputRef = useRef<HTMLInputElement>(null)

    // Expose only selected methods — not the raw DOM element
    useImperativeHandle(ref, () => ({
      focus: () => inputRef.current?.focus(),
      clear: () => {
        if (inputRef.current) inputRef.current.value = ""
      },
      getValue: () => inputRef.current?.value ?? "",
    }), [])  // empty deps — methods don't change

    return <input ref={inputRef} {...props} className="border rounded px-3 py-2" />
  }
)

// Parent usage — ref gives access to only the exposed API
function SearchBar() {
  const searchRef = useRef<SearchInputHandle>(null)

  return (
    <div>
      <SearchInput ref={searchRef} placeholder="Search..." />
      <button onClick={() => searchRef.current?.focus()}>Focus</button>
      <button onClick={() => searchRef.current?.clear()}>Clear</button>
    </div>
  )
}
4

React 19 ref-as-prop — No forwardRef Needed

React 19+ — forwardRef is no longer required
2 min

In React 19, ref is now a regular prop. You no longer need to wrap components in forwardRef — just accept ref in your props and attach it.

React 19 — ref as a normal prop
// React 19 — no forwardRef wrapper needed
interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  label?: string
  ref?: React.Ref<HTMLInputElement>   // just add ref to props type
}

// ✅ React 19 function component — ref is a regular prop
function CustomInput({ label, ref, ...props }: InputProps) {
  return (
    <div>
      {label && <label>{label}</label>}
      <input ref={ref} {...props} />   // ← attach ref to DOM element
    </div>
  )
}

// Parent — exact same usage as before
function Form() {
  const inputRef = useRef<HTMLInputElement>(null)
  return <CustomInput ref={inputRef} label="Name" placeholder="Enter name" />
}

// Note: forwardRef still works in React 19 — no migration required
// The ref-as-prop is the new recommended pattern for new components

If your project uses React 19, prefer the ref-as-prop pattern for new components. The forwardRef API is still supported but marked as a legacy pattern in the React 19 docs.

5

forwardRef Through Multiple Component Layers

ref passing through composed/wrapped components
3 min
Multi-layer ref forwarding
import { forwardRef } from "react"

// Level 1 — base input
const BaseInput = forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => <input ref={ref} {...props} />
)

// Level 2 — styled wrapper — must also forward the ref
const StyledInput = forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
  ({ className, ...props }, ref) => (
    <BaseInput
      ref={ref}   // ← forward to the next layer
      className={`border rounded px-3 py-2 ${className ?? ""}`}
      {...props}
    />
  )
)

// Level 3 — form field with label — must also forward
const FormField = forwardRef<HTMLInputElement, { label: string } & React.InputHTMLAttributes<HTMLInputElement>>(
  ({ label, ...props }, ref) => (
    <div className="flex flex-col gap-1">
      <label className="text-sm font-medium">{label}</label>
      <StyledInput ref={ref} {...props} />   // ← forward down the chain
    </div>
  )
)

// Parent — ref reaches the actual <input> DOM element through all 3 layers
function Form() {
  const nameRef = useRef<HTMLInputElement>(null)
  return <FormField ref={nameRef} label="Full name" placeholder="John Smith" />
}

Every component in the chain must use forwardRef and pass the ref down. If any layer drops the ref (doesn't pass ref={ref} to the next component), ref.current will be null at the parent level.

Prevention

Frequently Asked Questions

Why is my forwardRef ref always null?+
The most common cause is forgetting to pass the ref to the underlying DOM element inside the forwardRef component. The ref callback and forwardRef wrapper only forward the ref — you must manually attach it to the actual element with ref={ref} on the JSX element inside the component body.
What is forwardRef used for in React?+
forwardRef lets a parent component access a child component's DOM node or instance methods. Without forwardRef, passing a ref to a custom component has no effect — the ref stays null. Common use cases: focusing an input, measuring element size, triggering animations, or calling methods on a child (with useImperativeHandle).
Do I need forwardRef in React 19?+
No. React 19 allows passing ref as a regular prop — no forwardRef wrapper needed. If you are on React 19, just accept ref in your component props like any other prop and attach it to the DOM element. The forwardRef API still works for backwards compatibility.
How do I type forwardRef with TypeScript?+
Use forwardRef<RefType, PropsType>. The first generic is the type of the ref (usually HTMLInputElement, HTMLDivElement, etc). The second is your component's props type. Inside the component, type the ref parameter as React.ForwardedRef<RefType>.
What is useImperativeHandle and when should I use it?+
useImperativeHandle customises what the parent receives when it uses a ref on your component. Instead of exposing the full DOM node, you expose only specific methods (like focus(), reset(), scrollTo()). Use it when you want to give parents controlled access to your component's internals without exposing the entire DOM element.
Can I use forwardRef with a class component?+
Class components automatically support refs without forwardRef — you can pass a ref to any class component and React attaches it to the class instance. forwardRef is only needed for function components, which normally ignore the ref prop.

Need Expert Help?

We Build Reusable React Component Libraries

Softplix engineers build accessible, TypeScript-first React component systems with forwardRef, compound patterns, and design tokens. Let us help.

Talk to an Engineer