Skip to main content
navigateTo is available on both server side and client side. It can be used within the Nuxt context, or directly, to perform page navigation.
Make sure to always use await or return on result of navigateTo when calling it.
navigateTo cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use sendRedirect instead.

​
Type Signature

function navigateTo(
  to: RouteLocationRaw | undefined | null,
  options?: NavigateToOptions
): Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw

interface NavigateToOptions {
  replace?: boolean
  redirectCode?: number
  external?: boolean
  open?: OpenOptions
}

type OpenOptions = {
  target: string
  windowFeatures?: OpenWindowFeatures
}

type OpenWindowFeatures = {
  popup?: boolean
  noopener?: boolean
  noreferrer?: boolean
} & XOR<{ width?: number }, { innerWidth?: number }>
  & XOR<{ height?: number }, { innerHeight?: number }>
  & XOR<{ left?: number }, { screenX?: number }>
  & XOR<{ top?: number }, { screenY?: number }>

​
Parameters

​
to
RouteLocationRaw | undefined | null
default:"'/'"
The route to navigate to. Can be a plain string or a route object. When passed as undefined or null, it will default to '/'.
​
options
NavigateToOptions
Navigation options object.

​
Examples

​
Within a Vue Component

<script setup lang="ts">
// Passing 'to' as a string
await navigateTo('/search')

// ... or as a route object
await navigateTo({ path: '/search' })

// ... or as a route object with query parameters
await navigateTo({
  path: '/search',
  query: {
    page: 1,
    sort: 'asc',
  },
})
</script>

​
Within Route Middleware

export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // Setting the redirect code to '301 Moved Permanently'
    return navigateTo('/search', { redirectCode: 301 })
  }
})
When using navigateTo within route middleware, you must return its result to ensure the middleware execution flow works correctly.The following implementation will not work as expected:
export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // This will not work as expected
    navigateTo('/search', { redirectCode: 301 })
    return
  }
})
In this case, navigateTo will be executed but not returned, which may lead to unexpected behavior.
The external parameter influences how navigating to URLs is handled:
  • Without external: true:
    • Internal URLs navigate as expected.
    • External URLs throw an error.
  • With external: true:
    • Internal URLs navigate with a full-page reload.
    • External URLs navigate as expected.
<script setup lang="ts">
// Will throw an error;
// navigating to an external URL is not allowed by default
await navigateTo('https://nuxt.com')

// Will redirect successfully with the 'external' parameter set to 'true'
await navigateTo('https://nuxt.com', {
  external: true,
})
</script>

​
Opening a Page in a New Tab

<script setup lang="ts">
// Will open 'https://nuxt.com' in a new tab
await navigateTo('https://nuxt.com', {
  open: {
    target: '_blank',
    windowFeatures: {
      width: 500,
      height: 500,
    },
  },
})
</script>

​
See Also