8.7 KiB
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
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 apage
as
- Optional decorator for the URL that will be shown in the browser. Defaults tourl
options
- Optional object with the following configuration options:shallow
: Update the path of the current page without rerunninggetStaticProps
,getServerSideProps
orgetInitialProps
. Defaults tofalse
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 run on incomingpopstate
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 apage
as
:String
- the url that will be shown in the browseroptions
: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.back
Navigate back in history, equivalent to clicking the back button. It executes window.history.back()
.
import Router from 'next/router'
Router.back()
Router.reload
Reload the current URL, equivalent to clicking the refresh button. It executes window.location.reload()
.
import Router from 'next/router'
Router.reload()
Router.events
Examples
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 changerouteChangeComplete(url)
- Fires when a route changed completelyrouteChangeError(err, url)
- Fires when there's an error when changing routes, or a route load is cancellederr.cancelled
- Indicates if the navigation was cancelled
beforeHistoryChange(url)
- Fires just before changing the browser's historyhashChangeStart(url)
- Fires when the hash will change but not the pagehashChangeComplete(url)
- Fires when the hash has changed but not the page
Here
url
is the URL shown in the browser. If you callRouter.push(url, as)
(or similar), then the value ofurl
will beas
.
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)
}
}, [])