Edit

navigate()

Environment: client (server can import but not call it)

Provided by: vike

The navigate('/some/url') function enables you to programmatically switch pages without requiring the user to click a link.

For example, to redirect the user after a successful form submission:

import { navigate } from 'vike/client/router'
 
function Form() {
  return <form onSubmit={onSubmit}>{/* ... */}</form>
}
 
async function onSubmit() {
  const navigationPromise = navigate('/form/success')
  console.log("The URL changed but the new page hasn't rendered yet.")
  await navigationPromise
  console.log('The new page has finished rendering.')
}

If you want to redirect the user before the page has fully rendered (e.g. redirecting a non-authenticated user), then use throw redirect() instead. See: throw redirect() VS throw render() VS navigate().

To navigate back or forward in the user's browser history, use the History API instead:

• To go back, use window.history.back().
• To go forward, use window.history.forward().

For reloading the current page, use reload() instead.

Options

• navigate('/some-url', { keepScrollPosition: true }): Don't scroll to the top of the page, preserve the scroll position instead. See also:
  • API > +keepScrollPosition
  • <a href="/some-url" keep-scroll-position />.
• navigate('/some-url', { overwriteLastHistoryEntry: true }): Let the new URL replace the current URL in the browser history (instead of creating a new entry in the browser history). This effectively removes the current URL from the browser history. (Technically speaking: tell Vike to use history.replaceState() instead of history.pushState..)
• navigate('/some-url', { pageContext }): Pass extra pageContext values to the next page.

history.pushState()

If you want to change the URL completely independently of Vike then use history.pushState() instead of navigate().

// Somewhere in your client-side code
window.history.pushState(null, '', '/some-url')

You can then implement your navigation handling by listening to the popstate event.

⚠️

You must handle the popstate event, otherwise you'll break the browser's back- and forward history button.

window.addEventListener('popstate', () => {
  // Vike sets triggeredBy to 'vike' | 'browser' | 'user'
  // https://vike.dev/navigate#history-pushstate
  const { triggeredBy } = window.history.state
 
  // Navigation triggered by Vike or the browser
  if (triggeredBy === 'vike' || triggeredBy === 'browser') {
    // Abort: let Vike handle the navigation
    return
  }
 
  // Navigation triggered by our history.pushState() call
  if (triggeredBy === 'user') {
    // To Do: implement back- and forward navigation
  }
})

Without vike-{react,vue,solid}

If you don't use a UI framework Vike extension vike-react/vike-vue/vike-solid and if you use Server Routing then use window.location.href = '/some/url' instead of navigate() (because navigate() requires Client Routing).

The UI framework Vike extensions vike-react/vike-vue/vike-solid use Client Routing.

See also

• API > reload()
• API > throw redirect()
• API > +redirects
• Abort > throw redirect() VS throw render() VS navigate()