usePathname

usePathname is a Client Component hook that lets you read the current URL's pathname.

'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. It's important to note Client Components are not a de-optimization. They are an integral part of the 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.

Parameters

const pathname = usePathname()

usePathname does not take any parameters.

Returns

usePathname returns a string of the current URL's pathname. For example:

Behavior

Cache Components

When cacheComponents is enabled, usePathname may require a Suspense boundary. This depends on whether the pathname can be resolved during prerendering.

• Static routes and routes with generateStaticParams: every route segment, including dynamic params, is known at build time. The pathname can be resolved during prerendering, so usePathname resolves on the server and no Suspense boundary is required.
• Routes with dynamic params not covered by generateStaticParams: the param is a fallback param that is not known until request time. The pathname cannot be resolved during prerendering, so usePathname suspends. Wrap the component (or a parent) in a Suspense boundary so its fallback can be rendered during prerendering; otherwise, the build fails.

This applies even when the component that calls usePathname is itself static. For example, a sidebar with active links rendered in a layout suspends on any page below it that has an unknown dynamic param. To keep the rest of the layout prerendered, wrap the component that calls usePathname (or a parent) in a Suspense boundary with a fallback.

See Next.js encountered URL data in a Client Component outside of Suspense for full fix options and trade-offs.

Examples

Do something in response to a route change

'use client'
 
import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'
 
function ExampleClientComponent() {
  const pathname = usePathname()
  const searchParams = useSearchParams()
  useEffect(() => {
    // Do something here...
  }, [pathname, searchParams])
}

Avoid hydration mismatch with rewrites

When a page is prerendered, the HTML is generated for the source pathname. If the page is then reached through a rewrite using next.config or Proxy, the browser URL may differ, and usePathname() will read the rewritten pathname on the client.

To avoid hydration mismatches, design the UI so that only a small, isolated part depends on the client pathname. Render a stable fallback on the server and update that part after mount. The deferred read shows a brief moment of the fallback before the real pathname appears; see Preventing flash before hydration for techniques that eliminate the visible flicker.

'use client'
 
import { useEffect, useState } from 'react'
import { usePathname } from 'next/navigation'
 
export default function PathnameBadge() {
  const pathname = usePathname()
  const [clientPathname, setClientPathname] = useState('')
 
  useEffect(() => {
    setClientPathname(pathname)
  }, [pathname])
 
  return (
    <p>
      Current pathname: <span>{clientPathname}</span>
    </p>
  )
}