> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cloudflare/vinext/llms.txt
> Use this file to discover all available pages before exploring further.
# next/router
> Pages Router navigation and routing
The `next/router` module provides the Pages Router API, including the `useRouter` hook and default Router singleton for programmatic navigation.
## Import
```typescript theme={null}
import { useRouter } from 'next/router'
import Router from 'next/router'
```
## useRouter Hook
Returns a router instance with navigation methods and current route state.
```tsx theme={null}
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
Current path: {router.pathname}
Query: {JSON.stringify(router.query)}
)
}
```
## Router Object
### Properties
Current pathname (without basePath or query).
```tsx theme={null}
router.pathname // "/blog/[slug]"
```
Current route pattern (with dynamic segments).
```tsx theme={null}
router.route // "/blog/[slug]"
```
Query parameters and dynamic route params.
```tsx theme={null}
// URL: /blog/hello-world?author=john
router.query // { slug: "hello-world", author: "john" }
```
Full URL path including query string.
```tsx theme={null}
router.asPath // "/blog/hello-world?author=john"
```
Configured base path from `next.config.js`.
```tsx theme={null}
router.basePath // "/docs" or ""
```
Current locale (i18n).
```tsx theme={null}
router.locale // "en" or "fr"
```
All configured locales.
```tsx theme={null}
router.locales // ["en", "fr", "de"]
```
Default locale.
```tsx theme={null}
router.defaultLocale // "en"
```
Whether the router is ready (always `true` in vinext).
```tsx theme={null}
if (router.isReady) {
// Router fields are populated
}
```
Whether in preview mode (always `false` in vinext).
Whether the page is in fallback mode (ISR).
### Methods
Navigate to a new URL (pushes history entry).
```tsx theme={null}
await router.push('/about')
await router.push({ pathname: '/user/[id]', query: { id: '123' } })
await router.push('/post', undefined, { scroll: false })
await router.push('/', undefined, { locale: 'fr' })
```
**Parameters:**
* `url: string | UrlObject` — Destination
* `as?: string` — URL mask (legacy)
* `options?: { shallow?: boolean; scroll?: boolean; locale?: string }`
**Returns:** `Promise` — `true` on success
Navigate to a new URL (replaces history entry).
```tsx theme={null}
await router.replace('/login')
await router.replace('/dashboard', undefined, { shallow: true })
```
Same parameters as `push()`.
Navigate to the previous page.
```tsx theme={null}
```
Hard reload the current page.
```tsx theme={null}
```
Prefetch a page for faster navigation.
```tsx theme={null}
router.prefetch('/dashboard')}>
Hover to prefetch
```
Register a callback to run before browser back/forward navigation.
```tsx theme={null}
router.beforePopState(({ url, as, options }) => {
// Return false to prevent navigation
if (hasUnsavedChanges()) {
alert('You have unsaved changes!')
return false
}
return true
})
```
Event emitter for route changes.
```tsx theme={null}
useEffect(() => {
const handleStart = (url) => console.log('Navigating to', url)
const handleComplete = (url) => console.log('Navigated to', url)
router.events.on('routeChangeStart', handleStart)
router.events.on('routeChangeComplete', handleComplete)
return () => {
router.events.off('routeChangeStart', handleStart)
router.events.off('routeChangeComplete', handleComplete)
}
}, [])
```
**Events:**
* `routeChangeStart(url: string)` — Before navigation starts
* `routeChangeComplete(url: string)` — After navigation completes
* `routeChangeError(err: Error, url: string)` — On navigation error
## Router Singleton
The default export provides a router singleton for use outside components:
```typescript theme={null}
import Router from 'next/router'
// Usage in utility functions
export async function logout() {
await clearSession()
await Router.push('/login')
}
```
Methods and events are identical to `useRouter()`.
## UrlObject
Construct URLs programmatically:
```typescript theme={null}
interface UrlObject {
pathname?: string
query?: Record
}
```
```tsx theme={null}
router.push({
pathname: '/blog/[slug]',
query: { slug: 'hello-world', author: 'john' }
})
// Navigates to: /blog/hello-world?author=john
```
## Navigation Options
```typescript theme={null}
interface TransitionOptions {
shallow?: boolean // Update URL without re-fetching (deprecated)
scroll?: boolean // Scroll to top after navigation (default: true)
locale?: string // Navigate to a specific locale
}
```
### Shallow Routing
Update the URL without triggering a full page navigation:
```tsx theme={null}
router.push('/?filter=tech', undefined, { shallow: true })
```
**Deprecated in App Router** — Use `window.history.pushState()` instead.
### Scroll Control
```tsx theme={null}
// Don't scroll to top (stay at current position)
router.push('/page', undefined, { scroll: false })
```
## Route Events
Listen for navigation events:
```tsx theme={null}
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
useEffect(() => {
function handleRouteChange(url) {
console.log('App is changing to: ', url)
}
router.events.on('routeChangeComplete', handleRouteChange)
return () => {
router.events.off('routeChangeComplete', handleRouteChange)
}
}, [router.events])
return
Page content
}
```
### Available Events
* **routeChangeStart(url)** — Fires before navigation
* **routeChangeComplete(url)** — Fires after navigation succeeds
* **routeChangeError(err, url)** — Fires on navigation error
## Hash Navigation
Navigate to hash links:
```tsx theme={null}
router.push('#section-2')
router.push('/page#section-2')
```
Scroll to the target element automatically.
## External URLs
External URLs trigger full page navigation:
```tsx theme={null}
router.push('https://example.com')
// Same as: window.location.href = 'https://example.com'
```
## Dynamic Routes
Access dynamic route parameters via `router.query`:
```tsx theme={null}
// File: pages/blog/[slug].tsx
import { useRouter } from 'next/router'
export default function Post() {
const router = useRouter()
const { slug } = router.query
return