Maaz Zindani

Loading the index…

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

Importing useActionState from react fails in a Next.js project

Errorimport { useActionState } from 'react' fails after following the Next.js forms tutorial

Short answer

useActionState exists only in React 19 and later. If the import fails, the project still resolves an older react package, or its TypeScript types are old. Run npm ls react @types/react, upgrade next, react, react-dom and the two type packages together, and check that a peer dependency conflict did not block the install.

  • Applies to Next.js 15, Next.js 16, React 19, TypeScript 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the react and type packages that are really installed. Every react line should start with 19, and so should @types/react.

    npm ls react react-dom @types/react @types/react-dom
  2. 2Match what you see, then jump to its fix

    1. 1npm ls shows react 18.xThe installed react package is older than 19Fix
    2. 2Editor or tsc reports the hook missing, while the app runs@types/react is still on version 18Fix
    3. 3Upgrading next alone did not change the react versionA Pages Router app takes its React version from package.jsonFix
    4. 4npm printed a peer dependency error, and package.json still shows the old reactThe upgrade install was rejected by another package's peer dependencyFix

What does the error look like?

  • import { useActionState } from 'react' fails after following the Next.js forms tutorial
  • The editor flags useActionState as not exported by react
  • The tutorial used useFormState from react-dom, your code uses useActionState

Cause 1 of 4

The installed react package is older than 19

1Check

The React 19 release notes say React.useActionState replaced ReactDOM.useFormState from the canary builds. A project on react 18 has no such export.

npm ls react

2Fix

Move next, react and react-dom to their latest versions together. Next.js 15 raised the minimum to React 19.

npm install next@latest react@latest react-dom@latest

3Verify

The listing shows 19.x and the import resolves.

npm ls react react-dom

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

@types/react is still on version 18

1Check

The runtime can be React 19 while the type packages are old. The Next.js upgrade guide says to upgrade @types/react and @types/react-dom for TypeScript projects.

npm ls @types/react @types/react-dom

2Fix

Install the 19 type packages. The React upgrade guide gives this exact form.

npm install --save-exact @types/react@^19.0.0 @types/react-dom@^19.0.0

3Verify

Restart the TypeScript server in your editor and run the type check.

npx tsc --noEmit

Confirmed by react.dev

Did this fix it?

Cause 3 of 4

A Pages Router app takes its React version from package.json

1Check

The installation guide says the App Router ships built-in React canary builds, while the Pages Router uses the version written in package.json. In a Pages Router app, nothing upgrades react unless you do.

grep -E '"(next|react|react-dom)"' package.json

2Fix

Set react and react-dom to 19 yourself in package.json by installing them explicitly.

npm install react@latest react-dom@latest

3Verify

Run the dev server and open the page that uses the hook.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

The upgrade install was rejected by another package's peer dependency

1Check

The upgrade guide lists this as a known snag. Some other package may still declare a peer range that excludes React 19.

npm ls react 2>&1 | grep -i -E 'invalid|ERESOLVE'

2Fix

First update the package that rejects React 19. If you accept the risk, the upgrade guide names --force and --legacy-peer-deps as the ways to ignore the warning.

npm install react@latest react-dom@latest --legacy-peer-deps

3Verify

Check that the listing now shows React 19 and run the project's own checks.

npm ls react
npm run build

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Upgrade next, react, react-dom and both @types packages in one command so they never drift apart.
  • Commit the lockfile and install with npm ci in CI, so every machine gets the same React.
  • When a tutorial pins a canary or rc build, read the Next.js version note on the page before copying its imports.

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 a useRef ref passed to an input element

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

The ref prop on a DOM element expects an object whose current value is the element or null.

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.