next/navigation

The next/navigation module provides hooks and utilities for App Router navigation, including pathname/query access, programmatic navigation, and server-side redirects.

Import

import {
  useRouter,
  usePathname,
  useSearchParams,
  useParams,
  useSelectedLayoutSegment,
  useSelectedLayoutSegments,
  redirect,
  permanentRedirect,
  notFound,
  forbidden,
  unauthorized,
  RedirectType,
} from 'next/navigation'

Client Hooks

useRouter

Returns a router instance for programmatic navigation.

'use client'
import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()
  
  return (
    <button onClick={() => router.push('/dashboard')}>
      Go to Dashboard
    </button>
  )
}

Router Methods

push

(href: string, options?: { scroll?: boolean }) => void

Navigate to a new URL (pushes history entry).

router.push('/about')
router.push('/blog?filter=tech', { scroll: false })

replace

(href: string, options?: { scroll?: boolean }) => void

Navigate to a new URL (replaces history entry).

router.replace('/login')

back

() => void

Navigate to the previous page.

<button onClick={() => router.back()}>Back</button>

forward

() => void

Navigate to the next page (if available).

<button onClick={() => router.forward()}>Forward</button>

refresh

() => void

Re-fetch the current page’s RSC stream (soft refresh).

// After a mutation
router.refresh()

prefetch

(href: string) => void

Manually prefetch a route.

<div onMouseEnter={() => router.prefetch('/dashboard')}>
  Hover to prefetch
</div>

usePathname

Returns the current pathname (without basePath).

'use client'
import { usePathname } from 'next/navigation'

export default function Nav() {
  const pathname = usePathname()
  
  return (
    <nav>
      <a href="/" className={pathname === '/' ? 'active' : ''}>
        Home
      </a>
      <a href="/about" className={pathname === '/about' ? 'active' : ''}>
        About
      </a>
    </nav>
  )
}

pathname

string

Current pathname, e.g., /blog/post-1

Excludes basePath (if configured)
Excludes query string and hash
Updates on navigation

useSearchParams

Returns a URLSearchParams instance for reading query parameters.

'use client'
import { useSearchParams } from 'next/navigation'

export default function SearchResults() {
  const searchParams = useSearchParams()
  const query = searchParams.get('q')
  const page = searchParams.get('page') || '1'
  
  return <div>Search results for: {query} (page {page})</div>
}

searchParams

ReadonlyURLSearchParams

URLSearchParams instance with methods:

get(key: string): string | null
getAll(key: string): string[]
has(key: string): boolean
entries(): Iterator<[string, string]>

useParams

Returns dynamic route parameters.

'use client'
// File: app/blog/[slug]/page.tsx
import { useParams } from 'next/navigation'

export default function BlogPost() {
  const params = useParams<{ slug: string }>()
  
  return <h1>Post: {params.slug}</h1>
}

params

Record<string, string | string[]>

Dynamic route parameters, e.g., { slug: 'hello-world' }

Single segment: { slug: 'post-1' }
Catch-all: { slug: ['2024', '01', 'post'] }

useSelectedLayoutSegment

Returns the active child segment one level below the current layout.

'use client'
// File: app/blog/layout.tsx
import { useSelectedLayoutSegment } from 'next/navigation'

export default function BlogLayout({ children }) {
  const segment = useSelectedLayoutSegment()
  
  return (
    <div>
      <div>Active segment: {segment}</div>
      {children}
    </div>
  )
}

segment

string | null

/blog → null (no child)
/blog/post-1 → 'post-1'
/blog/category/tech → 'category'

useSelectedLayoutSegments

Returns all active segments below the current layout.

'use client'
import { useSelectedLayoutSegments } from 'next/navigation'

export default function Layout({ children }) {
  const segments = useSelectedLayoutSegments()
  
  return (
    <div>
      <div>Path: /{segments.join('/')}</div>
      {children}
    </div>
  )
}

segments

string[]

/blog → []
/blog/post-1 → ['post-1']
/blog/category/tech → ['category', 'tech']

useServerInsertedHTML

Inject HTML during SSR from client components (CSS-in-JS libraries).

'use client'
import { useServerInsertedHTML } from 'next/navigation'
import { StyleSheetManager } from 'styled-components'

export default function StyledComponentsRegistry({ children }) {
  const [sheet] = useState(() => new ServerStyleSheet())
  
  useServerInsertedHTML(() => {
    const styles = sheet.getStyleElement()
    sheet.instance.clearTag()
    return <>{styles}</>
  })
  
  return (
    <StyleSheetManager sheet={sheet.instance}>
      {children}
    </StyleSheetManager>
  )
}

Server Functions

redirect

Throw a redirect response (caught by the framework).

import { redirect } from 'next/navigation'

export default async function Page() {
  const session = await getSession()
  
  if (!session) {
    redirect('/login')
  }
  
  return <Dashboard />
}

