navigate()

Environment: client.

The navigate('/some/url') function enables you to programmatically switch pages. In other words, you can implement navigations that aren't triggered by the user clicking on an anchor link <a>.

For example, you can use navigate() 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 while rendering a page (e.g. redirect non-authenticated users to a login page), then use throw redirect() instead. See Abort > throw redirect() VS throw render() VS navigate().

If you want to navigate back, then use window.history.back() instead.

Options

  • navigate('/some-url', { keepScrollPosition: true }): Don't scroll to the top of the page, preserve the scroll position instead. See also <a href="/some-url" keep-scroll-position />.
  • navigate('/some-url', { overwriteLastHistoryEntry: true }): Don't create a new entry in the browser's history, instead let the new URL replace the current URL. (This effectively removes the current URL from the browser history).

history.pushState()

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

Make sure you implement your navigation handling by listening to the popstate event.

⚠
You need to handle the popstate event yourself, otherwise you'll break the browser's back- and forward history button.
window.addEventListener('popstate', (event) => {
  // Vike sets triggeredBy to 'vike' | 'browser' | 'user'
  const { triggeredBy } = window.history.state
  /* Equivalent:
  const { triggeredBy } = event.state
  */
 
  // Navigation triggered by Vike or the browser
  if (triggeredBy === 'vike' || triggeredBy === 'browser') {
    // Abort: let Vike handle the navigation
    return
  }
 
  // Navigation triggered by your history.pushState() call
  if (triggeredBy === 'user') {
    // Implement your navigation handling here
  }
})

Without Vike extension

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