Maaz Zindani

Loading the index…

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

ref.current may be null or undefined with useRef in React and TypeScript

ErrorTypeScript reports that ref.current may be null

Short 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.

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

Fix it fast

  1. 1Find out which cause you have

    Hover the ref in your editor. The type of current tells you which cause applies.

    npx tsc --noEmit
  2. 2Match what you see, then jump to its fix

    1. 1A null error when calling a method on ref.currentThe element is not attached yetFix
    2. 2Expected 1 argument but saw noneuseRef() called without an argument (React 19 types)Fix
    3. 3A type error on a ref callback written with an arrow expressionA ref callback returns a valueFix

What does the error look like?

  • TypeScript reports that ref.current may be null
  • Expected 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" src

2Fix

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 --noEmit

Confirmed by react.dev

Did this fix it?

Cause 2 of 3

useRef() called without an argument (React 19 types)

1Check

In React 19 types useRef requires an argument.

grep -rn "useRef()" src

2Fix

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 --noEmit

Confirmed by react.dev

Did this fix it?

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 --noEmit

Confirmed by react.dev

Did this fix it?

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:

Related fixes

Web 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 fix

Next step

Want this handled for good?

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