Skip to main content
useRouter
Updated over a year ago

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 is true 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 by err.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

location

{}

The equivalent of window.location.

pathname

string

The equivalent of window.location.pathname.

query

{}

The equivalent of window.location.search. It returns an object with the URL's query string. If the URL does not have query string, it returns an empty object.

push

function (url, as, options) {}

For client-side routing navigation.

replace

function (url, as, options) {}

Replaces the current browser history instead of appending it to the stack.

reload

function () {}

The equivalent of window.location.reload(). It reloads the current page.

back

function () {}

The equivalent of window.history.back(). It navigates back in history, like clicking the browser's back button.

events

{}

Used to listen to events during the page's navigation. See examples above for more.

isReady

boolean

This should be used inside of an useEffect. Confirms when router fields are up to date and ready to use.

Did this answer your question?