Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

TypeScript rejects a useRef ref passed to an input element

ErrorType 'MutableRefObject<HTMLInputElement | undefined>' is not assignable to type 'LegacyRef<HTMLInputElement> | undefined'

Short answer

The ref prop on a DOM element expects an object whose current value is the element or null. useRef with no argument, or typed with undefined, gives an object that does not fit. Pass null as the starting value. On React 19 types, useRef also requires an argument and MutableRefObject is deprecated.

  • Applies to React 19, @types/react 19, TypeScript 5, Next.js 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the useRef call that feeds the failing ref prop and look at its initial value.

    grep -rnE "useRef(<[^>]*>)?\(" app components src 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The error mentions HTMLInputElement | undefined, and the call is useRef<HTMLInputElement>() or useRef<HTMLInputElement | undefined>(undefined)The ref was created without null as the initial valueFix
    2. 2TypeScript reports a missing argument on a bare useRef() call after upgrading @types/reactReact 19 types: useRef now requires an argumentFix

What does the error look like?

  • Type 'MutableRefObject<HTMLInputElement | undefined>' is not assignable to type 'LegacyRef<HTMLInputElement> | undefined'

Cause 1 of 2

The ref was created without null as the initial value

1Check

React's docs initialise a DOM ref with null. React sets current to the DOM node once it exists and back to null when the node leaves the screen. A type that includes undefined does not match that.

grep -rn "useRef<HTMLInputElement" app components

2Fix

Type the ref as the element and start it at null.

const inputRef = useRef<HTMLInputElement>(null)

return <input ref={inputRef} />

3Verify

Run the type check; the error on the ref prop should be gone.

npx tsc --noEmit

Confirmed by react.dev

Did this fix it?

Cause 2 of 2

React 19 types: useRef now requires an argument

1Check

The React 19 upgrade guide says the types changed so that useRef requires an argument, and that MutableRefObject is deprecated in favour of one RefObject type.

npm ls @types/react react

2Fix

Add the initial value. For DOM refs use null. To migrate the whole project, the guide points to the types-react-codemod preset.

// single call
const inputRef = useRef<HTMLInputElement>(null)

// whole project
npx types-react-codemod@latest preset-19 ./src

3Verify

Type-check the project again.

npx tsc --noEmit

Confirmed by react.dev

Did this fix it?

How do I stop it coming back?

  • Write every DOM ref as useRef<ElementType>(null) and check current for null before using it.
  • Keep react and @types/react on the same major version.
  • Use useRef(undefined) only for non-DOM values such as timer ids, never for a ref prop.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.