navigateTo

Programmatically navigate users to pages.

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.

Show options properties

replace · boolean · default: "false"

By default, navigateTo pushes the given route into the Vue Router’s instance on the client side. Set to true to replace the current route instead.

redirectCode · number · default: "302"

The HTTP status code to use for server-side redirects. Defaults to 302 Found. Commonly, 301 Moved Permanently can be used for permanent redirections.

external · boolean · default: "false"

Allows navigating to an external URL when set to true. Otherwise, navigateTo will throw an error, as external navigation is not allowed by default.

open · OpenOptions

Allows navigating to the URL using the window.open() method. This option is only applicable on the client side and will be ignored on the server side.

Show open properties

target · string · default: "'_blank'"

A string, without whitespace, specifying the name of the browsing context the resource is being loaded into.

windowFeatures · OpenWindowFeatures

Window features configuration object.

Show windowFeatures properties

popup · boolean

Requests a minimal popup window instead of a new tab, with UI features decided by the browser.

width · number

Specifies the content area’s width (minimum 100 pixels), including scrollbars. Mutually exclusive with innerWidth.

innerWidth · number

Specifies the content area’s width (minimum 100 pixels), including scrollbars. Mutually exclusive with width.

height · number

Specifies the content area’s height (minimum 100 pixels), including scrollbars. Mutually exclusive with innerHeight.

innerHeight · number

Specifies the content area’s height (minimum 100 pixels), including scrollbars. Mutually exclusive with height.

left · number

Sets the horizontal position of the new window relative to the left edge of the screen. Mutually exclusive with screenX.

screenX · number

Sets the horizontal position of the new window relative to the left edge of the screen. Mutually exclusive with left.

top · number

Sets the vertical position of the new window relative to the top edge of the screen. Mutually exclusive with screenY.

screenY · number

Sets the vertical position of the new window relative to the top edge of the screen. Mutually exclusive with top.

noopener · boolean

Prevents the new window from accessing the originating window via window.opener.

noreferrer · boolean

Prevents the Referer header from being sent and implicitly enables noopener.

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.

Navigating to an External URL

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

• Route Middleware Guide
• abortNavigation