navigateTo()
Programmatically navigates, working safely in setup, middleware, and plugins.
Syntax
await navigateTo(to, options?)Parameters
| Name | Type | Required | Description |
|---|---|---|---|
to | string | RouteLocationRaw | Yes | Target path or route location object. Use an object with `external: true` for external URLs. |
options | object | No | `replace`, `redirectCode` (default 302), `external`, `open`. |
Returns
Promise | false — Navigation promise; return its value from middleware.
Examples
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
const user = useState('user')
if (!user.value) return navigateTo('/login')
})
<script setup lang="ts">
function checkout() {
return navigateTo({ path: '/checkout', query: { step: '1' } })
}
</script>
navigateTo('https://example.com', {
external: true,
open: { target: '_blank' },
})
Notes
Always `return` (or `await`) it inside route middleware so Nuxt
handles the redirect correctly during SSR. External URLs require
`external: true`. Use `redirectCode: 301` for permanent server-side
redirects. Preferred over `useRouter().push()` for SSR safety.