2020-01-03 19:16:51 +01:00
---
description: Learn more about the API of the Next.js Router, and access the router instance in your page with the useRouter hook.
---
2019-12-23 16:07:38 +01:00
# next/router
> Before moving forward, we recommend you to read [Routing Introduction](/docs/routing/introduction.md) first.
## useRouter
If you want to access the [`router` object ](#router-object ) inside any function component in your app, you can use the `useRouter` hook, take a look at the following example:
```jsx
import { useRouter } from 'next/router'
function ActiveLink({ children, href }) {
const router = useRouter()
const style = {
marginRight: 10,
color: router.pathname === href ? 'red' : 'black',
}
2020-05-18 21:24:37 +02:00
const handleClick = (e) => {
2019-12-23 16:07:38 +01:00
e.preventDefault()
router.push(href)
}
return (
< a href = {href} onClick = {handleClick} style = {style} >
{children}
< / a >
)
}
export default ActiveLink
```
> `useRouter` is a [React Hook](https://reactjs.org/docs/hooks-intro.html), meaning it cannot be used with classes. You can either use [withRouter](#withRouter) or wrap your class in a function component.
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
## `router` object
2019-12-23 16:07:38 +01:00
The following is the definition of the `router` object returned by both [`useRouter` ](#useRouter ) and [`withRouter` ](#withRouter ):
2020-01-08 11:56:17 +01:00
- `pathname` : `String` - Current route. That is the path of the page in `/pages`
2020-05-22 10:36:45 +02:00
- `query` : `Object` - The query string parsed to an object. It will be an empty object during prerendering if the page doesn't have [data fetching requirements ](/docs/basic-features/data-fetching.md ). Defaults to `{}`
2019-12-23 16:07:38 +01:00
- `asPath` : `String` - Actual path (including the query) shown in the browser
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
Additionally, the following methods are also included inside `router` :
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
### router.push
2019-12-23 16:07:38 +01:00
< details >
< summary > < b > Examples< / b > < / summary >
< ul >
2020-05-27 23:51:11 +02:00
< li > < a href = "https://github.com/vercel/next.js/tree/canary/examples/using-router" > Using Router< / a > < / li >
2019-12-23 16:07:38 +01:00
< / ul >
< / details >
Handles client-side transitions, this method is useful for cases where [`next/link` ](/docs/api-reference/next/link.md ) is not enough.
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
router.push(url, as, options)
2019-12-23 16:07:38 +01:00
```
- `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:
2020-04-15 21:38:46 +02:00
- [`shallow` ](/docs/routing/shallow-routing.md ): Update the path of the current page without rerunning [`getStaticProps` ](/docs/basic-features/data-fetching.md#getstaticprops-static-generation ), [`getServerSideProps` ](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering ) or [`getInitialProps` ](/docs/api-reference/data-fetching/getInitialProps.md ). Defaults to `false`
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
> You don't need to use `router.push` for external URLs. [window.location](https://developer.mozilla.org/en-US/docs/Web/API/Window/location) is better suited for those cases.
2019-12-23 16:07:38 +01:00
#### Usage
Navigating to `pages/about.js` , which is a predefined route:
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
return < span onClick = {() = > router.push('/about')}>Click me< / span >
2019-12-23 16:07:38 +01:00
}
```
Navigating `pages/post/[pid].js` , which is a dynamic route:
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
2019-12-23 16:07:38 +01:00
return (
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
< span onClick = {() = > router.push('/post/[pid]', '/post/abc')}>
2019-12-23 16:07:38 +01:00
Click me
< / span >
)
}
```
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
Redirecting the user to `pages/login.js` , useful for pages behind authentication:
```jsx
import { useEffect } from 'react'
import { useRouter } from 'next/router'
// Here you would fetch and return the user
const useUser = () => ({ user: null, loading: false })
export default function Page() {
const { user, loading } = useUser()
const router = useRouter()
useEffect(() => {
if (!(user || loading)) {
router.push('/login')
}
}, [user, loading])
return < p > Redirecting...< / p >
}
```
2019-12-23 16:07:38 +01:00
#### With URL object
You can use an URL object in the same way you can use it for [`next/link` ](/docs/api-reference/next/link.md#with-url-object ). Works for both the `url` and `as` parameters:
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useRouter } from 'next/router'
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
export default function ReadMore() {
const router = useRouter()
2019-12-23 16:07:38 +01:00
return (
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
< span
onClick={() => {
router.push({
pathname: '/about',
query: { name: 'Vercel' },
})
}}
>
Click here to read more
< / span >
2019-12-23 16:07:38 +01:00
)
}
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
```
### router.replace
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
Similar to the `replace` prop in [`next/link` ](/docs/api-reference/next/link.md ), `router.replace` will prevent adding a new URL entry into the `history` stack.
```jsx
router.replace(url, as, options)
2019-12-23 16:07:38 +01:00
```
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
- The API for `router.replace` is exactly the same as the API for [`router.push` ](#router.push ).
#### Usage
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
Take a look at the following example:
2019-12-23 16:07:38 +01:00
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useRouter } from 'next/router'
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
export default function Page() {
const router = useRouter()
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
return < span onClick = {() = > router.replace('/home')}>Click me< / span >
}
```
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
### router.prefetch
2020-05-02 06:42:22 +02:00
Prefetch pages for faster client-side transitions. This method is only useful for navigations without [`next/link` ](/docs/api-reference/next/link.md ), as `next/link` takes care of prefetching pages automatically.
> This is a production only feature. Next.js doesn't prefetch pages on development.
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
router.prefetch(url, as)
2020-05-02 06:42:22 +02:00
```
- `url` - The path to a `page` inside the `pages` directory
- `as` - Optional decorator for `url` , used to prefetch [dynamic routes ](/docs/routing/dynamic-routes ). Defaults to `url`
#### Usage
Let's say you have a login page, and after a login, you redirect the user to the dashboard. For that case, we can prefetch the dashboard to make a faster transition, like in the following example:
```jsx
import { useCallback, useEffect } from 'react'
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useRouter } from 'next/router'
2020-05-02 06:42:22 +02:00
export default function Login() {
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
const router = useRouter()
2020-05-18 21:24:37 +02:00
const handleSubmit = useCallback((e) => {
2020-05-02 06:42:22 +02:00
e.preventDefault()
fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
/* Form data */
}),
2020-05-18 21:24:37 +02:00
}).then((res) => {
2020-05-11 23:08:31 +02:00
// Do a fast client-side transition to the already prefetched dashboard page
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
if (res.ok) router.push('/dashboard')
2020-05-02 06:42:22 +02:00
})
}, [])
useEffect(() => {
// Prefetch the dashboard page as the user will go there after the login
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
router.prefetch('/dashboard')
2020-05-02 06:42:22 +02:00
}, [])
return (
< form onSubmit = {handleSubmit} >
{/* Form fields */}
< button type = "submit" > Login< / button >
< / form >
)
}
```
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
### router.beforePopState
2019-12-23 16:07:38 +01:00
In some cases (for example, if using a [Custom Server ](/docs/advanced-features/custom-server.md )), you may wish to listen to [popstate ](https://developer.mozilla.org/en-US/docs/Web/Events/popstate ) and do something before the router acts on it.
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
router.beforePopState(cb)
2019-12-23 16:07:38 +01:00
```
2020-04-17 16:26:25 +02:00
- `cb` - The function to run on incoming `popstate` events. The function receives the state of the event as an object with the following props:
2019-12-23 16:07:38 +01:00
- `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
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
- `options` : `Object` - Additional options sent by [router.push ](#router.push )
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
If `cb` returns `false` , the Next.js router will not handle `popstate` , and you'll be responsible for handling it in that case. See [Disabling file-system routing ](/docs/advanced-features/custom-server.md#disabling-file-system-routing ).
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
#### Usage
You could use `beforePopState` to manipulate the request, or force a SSR refresh, as in the following example:
```jsx
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
useEffect(() => {
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
})
}, [])
return < p > Welcome to the page< / p >
}
```
### router.back
2020-05-02 06:11:06 +02:00
2020-05-02 06:20:09 +02:00
Navigate back in history. Equivalent to clicking the browser’ s back button. It executes `window.history.back()` .
2020-05-02 06:11:06 +02:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
#### Usage
2020-05-02 06:11:06 +02:00
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useRouter } from 'next/router'
2020-05-02 06:11:06 +02:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
export default function Page() {
const router = useRouter()
return < span onClick = {() = > router.back()}>Click here to go back< / span >
}
2020-05-02 06:11:06 +02:00
```
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
### router.reload
2020-05-02 06:11:06 +02:00
2020-05-02 06:20:09 +02:00
Reload the current URL. Equivalent to clicking the browser’ s refresh button. It executes `window.location.reload()` .
2020-05-02 06:11:06 +02:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
#### Usage
2020-05-02 06:11:06 +02:00
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
2020-05-02 06:11:06 +02:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
return < span onClick = {() = > router.reload()}>Click here to reload< / span >
}
2020-05-02 06:11:06 +02:00
```
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
### router.events
2019-12-23 16:07:38 +01:00
< details >
< summary > < b > Examples< / b > < / summary >
< ul >
2020-05-27 23:51:11 +02:00
< li > < a href = "https://github.com/vercel/next.js/tree/canary/examples/with-loading" > With a page loading indicator< / a > < / li >
2019-12-23 16:07:38 +01:00
< / ul >
< / details >
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
You can listen to different events happening inside the Next.js Router. Here's a list of supported events:
2019-12-23 16:07:38 +01:00
- `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
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
> 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`.
2020-07-20 22:03:49 +02:00
>
> **Note:** If you [configure a `basePath`](/docs/api-reference/next.config.js/basepath.md) then the value of `url` will be `basePath + as`.
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
#### Usage
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
For example, to listen to the router event `routeChangeStart` , open or create `pages/_app.js` and subscribe to the event, like so:
2019-12-23 16:07:38 +01:00
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useEffect } from 'react'
import { useRouter } from 'next/router'
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
export default function MyApp({ Component, pageProps }) {
const router = useRouter()
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
useEffect(() => {
const handleRouteChange = (url) => {
console.log('App is changing to: ', url)
}
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
router.events.on('routeChangeStart', handleRouteChange)
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
// If the component is unmounted, unsubscribe
// from the event with the `off` method:
return () => {
router.events.off('routeChangeStart', handleRouteChange)
}
}, [])
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
return < Component { . . . pageProps } / >
}
2019-12-23 16:07:38 +01:00
```
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
> We use a [Custom App](/docs/advanced-features/custom-app.md) (`pages/_app.js`) for this example to subscribe to the event because it's not unmounted on page navigations, but you can subscribe to router events on any component in your application.
Router events should be registered when a component mounts ([useEffect](https://reactjs.org/docs/hooks-effect.html) or [componentDidMount ](https://reactjs.org/docs/react-component.html#componentdidmount ) / [componentWillUnmount ](https://reactjs.org/docs/react-component.html#componentwillunmount )) or imperatively when an event happens.
2019-12-23 16:07:38 +01:00
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:
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { useEffect } from 'react'
import { useRouter } from 'next/router'
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
export default function MyApp({ Component, pageProps }) {
const router = useRouter()
useEffect(() => {
const handleRouteChangeError = (err, url) => {
if (err.cancelled) {
console.log(`Route to ${url} was cancelled!`)
}
}
router.events.on('routeChangeError', handleRouteChangeError)
// If the component is unmounted, unsubscribe
// from the event with the `off` method:
return () => {
router.events.off('routeChangeError', handleRouteChangeError)
}
}, [])
return < Component { . . . pageProps } / >
}
2019-12-23 16:07:38 +01:00
```
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
## withRouter
If [`useRouter` ](#useRouter ) is not the best fit for you, `withRouter` can also add the same [`router` object ](#router-object ) to any component.
### Usage
2019-12-23 16:07:38 +01:00
```jsx
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
import { withRouter } from 'next/router'
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
function Page({ router }) {
return < p > {router.pathname}< / p >
}
2019-12-23 16:07:38 +01:00
[Docs] Focus on useRouter (#14515)
[ch4109]
Closes https://github.com/vercel/next.js/issues/14500
Our current docs for `next/router` use examples from both `useRouter` and `import Router from 'next/router'`, with this PR I'm unifying the API into `useRouter` (`withRouter` is still going to be mentioned multiple times as it is the HOC alternative) and no longer mentioning that you can import a global `Router` object from `next/router`, not sure if I should mention it at least once but that didn't seem to be required.
I also did some structural changes to the docs for `next/router`, now every method starts with a description, then the implementation and explanation of the parameters of the method, and then the usage example, because every method uses the same `Usage` title the hash for them would be something like `#usage`, `#usage-1`, `#usage-2`, e.t.c, so I'm not very happy with this but it looks good.
Feedback wanted 🙏
2020-06-26 01:35:28 +02:00
export default withRouter(Page)
2019-12-23 16:07:38 +01:00
```