ref.current may be null or undefined with useRef in React and TypeScript
TypeScript reports that ref.current may be nullShort answer
A DOM ref has no value until React attaches the element, so its type includes null. Declare it as useRef<HTMLInputElement>(null) and check current before using it. With React 19 types useRef needs an initial argument, and ref callbacks must not return a value.
Fix it fast
1Find out which cause you have
Hover the ref in your editor. The type of current tells you which cause applies.
npx tsc --noEmit2Match what you see, then jump to its fix
What does the error look like?
TypeScript reports that ref.current may be nullExpected 1 argument but saw none (useRef called with no arguments)A type error on a ref callback after moving to React 19 types
Cause 1 of 3
The element is not attached yet
1Check
React sets current once the DOM node is on screen and sets it back to null when the node is removed. TypeScript models this as a nullable type.
grep -rn "useRef" src2Fix
Type the ref with the element type and null, then check current before using it.
const inputRef = useRef<HTMLInputElement>(null);
function focusInput() {
inputRef.current?.focus();
}
return <input ref={inputRef} />;3Verify
Run the type checker.
npx tsc --noEmitConfirmed by react.dev
Cause 2 of 3
useRef() called without an argument (React 19 types)
1Check
In React 19 types useRef requires an argument.
grep -rn "useRef()" src2Fix
Pass an initial value: null for a DOM ref, or undefined if there is no initial value.
const timer = useRef<number | undefined>(undefined);3Verify
Run the type checker.
npx tsc --noEmitConfirmed by react.dev
Cause 3 of 3
A ref callback returns a value
1Check
Ref callbacks can now return cleanup functions, so TypeScript rejects any other return value.
grep -rn "ref={" src | grep "=>"2Fix
Use a block body so the callback returns nothing.
// before
<div ref={current => (instance = current)} />
// after
<div ref={current => { instance = current }} />3Verify
Run the type checker.
npx tsc --noEmitConfirmed by react.dev
How do I stop it coming back?
- Use optional chaining or an if check on every DOM ref.
- Run the types-react-codemod preset when upgrading to React 19 types.
- Keep @types/react and @types/react-dom on the same major version as React.
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
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 fixWeb apps
ESLint says it cannot resolve a path to a module that does exist
Unable to resolve path to module 'react'. import/no-unresolved
import/no-unresolved fails when eslint-plugin-import cannot find the file or package on disk with its resolver.
4 causes, each with a fixWeb apps
ESLint reports no-unused-vars for React components and imports that are used
no-unused-vars reported for a component that is rendered as a JSX tag
ESLint's core no-unused-vars does not see variables used only as JSX tags, so a component imported and rendered as <Hello /> looks unused.
3 causes, each with a fixWeb apps
TypeScript rejects MUI Data Grid columns that set a type
A TypeScript error inside a column's renderCell callback
A columns array declared without a type is inferred with type as a plain string, which the Data Grid's column type union does not accept.
2 causes, each with a fixWeb apps
The renderInput prop stopped working on the MUI X DatePicker
The custom TextField (variant, size, helperText) is ignored
renderInput was removed from the MUI X date pickers in version 6.
3 causes, each with a fix