# 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:

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:

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.**

## `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`.

## `reload`

The `reload` method is the equivalent of clicking on the browser's refresh button.

## `back`

The `back` method is the equivalent of clicking on the browser's back button.

## `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.


`events` must be used inside of an `useEffect`.

# Router object output

`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.