navigate

This function causes programmatic navigation and causes all raviger hooks to re-render. Internally it used by the <Link> component.

API

export function navigate(
  url: string,
  options?: {
    /**
     * Use a `replace` instead of `push` for navigation
     * @default false */
    replace?: boolean
    /** Values to serialize as a querystring, which will be appended to the `url` */
    query?: QueryParam | URLSearchParams
    /**  value to pass as the state/data to history push/replace*/
    state?: unknown
  }
): void

Note: navigate does not consider any basePath that may be set. The useNavigate hook should be used if you want to prepend the basePath to the URL when navigating.

Basic

the navigate function is intended to be used outside of components to perform page navigation programmatically.

import { navigate } from 'raviger'

export async function createUser () {
  let user = await createUser()
  navigate(`/users/${user.id}`)
}

Normal navigation adds an entry to the browsers history stack, enabling the back button to return to the previous location. To instead change the page without adding to the history stack use the replace option. This is sometimes desirable when creating objects as the creation-page form may no longer be a valid location

import { navigate } from 'raviger'

export async function createUser () {
  let user = await createUser()
  navigate(`/users/${user.id}`, { replace: true })
}

Navigating with Query Params

To navigate with a serialized query string pass an object to the query option.

import { navigate } from 'raviger'

export async function createUser () {
  let user = await createUser()
  navigate(`/users/${user.id}`, { query: { ref: 'create page' }})
}

Navigating with History State

By default the state is null. You can control the state passed to history.pushState | history.replaceState using the state option.

import { navigate } from 'raviger'

export async function createUser () {
  let user = await createUser()
  navigate(`/users/${user.id}`, { state: { user: user } })
}

Detecting navigate events

navigate has two modes: intra-domain navigation and extra-domain navigation. When navigating outside the current origin navigation is done directly, and no popstate event is dispatched. When navigating to the current origin a custom popstate event is dispatched. Two properties are attached to the event to help programmatically distinguish these events from popstate events dispatched by the browser back/forward buttons:

• __tag: 'raviger:navigation' — present on all events dispatched by navigate()
• __method: 'push' | 'replace' — indicates whether history.pushState or history.replaceState was used

If you are using useLocationChange, the initiatedBy field on the RavigerLocation object already reflects this distinction — prefer that over reading the event properties directly.