Nuxt/docs/3.api/3.utils/navigate-to.md

title	description	links
navigateTo	navigateTo is a helper function that programmatically navigates users.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/router.ts xs

::note navigateTo is available on both server side and client side. ::

Usage

navigateTo is available on both server side and client side. It can be used within the Nuxt context, or directly, to perform page navigation.

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 })
  }
})

:read-more{to="/docs/guide/directory-structure/middleware"}

External URL

The external parameter in navigateTo 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.

Example

<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>

Using open()

<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>

Type

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

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

::warning Make sure to always use await or return on result of navigateTo when calling it. ::

Parameters

to

Type: RouteLocationRaw | undefined | null

Default: '/'

to can be a plain string or a route object to redirect to. When passed as undefined or null, it will default to '/'.

options (optional)

Type: NavigateToOptions

An object accepting the following properties:

• replace (optional)

  Type: boolean

  Default: false

  By default, navigateTo pushes the given route into the Vue Router's instance on the client side.

  This behavior can be changed by setting replace to true, to indicate that given route should be replaced.

• redirectCode (optional)

  Type: number

  Default: 302

  navigateTo redirects to the given path and sets the redirect code to 302 Found by default when the redirection takes place on the server side.

  This default behavior can be modified by providing different redirectCode. Commonly, 301 Moved Permanently can be used for permanent redirections.

• external (optional)

  Type: 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 (optional)

  Type: OpenOptions

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

  An object accepting the following properties:

  • target

    Type: string

    Default: '_blank'

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

  • windowFeatures (optional)

    Type: OpenWindowFeatures

    An object accepting the following properties:

    • popup (optional)

      Type: boolean

    • width or innerWidth (optional)

      Type: number

    • height or innerHeight (optional)

      Type: number

    • left or screenX (optional)

      Type: number

    • top or screenY (optional)

      Type: number

    • noopener (optional)

      Type: boolean

    • noreferrer (optional)

      Type: boolean

    Refer to the documentation for more detailed information on the windowFeatures properties.