Overview
The useRouter
hook is used for managing client-side routing and accessing browser history.
Import
@getshogun/frontend-hooks
is already pre-installed on every Shogun Frontend store. It contains useRouter
and other hooks. To import:
import { useRouter } from '@getshogun/frontend-hooks'
π§ Importing useRouter
from frontend-router
is no longer recommend.
Basic usage
With useRouter
hook, you can access the router object and its properties inside any component/section:
import React from 'react'
import { useRouter } from '@getshogun/frontend-hooks'
const MyComponent = () => {
const router = useRouter()
return (
<p>You are currently at: {router.pathname}</p>
)
}
export default MyComponent
See the table below for all router properties available.
Methods usage
push
The push
method handle client-side navigation. It accepts the following parameters:
url
: A string indicating the URL to which to navigate.as
: A string indicating the URL that will be shown in the browser. This is optional.options
: An object with the following options:scroll
: A boolean that controls whether the page should scroll to the top after navigation. This istrue
by default.shallow
: A boolean that allows updating the URL path of the current page without rerunning the page and losing the state. You'll receive the updated pathname and the query via the router object.locale
: A string indicating the locale of the new page. This is optional.
JavaScript
import React from 'react'
import { useRouter } from '@getshogun/frontend-hooks'
const MyComponent = () => {
const router = useRouter()
return (
<React.Fragment>
{/* Simple usage */}
<button onClick={() => router.push('/contact')}>
Go to contact page
</button>
{/* Advanced usage */}
<button
onClick={
() => router.push(
'/profile',
'/my-profile',
{
scroll: false,
shallow: true,
locale: 'en'
}
)
}
>
Go to profile page
</button>
</React.Fragment>
)
}
export default MyComponent
replace
The replace
method replaces the current browser history, instead of adding the URL to the browser history stack. Its API is the same as the router.push
.
import React from 'react'
import { useRouter } from '@getshogun/frontend-hooks'
const MyComponent = () => {
const router = useRouter()
return (
<button onClick={() => router.replace('/contact')}>
Go to contact page
</button>
)
}
export default MyComponent
reload
The reload
method is the equivalent of clicking on the browser's refresh button.
import React from 'react'
import { useRouter } from '@getshogun/frontend-hooks'
const MyComponent = () => {
const router = useRouter()
return (
<button onClick={() => router.reload()}>
Reload this page
</button>
)
}
export default MyComponent
back
The back
method is the equivalent of clicking on the browser's back button.
import React from 'react'
import { useRouter } from '@getshogun/frontend-hooks'
const MyComponent = () => {
const router = useRouter()
return (
<button onClick={() => router.back()}>
Go back
</button>
)
}
export default MyComponent
events
The events
method responds to the following events during navigation:
routeChangeStart(url, { shallow })
: Triggered when a route starts to change.routeChangeComplete(url, { shallow })
: Triggered when a route change is finished.routeChangeError(err, url, { shallow })
: Triggered when an error occurs during routes transitions, or when a route load is cancelled (indicate byerr.cancelled
).beforeHistoryChange(url, { shallow })
: Triggered before changing the browser's history.hashChangeStart(url, { shallow })
: Triggered when the URL's hash will change but not the page.hashCompleteStart(url, { shallow })
: Triggered when the URL's hash has changed but not the page.
π§ Important
events
must be used inside of an useEffect
.
import React from 'react'
import { useRouter } from '@getshogun/frontend-hooks'
const MyComponent = () => {
const router = useRouter()
React.useEffect(() => {
const handleRouteChange = (url) => {
console.log(`URL is ${url}.`)
}
router.events.on('routeChangeStart', handleRouteChange)
return () => {
router.events.off('routeChangeStart', handleRouteChange)
}
})
return (
<button onClick={() => router.push('/')}>
Go to home page
</button>
)
}
export default MyComponentRouter object output
name | type | description |
|
| The equivalent of |
|
| The equivalent of |
|
| The equivalent of |
|
| For client-side routing navigation. |
|
| Replaces the current browser history instead of appending it to the stack. |
|
| The equivalent of |
|
| The equivalent of |
|
| Used to listen to events during the page's navigation. See examples above for more. |
|
| This should be used inside of an |