url

string

required

Destination URL (relative or absolute).

type

'push' | 'replace' | RedirectType

default:"'replace'"

Navigation type:

'replace' — 307 redirect (default)
'push' — 307 redirect with history push
RedirectType.push / RedirectType.replace

permanentRedirect

Throw a permanent redirect (308).

import { permanentRedirect } from 'next/navigation'

export default async function Page() {
  permanentRedirect('https://example.com')
}

url

string

required

Destination URL.

notFound

Throw a 404 Not Found error.

import { notFound } from 'next/navigation'

export default async function Page({ params }) {
  const post = await getPost(params.id)
  
  if (!post) {
    notFound()
  }
  
  return <Post data={post} />
}

Renders the nearest not-found.tsx file.

forbidden

Throw a 403 Forbidden error (Next.js 16+).

import { forbidden } from 'next/navigation'

export default async function AdminPage() {
  const user = await getUser()
  
  if (!user.isAdmin) {
    forbidden()
  }
  
  return <AdminPanel />
}

Renders the nearest forbidden.tsx file (or error.tsx as fallback).

unauthorized

Throw a 401 Unauthorized error (Next.js 16+).

import { unauthorized } from 'next/navigation'

export default async function ProfilePage() {
  const session = await getSession()
  
  if (!session) {
    unauthorized()
  }
  
  return <Profile user={session.user} />
}

Renders the nearest unauthorized.tsx file (or error.tsx as fallback).

Shallow Routing

Update the URL without re-fetching data:

'use client'
import { useRouter, usePathname, useSearchParams } from 'next/navigation'

export default function Filters() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()
  
  function setFilter(filter: string) {
    const params = new URLSearchParams(searchParams)
    params.set('filter', filter)
    router.push(pathname + '?' + params.toString())
  }
  
  return (
    <button onClick={() => setFilter('tech')}>
      Tech Posts
    </button>
  )
}

Next.js 15+ automatically intercepts history.pushState() / replaceState() calls, so direct manipulation works:

// Also works
window.history.pushState(null, '', '?filter=tech')

Prefetching

Automatic (Link)

<Link> components automatically prefetch on viewport entry (250px margin).

Manual (useRouter)

function Card({ href }) {
  const router = useRouter()
  
  return (
    <div onMouseEnter={() => router.prefetch(href)}>
      <a href={href}>Read more</a>
    </div>
  )
}

Cache TTL

Prefetched entries are valid for 30 seconds. Stale entries are re-prefetched on next trigger.

basePath Support

All navigation functions automatically handle basePath:

// next.config.js
module.exports = { basePath: '/docs' }

router.push('/api')  // Navigates to /docs/api
usePathname()        // Returns /api (without basePath)

i18n Support

Use the locale parameter for internationalized routing:

import Link from 'next/link'

<Link href="/" locale="fr">Français</Link>
<Link href="/" locale={false}>Default Locale</Link>

Limitations

SSR hook usage: Client hooks (useRouter, usePathname, etc.) cannot be called during SSR of client components. Use them inside useEffect or event handlers.

Concurrent navigation: Multiple rapid router.push() calls may result in race conditions. Await navigation if order matters.

Source

View source code → Implementation: /home/daytona/workspace/source/packages/vinext/src/shims/navigation.ts

CLI

Module Shims

Configuration

Cloudflare

next/navigation

Import

Client Hooks

useRouter

Router Methods

usePathname

useSearchParams

useParams

useSelectedLayoutSegment

useSelectedLayoutSegments

useServerInsertedHTML

Server Functions

redirect

permanentRedirect

notFound

forbidden

unauthorized

Shallow Routing

Prefetching

Automatic (Link)

Manual (useRouter)

Cache TTL

basePath Support

i18n Support

Limitations

Source

Build docs developers (and LLMs) love

CLI

Module Shims

Configuration

Cloudflare

Documentation Index

​Import

​Client Hooks

​useRouter

​Router Methods

​usePathname

​useSearchParams

​useParams

​useSelectedLayoutSegment

​useSelectedLayoutSegments

​useServerInsertedHTML

​Server Functions

​redirect

​permanentRedirect

​notFound

​forbidden

​unauthorized

​Shallow Routing

​Prefetching

​Automatic (Link)

​Manual (useRouter)

​Cache TTL

​basePath Support

​i18n Support

​Limitations

​Source

Build docs developers (and LLMs) love

Import

Client Hooks

useRouter

Router Methods

usePathname

useSearchParams

useParams

useSelectedLayoutSegment

useSelectedLayoutSegments

useServerInsertedHTML

Server Functions

redirect

permanentRedirect

notFound

forbidden

unauthorized

Shallow Routing

Prefetching

Automatic (Link)

Manual (useRouter)

Cache TTL

basePath Support

i18n Support

Limitations

Source