Unverified Commit e5a45c8a authored by Lee Robinson's avatar Lee Robinson Committed by GitHub

docs: clarify `usePathname` usage as client hook. (#51146)

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: 's avatarDelba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
parent f9813ad6
...@@ -27,9 +27,13 @@ export default function ExampleClientComponent() { ...@@ -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:** > **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: > - 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. > - `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. > - Next.js will automatically update your types if it detects both an `app` and `pages` directory in your project.
......
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