Unverified Commit 3f51f6e6 authored by Aryan Sachin's avatar Aryan Sachin Committed by GitHub

docs: document useRouter push/replace void return and useTransition migration (#100420)

### What?

Documents that `router.push()` and `router.replace()` in the App Router
(`next/navigation`) return `void` instead of a `Promise`, and provides
migration guidance and code examples showing how to use React's
`useTransition` to track pending navigation state.

### Why?

In the Pages Router (`next/router`), `router.push()` and
`router.replace()` returned a `Promise<boolean>` that developers could
`await` to execute code after a route change. In the App Router,
navigations are non-blocking transitions integrated with React's
transition system and return `void`. This breaking difference was not
documented in the `useRouter` API reference or the App Router migration
guide, leading to confusion when migrating existing codebases.

### How?

- Updated `docs/01-app/03-api-reference/04-functions/use-router.mdx`:
- Added callout notes to `router.push()` and `router.replace()`
explaining the `void` return type and referencing `useTransition`.
  - Added a migration bullet point under "Migrating from `next/router`".
- Added an example demonstrating how to track pending navigation state
with React's `useTransition` (`startTransition` / `isPending`).
- Updated `docs/01-app/02-guides/migrating/app-router-migration.mdx`:
- Added migration notes and dual-language (TSX/JSX) switcher examples
under Step 5 ("Migrating Routing Hooks") explaining how to migrate from
`await router.push(...)` using `useTransition`.

Closes #61737
parent 2aa96d02
......@@ -511,6 +511,7 @@ In addition, the new `useRouter` hook has the following changes:
- `asPath` has been removed because the concept of `as` has been removed from the new router.
- `isReady` has been removed because it is no longer necessary. During [prerendering](/docs/app/glossary#prerendering), any component that uses the [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params) hook will skip the prerendering step and instead be rendered on the client at runtime.
- `route` has been removed. `usePathname` or `useSelectedLayoutSegments()` provide an alternative.
- `router.push()` and `router.replace()` no longer return a Promise. They queue the route change as a React Transition and return right away. To show a pending state, call them inside the `startTransition` returned by [`useTransition`](https://react.dev/reference/react/useTransition) and read `isPending`. See [Filter with pending feedback](/docs/app/guides/interactive-apps#step-3-filter-with-pending-feedback) for an example.
[View the `useRouter()` API reference](/docs/app/api-reference/functions/use-router).
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment