router.md

description
Learn more about the API of the Next.js Router, and access the router instance in your page with the useRouter hook.

next/router

Before moving forward, we recommend you to read Routing Introduction first.

useRouter

If you want to access the router object inside any function component in your app, you can use the useRouter hook, take a look at the following example:

import { useRouter } from 'next/router'

function ActiveLink({ children, href }) {
  const router = useRouter()
  const style = {
    marginRight: 10,
    color: router.pathname === href ? 'red' : 'black',
  }

  const handleClick = e => {
    e.preventDefault()
    router.push(href)
  }

  return (
    <a href={href} onClick={handleClick} style={style}>
      {children}
    </a>
  )
}

export default ActiveLink

useRouter is a React Hook, meaning it cannot be used with classes. You can either use withRouter or wrap your class in a function component.

router object

The following is the definition of the router object returned by both useRouter and withRouter:

• pathname: String - Current route. That is the path of the page in /pages
• query: Object - The query string parsed to an object. Defaults to {}
• asPath: String - Actual path (including the query) shown in the browser

Additionally, the Router API is also included inside the object.

The query object will be empty during prerendering if the page is statically optimized.

withRouter

If useRouter is not the best fit for you, withRouter can also add the same router object to any component, here's how to use it:

import { withRouter } from 'next/router'

function Page({ router }) {
  return <p>{router.pathname}</p>
}

export default withRouter(Page)

Router API

The API of Router, exported by next/router, is defined below.

Router.push

Examples

• Using Router

Handles client-side transitions, this method is useful for cases where next/link is not enough.

import Router from 'next/router'

Router.push(url, as, options)

• url - The URL to navigate to. This is usually the name of a page
• as - Optional decorator for the URL that will be shown in the browser. Defaults to url
• options - Optional object with the following configuration options:
  • shallow: Update the path of the current page without rerunning getInitialProps. Defaults to false

You don't need to use Router for external URLs, window.location is better suited for those cases.

Usage

Navigating to pages/about.js, which is a predefined route:

import Router from 'next/router'

function Page() {
  return <span onClick={() => Router.push('/about')}>Click me</span>
}

Navigating pages/post/[pid].js, which is a dynamic route:

import Router from 'next/router'

function Page() {
  return (
    <span onClick={() => Router.push('/post/[pid]', '/post/abc')}>
      Click me
    </span>
  )
}

With URL object

You can use an URL object in the same way you can use it for next/link. Works for both the url and as parameters:

import Router from 'next/router'

const handler = () => {
  Router.push({
    pathname: '/about',
    query: { name: 'Zeit' },
  })
}

function ReadMore() {
  return (
    <div>
      Click <span onClick={handler}>here</span> to read more
    </div>
  )
}

export default ReadMore

Router.replace

Similar to the replace prop in next/link, Router.replace will prevent adding a new URL entry into the history stack, take a look at the following example:

import Router from 'next/router'

Router.replace('/home')

The API for Router.replace is exactly the same as that used for Router.push.

Router.beforePopState

In some cases (for example, if using a Custom Server), you may wish to listen to popstate and do something before the router acts on it.

You could use this to manipulate the request, or force a SSR refresh, as in the following example:

import Router from 'next/router'

Router.beforePopState(({ url, as, options }) => {
  // I only want to allow these two routes!
  if (as !== '/' && as !== '/other') {
    // Have SSR render bad routes as a 404.
    window.location.href = as
    return false
  }

  return true
})

Router.beforePopState(cb: () => boolean)

• cb - The function to execute on incoming popstate events. The function receives the state of the event as an object with the following props:
  • url: String - the route for the new state. This is usually the name of a page
  • as: String - the url that will be shown in the browser
  • options: Object - Additional options sent by Router.push

If the function you pass into beforePopState returns false, Router will not handle popstate and you'll be responsible for handling it, in that case. See Disabling file-system routing.

Router.events

Examples

• With a page loading indicator

You can listen to different events happening inside the Router. Here's a list of supported events:

• routeChangeStart(url) - Fires when a route starts to change
• routeChangeComplete(url) - Fires when a route changed completely
• routeChangeError(err, url) - Fires when there's an error when changing routes, or a route load is cancelled
  • err.cancelled - Indicates if the navigation was cancelled
• beforeHistoryChange(url) - Fires just before changing the browser's history
• hashChangeStart(url) - Fires when the hash will change but not the page
• hashChangeComplete(url) - Fires when the hash has changed but not the page

Here url is the URL shown in the browser. If you call Router.push(url, as) (or similar), then the value of url will be as.

For example, to listen to the router event routeChangeStart, do the following:

import Router from 'next/router'

const handleRouteChange = url => {
  console.log('App is changing to: ', url)
}

Router.events.on('routeChangeStart', handleRouteChange)

If you no longer want to listen to the event, unsubscribe with the off method:

import Router from 'next/router'

Router.events.off('routeChangeStart', handleRouteChange)

If a route load is cancelled (for example, by clicking two links rapidly in succession), routeChangeError will fire. And the passed err will contain a cancelled property set to true, as in the following example:

import Router from 'next/router'

Router.events.on('routeChangeError', (err, url) => {
  if (err.cancelled) {
    console.log(`Route to ${url} was cancelled!`)
  }
})

Router events should be registered when a component mounts (useEffect or componentDidMount / componentWillUnmount) or imperatively when an event happens, as in the following example:

import Router from 'next/router'

useEffect(() => {
  const handleRouteChange = url => {
    console.log('App is changing to: ', url)
  }

  Router.events.on('routeChangeStart', handleRouteChange)
  return () => {
    Router.events.off('routeChangeStart', handleRouteChange)
  }
}, [])