TypeScript rejects a useRef ref passed to an input element
Type '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.
Fix it fast
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/null2Match what you see, then jump to its fix
- 1
The 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
TypeScript reports a missing argument on a bare useRef() call after upgrading @types/reactReact 19 types: useRef now requires an argumentFix
- 1
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 components2Fix
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 --noEmitConfirmed by react.dev
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 react2Fix
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 ./src3Verify
Type-check the project again.
npx tsc --noEmitConfirmed by react.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
Type error after upgrading: params does not satisfy the PageProps constraint
Type '{ params: { id: string; }; }' does not satisfy the constraint 'PageProps'
Since Next.js 15, params and searchParams are Promises, not plain objects.
4 causes, each with a fixWeb apps
Importing useActionState from react fails in a Next.js project
The editor flags useActionState as not exported by react
useActionState exists only in React 19 and later.
4 causes, each with a fixWeb apps
TypeScript says a JSX element type has no construct or call signatures
'Promise<Element>' is not a valid JSX element
TypeScript accepts a capitalised JSX tag only when the value is a function component or a class component.
3 causes, each with a fixWeb apps
TypeScript refuses JSX because the jsx option is not set
TS17004: Cannot use JSX unless the '--jsx' flag is provided.
TypeScript compiles JSX only when you name the file with a .tsx extension and enable the jsx compiler option.
2 causes, each with a fixWeb apps
TypeScript rejects a component that returns an array or other non-Element
Its return type 'Element[]' is not a valid JSX element.
TypeScript before 5.1 required every component to return JSX.Element or null, so arrays, strings and Promises were rejected even though React renders them.
2 causes, each with a fix