mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
1dc5c066cb
We initially wrote the [React page](https://nextjs.org/docs/getting-started/react-essentials) to introduce Server Components in the App Router, but over time, some implementation details have changed, and the information has become stale. The React team is working on adding new docs, so I'd like to change the narrative on the Next.js docs from "client vs. server components" to "writing code for the server and for the client" - and link back to the React documentation when it becomes available. As React developers, we're very familiar with writing code for the client, it's nice and simple. But doing so comes at the expense of not being familiar with the server. The aim of these docs is to help developers become proficient in both the client and server environments. I'd like to take it back to the foundations, and not use abstractions like SSG and CSR, MPAs or SPAs, as those terms come with their own set of assumptions that make it harder to understand how RSC works. Instead, we'll focus on the request lifecycle, show how application code flows from the server to the client, and discuss the trade-offs of doing operations in each environment. - [x] Page: Rendering Fundamentals - [x] Environments: Client and Server - [x] Request-response lifecycle - [x] Network Boundary - [x] Page: Server Components - [x] Benefits and use cases of server rendering - [x] How to use Server Components in Next.js - [x] How Server Components are rendered - [x] Static Rendering - [x] Dynamic Rendering - [x] Streaming - [x] Page: Client Components - [x] Benefits and use cases of client rendering - [x] How to use Client Components in Next.js - [x] How Client Components are rendered - [x] Initial vs. Subsquent navigation - [x] Page: Composition Patterns - [x] When to use client and server components - [x] Server Component Patterns - [x] Client Component Patterns - [x] Interleaving Client and Server Components - [ ] ~Diagrams~ will follow up with new PR. - [x] Set up redirects: https://github.com/vercel/front/pull/24917 --------- Co-authored-by: Térence Hollander <[email protected]> Co-authored-by: shawnthwei <[email protected]> Co-authored-by: Michael Novotny <[email protected]>
95 lines
3.3 KiB
Plaintext
95 lines
3.3 KiB
Plaintext
---
|
|
title: usePathname
|
|
description: API Reference for the usePathname hook.
|
|
---
|
|
|
|
`usePathname` is a **Client Component** hook that lets you read the current URL's **pathname**.
|
|
|
|
```tsx filename="app/example-client-component.tsx" switcher
|
|
'use client'
|
|
|
|
import { usePathname } from 'next/navigation'
|
|
|
|
export default function ExampleClientComponent() {
|
|
const pathname = usePathname()
|
|
return <p>Current pathname: {pathname}</p>
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/example-client-component.js" switcher
|
|
'use client'
|
|
|
|
import { usePathname } from 'next/navigation'
|
|
|
|
export default function ExampleClientComponent() {
|
|
const pathname = usePathname()
|
|
return <p>Current pathname: {pathname}</p>
|
|
}
|
|
```
|
|
|
|
`usePathname` intentionally requires using a [Client Component](/docs/app/building-your-application/rendering/client-components). It's important to note Client Components are not a de-optimization. They are an integral part of the [Server Components](/docs/app/building-your-application/rendering/server-components) 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**:
|
|
>
|
|
> - Reading the current URL from a [Server Component](/docs/app/building-your-application/rendering/server-components) 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.
|
|
|
|
## Parameters
|
|
|
|
```tsx
|
|
const pathname = usePathname()
|
|
```
|
|
|
|
`usePathname` does not take any parameters.
|
|
|
|
## Returns
|
|
|
|
`usePathname` returns a string of the current URL's pathname. For example:
|
|
|
|
| URL | Returned value |
|
|
| ------------------- | --------------------- |
|
|
| `/` | `'/'` |
|
|
| `/dashboard` | `'/dashboard'` |
|
|
| `/dashboard?v=2` | `'/dashboard'` |
|
|
| `/blog/hello-world` | `'/blog/hello-world'` |
|
|
|
|
## Examples
|
|
|
|
### Do something in response to a route change
|
|
|
|
```tsx filename="app/example-client-component.tsx" switcher
|
|
'use client'
|
|
|
|
import { usePathname, useSearchParams } from 'next/navigation'
|
|
|
|
function ExampleClientComponent() {
|
|
const pathname = usePathname()
|
|
const searchParams = useSearchParams()
|
|
useEffect(() => {
|
|
// Do something here...
|
|
}, [pathname, searchParams])
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/example-client-component.js" switcher
|
|
'use client'
|
|
|
|
import { usePathname, useSearchParams } from 'next/navigation'
|
|
|
|
function ExampleClientComponent() {
|
|
const pathname = usePathname()
|
|
const searchParams = useSearchParams()
|
|
useEffect(() => {
|
|
// Do something here...
|
|
}, [pathname, searchParams])
|
|
}
|
|
```
|
|
|
|
| Version | Changes |
|
|
| --------- | ------------------------- |
|
|
| `v13.0.0` | `usePathname` introduced. |
|