diff --git a/docs/content/2.guide/3.directory-structure/8.middleware.md b/docs/content/2.guide/3.directory-structure/8.middleware.md index 672fb7b56..e0219ca81 100644 --- a/docs/content/2.guide/3.directory-structure/8.middleware.md +++ b/docs/content/2.guide/3.directory-structure/8.middleware.md @@ -35,7 +35,7 @@ export default defineNuxtRouteMiddleware((to, from) => { Nuxt provides two globally available helpers that can be returned directly from the middleware: -1. `navigateTo (route: string | Route, options: { redirectCode: number, replace: boolean )` - Redirects to the given route, within plugins or middleware. It can also be called directly to perform page navigation. +1. `navigateTo (to: RouteLocationRaw | undefined | null, options: { replace: boolean, redirectCode: number, external: boolean )` - Redirects to the given route, within plugins or middleware. It can also be called directly to perform page navigation. 2. `abortNavigation (err?: string | Error)` - Aborts the navigation, with an optional error message. Unlike navigation guards in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards), a third `next()` argument is not passed, and redirects or route cancellation is handled by returning a value from the middleware. Possible return values are: diff --git a/docs/content/3.api/1.composables/use-router.md b/docs/content/3.api/1.composables/use-router.md index 9d44195d0..66d9e9f2a 100644 --- a/docs/content/3.api/1.composables/use-router.md +++ b/docs/content/3.api/1.composables/use-router.md @@ -19,8 +19,8 @@ If you have a `pages/` folder, `useRouter` is identical in behavior to the one p - **back:** Go back in history if possible, same as `router.go(-1)`. - **forward:** Go forward in history if possible, same as `router.go(1)`. - **go:** Move forward or backward through the history without the hierarchical restrictions enforced in `router.back()` and `router.forward()`. -- **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to#navigateto) instead.** -- **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to#navigateto) instead.** +- **push:** Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to) instead.** +- **replace:** Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](http://v3.nuxtjs.org/api/utils/navigate-to) instead.** > TIP: `router.addRoute()` adds route details into an array of routes and it is useful while building Nuxt plugins while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in Nuxt Page components, Vue components and composable. diff --git a/docs/content/3.api/3.utils/navigate-to.md b/docs/content/3.api/3.utils/navigate-to.md index b2681f9d1..c48d0cbd6 100644 --- a/docs/content/3.api/3.utils/navigate-to.md +++ b/docs/content/3.api/3.utils/navigate-to.md @@ -1,76 +1,115 @@ # `navigateTo` -`navigateTo` is a router helper function that allows creating programmatic navigation for users to navigate within Nuxt application. +`navigateTo` is a router helper function that allows programmatically navigating users through your Nuxt application. `navigateTo` is available on both server side and client side. It can be used within plugins, middleware or can be called directly to perform page navigation. -## Usage +## Type ```ts -navigateTo (route: string | Route, { redirectCode = 302, replace = false }) +navigateTo(to: RouteLocationRaw | undefined | null, options?: NavigateToOptions) => Promise | RouteLocationRaw + +interface NavigateToOptions { + replace?: boolean + redirectCode?: number + external?: boolean +} ``` -`route` can be a plain string or a route object to redirect to. - ::alert{type="warning"} -Make sure to use always `await` or `return` on result of `navigateTo()` when calling it. +Make sure to always use `await` or `return` on result of `navigateTo` when calling it. :: +## Parameters + +### `to` + +**Type**: [`RouteLocationRaw`](https://router.vuejs.org/api/#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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) 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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) 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. + ## Examples -### Within a Vue Component +### Navigating Within a Vue Component ```vue ``` -### Within Route Middleware +### Navigating Within Route Middleware -```js +```ts export default defineNuxtRouteMiddleware((to, from) => { - // set the redirect code to 301 Moved Permanently + // setting the redirect code to '301 Moved Permanently' return navigateTo('/search', { redirectCode: 301 }) }) ``` -```js - -``` - ::ReadMore{link="/guide/directory-structure/middleware"} :: -### Options +### Navigating to an External URL -#### `redirectCode` +```vue + +```