Skip to content

Commit

Permalink
docs: clarify usePathname usage as client hook. (#51146)
Browse files Browse the repository at this point in the history
Using client components for `usePathname` is not a de-optimization. This
update tries to make this more clear by sharing more information about
the design and tradeoffs of this approach.

---------

Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
  • Loading branch information
leerob and delbaoliveira committed Jun 12, 2023
1 parent f9813ad commit e5a45c8
Showing 1 changed file with 5 additions and 1 deletion.
6 changes: 5 additions & 1 deletion docs/02-app/02-api-reference/04-functions/use-pathname.mdx
Expand Up @@ -27,9 +27,13 @@ export default function ExampleClientComponent() {
}
```

`usePathname` intentionally requires using a [Client Component](/docs/getting-started/react-essentials). It's important to note Client Components are not a de-optimization. They are an integral part of the [Server Components](/docs/getting-started/react-essentials) architecture.

For example, a Client Component with `usePathname` will be rendered into HTML on the initial page load. When navigating to a new route, this component does not need to be re-fetched. Instead, the component is downloaded once (in the client JavaScript bundle), and re-renders based on the current state.

> **Good to know:**
>
> - `usePathname` is a [Client Component](/docs/getting-started/react-essentials) hook and is **not supported** in [Server Components](/docs/getting-started/react-essentials).
> - Reading the current URL from a [Server Component](/docs/getting-started/react-essentials) is not supported. This design is intentional to support layout state being preserved across page navigations.
> - Compatibility mode:
> - `usePathname` can return `null` when a [fallback route](/docs/pages/api-reference/functions/get-static-paths#fallback-true) is being rendered or when a `pages` directory page has been [automatically statically optimized](/docs/pages/building-your-application/rendering/automatic-static-optimization) by Next.js and the router is not ready.
> - Next.js will automatically update your types if it detects both an `app` and `pages` directory in your project.
Expand Down

0 comments on commit e5a45c8

Please sign in to comment.