---
url: /data-loaders/basic.md
---
# `defineBasicLoader()`

Basic data loader that always reruns on navigation.

::: warning
Data Loaders are experimental. Feedback is very welcome to shape the future of data loaders in Vue Router.
:::

## Setup

## Example

```vue
<script lang="ts">
import { defineBasicLoader } from 'vue-router/experimental'
import { getUserById } from '../api'

export const useUserData = defineBasicLoader(
  (to, { signal }) => {
    return getUserById(to.params.id, { signal })
  },
  {
    // used for SSR only
    key: 'user-data',
  }
)
</script>

<script lang="ts" setup>
const route = useRoute('/users/[id]')

const {
  user,
  error
  isLoading,
  reload,
} = useUserData()
</script>

<template>
  <main>
    <h1>Basic Data Loader Example</h1>
    <pre>User: {{ route.params.id }}</pre>

    <fieldset>
      <legend>Controls</legend>

      <button @click="reload()">Refetch</button>
    </fieldset>

    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 - 1 } }"
      >Previous</RouterLink
    >
    |
    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 + 1 } }"
      >Next</RouterLink
    >

    <h2>State</h2>

    <p>
      <code>isLoading: {{ isLoading }}</code>
    </p>
    <pre v-if="error">Error: {{ error }}</pre>
    <pre v-else>{{ user == null ? String(user) : user }}</pre>
  </main>
</template>
```

## SSR

## Nuxt

## Unresolved Questions

* Should this basic version also track what is used in the route object, like [Svelte Data Loaders do](https://kit.svelte.dev/docs/load#rerunning-load-functions)?

---

---
url: /data-loaders/colada.md
---
# `defineColadaLoader()`

Loaders that use [@pinia/colada](https://github.com/posva/pinia-colada) under the hood. These loaders provide the most efficient solution to asynchronous state with cache, ssr support and more.

The key used in these loaders is directly passed to `useQuery()` from `@pinia/colada` and can be invalidated with `useMutation()` hooks. See [Pinia Colada documentation about query invalidation](https://pinia-colada.esm.dev/guide/query-invalidation.html) to learn more.

## Setup

Follow the installation instructions in [@pinia/colada](https://github.com/posva/pinia-colada).

## Example

```vue
<script lang="ts">
import { defineColadaLoader } from 'vue-router/experimental/pinia-colada'
import { getUserById } from '../api'

export const useUserData = defineColadaLoader({
  async query(to, { signal }) {
    return getUserById(to.params.id, { signal })
  },
  key: to => ['users', to.params.id],
  // Keep the data "fresh" 10 seconds to avoid fetching the same data too often
  staleTime: 10000,
})
</script>

<script lang="ts" setup>
const route = useRoute('/users/[id]')

const {
  user,
  status,
  error
  isLoading,
  reload,
  refresh,
} = useUserData()
</script>

<template>
  <main>
    <h1>Pinia Colada Loader Example</h1>
    <pre>User: {{ route.params.id }}</pre>

    <fieldset>
      <legend>Controls</legend>

      <button @click="refresh()">Refresh</button>
      <button @click="reload()">Refetch</button>
    </fieldset>

    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 - 1 } }">
      Previous
    </RouterLink>
    |
    <RouterLink :to="{ params: { id: Number(route.params.id) || 0 + 1 } }">
      Next
    </RouterLink>

    <h2>State</h2>

    <p>
      <code>status: {{ status }}</code>
      <br />
      <code>isLoading: {{ isLoading }}</code>
    </p>
    <pre v-if="error">Error: {{ error }}</pre>
    <pre v-else>{{ user == null ? String(user) : user }}</pre>
  </main>
</template>
```

::: tip
You can pass a route name to `defineColadaLoader` to get typed routes in the `query` function.

```ts
export const useUserData = defineColadaLoader('/users/[id]', {
  // ...
})
```

:::

## Refresh by default

To avoid unnecessary frequent refreshes, Pinia Colada refreshes the data when navigating (instead of *refetching*). Change the `staleTime` option to control how often the data should be fetched, e.g. setting it to 0 will fetch the data every time the route changes.

## Route tracking

The `query` function tracks what is used in the `to` parameter and will only refresh the data if **tracked** properties change. This means that if you use `to.params.id` in the `query` function, it will only refetch the data if the `id` parameter changes but not if other properties like `to.query`, `to.hash` or even `to.params.other` change. To make sure the data is updated, it will still refresh in these scenarios. Configure the `staleTime` option to control how often the data should be refreshed.

## SSR

Follow Pinia Colada docs for SSR.

## Nuxt

Use `@pinia/colada-nuxt` plugin and SSR will work out of the box. Hydration won't trigger an extra fetch!

---

---
url: /guide/essentials/active-links.md
---
# Active links

It's common for applications to have a navigation component that renders a list of RouterLink components. Within that list, we might want to style links to the currently active route differently from the others.

The RouterLink component adds two CSS classes to active links, `router-link-active` and `router-link-exact-active`. To understand the difference between them, we first need to consider how Vue Router decides that a link is *active*.

## When are links active?

A RouterLink is considered to be ***active*** if:

1. It matches the same route record (i.e. configured route) as the current location.
2. It has the same values for the `params` as the current location.

If you're using [nested routes](./nested-routes), any links to ancestor routes will also be considered active if the relevant `params` match.

Other route properties, such as the [`query`](../../api/interfaces/RouteLocationBase.html#query), are not taken into account.

The path doesn't necessarily need to be a perfect match. For example, using an [`alias`](./redirect-and-alias#Alias) would still be considered a match, so long as it resolves to the same route record and `params`.

If a route has a [`redirect`](./redirect-and-alias#Redirect), it won't be followed when checking whether a link is active.

## Exact active links

An ***exact*** match does not include ancestor routes.

Let's imagine we have the following routes:

```js
const routes = [
  {
    path: '/user/:username',
    component: User,
    children: [
      {
        path: 'role/:roleId',
        component: Role,
      },
    ],
  },
]
```

Then consider these two links:

```vue-html
<RouterLink to="/user/erina">
  User
</RouterLink>
<RouterLink to="/user/erina/role/admin">
  Role
</RouterLink>
```

If the current location path is `/user/erina/role/admin` then these would both be considered *active*, so the class `router-link-active` would be applied to both links. But only the second link would be considered *exact*, so only that second link would have the class `router-link-exact-active`.

## Configuring the classes

The RouterLink component has two props, `activeClass` and `exactActiveClass`, that can be used to change the names of the classes that are applied:

```vue-html
<RouterLink
  activeClass="border-indigo-500"
  exactActiveClass="border-indigo-700"
  ...
>
```

The default class names can also be changed globally by passing the `linkActiveClass` and `linkExactActiveClass` options to `createRouter()`:

```js
const router = createRouter({
  linkActiveClass: 'border-indigo-500',
  linkExactActiveClass: 'border-indigo-700',
  // ...
})
```

See [Extending RouterLink](../advanced/extending-router-link) for more advanced customization techniques using the `v-slot` API.

---

---
url: /data-loaders/load-cancellation.md
---
# Cancelling a data loader

Data loaders receive an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can be passed to `fetch` and other Web APIs to cancel ongoing requests when the navigation is cancelled. If the navigation is cancelled because of errors or a new navigation, the signal aborts, causing any request using it to abort as well.

```ts twoslash
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(options: {
  signal?: AbortSignal
}): Promise<Book[]> {
  return {} as any
}
// ---cut---
import { defineBasicLoader } from 'vue-router/experimental'
export const useBookCollection = defineBasicLoader(
  async (_route, { signal }) => {
    return fetchBookCollection({ signal })
  }
)
```

This aligns with the future [Navigation API](https://github.com/WICG/navigation-api#navigation-monitoring-and-interception) and other web APIs that use the `AbortSignal` to cancel an ongoing invocation.

## Best practices

Depending on the data loader implementation, it might be more interesting **not** to cancel an ongoing request, for example, when using [Pinia Colada](./colada/), it might be more interesting to keep the request ongoing and cache the result for future navigations. Make sure to read the documentation

---

---
url: /file-based-routing/configuration.md
---
# Configuration

Have a glimpse of all the existing configuration options with their corresponding **default values**:

```ts
import VueRouter from 'vue-router/vite'

VueRouter({
  // how and what folders to scan for files
  routesFolder: [
    {
      src: 'src/pages',
      path: '',
      // override globals
      exclude: excluded => excluded,
      filePatterns: filePatterns => filePatterns,
      extensions: extensions => extensions,
    },
  ],

  // what files should be considered as a pages
  extensions: ['.vue'],

  // what files to include
  filePatterns: ['**/*'],

  // files to exclude from the scan
  exclude: [],

  // where to generate the types
  dts: './typed-router.d.ts',

  // how to generate the route name
  getRouteName: routeNode => getFileBasedRouteName(routeNode),

  // default language for <route> custom blocks
  routeBlockLang: 'json5',

  // how to import routes, can also be a string
  importMode: 'async',

  // where are paths relative to
  root: process.cwd(),

  // options for the path parser
  pathParser: {
    // should `users.[id]` be parsed as `users/:id`?
    dotNesting: true,
  },

  // modify routes individually
  async extendRoute(route) {
    // ...
  },

  // modify routes before writing
  async beforeWriteFiles(rootRoute) {
    // ...
  },
})
```

## SSR

It might be necessary to mark `vue-router` as `noExternal` in your `vite.config.js` in development mode:

```ts{7}
import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import VueRouter from 'vue-router/vite'

export default defineConfig(({ mode }) => ({
  ssr: {
    noExternal: mode === 'development' ? ['vue-router'] : [],
  },
  plugins: [VueRouter(), Vue()],
}))
```

---

---
url: /guide/advanced/data-fetching.md
---
# Data Fetching

Sometimes you need to fetch data from the server when a route is activated. For example, before rendering a user profile, you need to fetch the user's data from the server. We can achieve this in two different ways:

* **Fetching After Navigation**: perform the navigation first, and fetch data in the incoming component's lifecycle hook. Display a loading state while data is being fetched.

* **Fetching Before Navigation**: Fetch data before navigation in the route enter guard, and perform the navigation after data has been fetched.

Technically, both are valid choices - it ultimately depends on the user experience you are aiming for.

## Fetching After Navigation

When using this approach, we navigate and render the incoming component immediately, and fetch data in the component itself. It gives us the opportunity to display a loading state while the data is being fetched over the network, and we can also handle loading differently for each view.

Let's assume we have a `Post` component that needs to fetch the data for a post based on `route.params.id`:

::: code-group

```vue [Composition API]
<template>
  <div class="post">
    <div v-if="loading" class="loading">Loading...</div>

    <div v-if="error" class="error">{{ error }}</div>

    <div v-if="post" class="content">
      <h2>{{ post.title }}</h2>
      <p>{{ post.body }}</p>
    </div>
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'
import { useRoute } from 'vue-router'
import { getPost } from './api.js'

const route = useRoute()

const loading = ref(false)
const post = ref(null)
const error = ref(null)

// watch the params of the route to fetch the data again
watch(() => route.params.id, fetchData, { immediate: true })

async function fetchData(id) {
  error.value = post.value = null
  loading.value = true

  try {
    // replace `getPost` with your data fetching util / API wrapper
    post.value = await getPost(id)
  } catch (err) {
    error.value = err.toString()
  } finally {
    loading.value = false
  }
}
</script>
```

```vue [Options API]
<template>
  <div class="post">
    <div v-if="loading" class="loading">Loading...</div>

    <div v-if="error" class="error">{{ error }}</div>

    <div v-if="post" class="content">
      <h2>{{ post.title }}</h2>
      <p>{{ post.body }}</p>
    </div>
  </div>
</template>

<script>
import { getPost } from './api.js'

export default {
  data() {
    return {
      loading: false,
      post: null,
      error: null,
    }
  },
  created() {
    // watch the params of the route to fetch the data again
    this.$watch(
      () => this.$route.params.id,
      this.fetchData,
      // fetch the data when the view is created and the data is
      // already being observed
      { immediate: true }
    )
  },
  methods: {
    async fetchData(id) {
      this.error = this.post = null
      this.loading = true

      try {
        // replace `getPost` with your data fetching util / API wrapper
        this.post = await getPost(id)
      } catch (err) {
        this.error = err.toString()
      } finally {
        this.loading = false
      }
    },
  },
}
</script>
```

:::

## Fetching Before Navigation

With this approach we fetch the data before actually navigating to the new route. We can perform the data fetching in the `beforeRouteEnter` guard in the incoming component, and only call `next` when the fetch is complete. The callback passed to `next` will be called **after the component is mounted**:

```js
export default {
  data() {
    return {
      post: null,
      error: null,
    }
  },
  async beforeRouteEnter(to, from, next) {
    try {
      const post = await getPost(to.params.id)
      // `setPost` is a method defined below
      next(vm => vm.setPost(post))
    } catch (err) {
      // `setError` is a method defined below
      next(vm => vm.setError(err))
    }
  },
  // when route changes and this component is already rendered,
  // the logic will be slightly different.
  beforeRouteUpdate(to, from) {
    this.post = null
    getPost(to.params.id).then(this.setPost).catch(this.setError)
  },
  methods: {
    setPost(post) {
      this.post = post
    },
    setError(err) {
      this.error = err.toString()
    },
  },
}
```

The user will stay on the previous view while the resource is being fetched for the incoming view. It is therefore recommended to display a progress bar or some kind of indicator while the data is being fetched. If the data fetch fails, it's also necessary to display some kind of global warning message.

---

---
url: /data-loaders.md
---
# Data Loaders

Data loaders streamline any asynchronous state management with Vue Router, like **Data Fetching**. Adopting Data loaders ensures a consistent and efficient way to manage data fetching in your application. Keep all the benefits of using libraries like [Pinia Colada](./colada/) and integrate them seamlessly with client-side navigation.

This is achieved by extracting the loading logic **outside** of the component `setup` (unlike `<Suspense>`). This way, the loading logic can be executed independently of the component life cycle, and the component can focus on rendering the data. Data Loaders are automatically collected and awaited within a navigation guard, ensuring the data is ready before rendering the component.

## Features

* Parallel data fetching and deduplication
* Automatic loading state management
* Error handling
* Extensible by loader implementations
* SSR support
* Prefetching data support

## Installation

Install the `DataLoaderPlugin` **before the `router`**.

```ts{12-15} twoslash
// @errors: 2769 2345
import { createApp } from 'vue'
import { routes } from 'vue-router/auto-routes'
import { createRouter, createWebHistory } from 'vue-router'
import { DataLoaderPlugin } from 'vue-router/experimental' // [!code ++]

const router = createRouter({
  history: createWebHistory(),
  routes,
})

const app = createApp({})
// Register the plugin before the router
app.use(DataLoaderPlugin, { router }) // [!code ++]
// adding the router will trigger the initial navigation
app.use(router)
app.mount('#app')
```

## Quick start

There are different data loader implementations. The simplest one is the [Basic Loader](./basic/) which always reruns data fetching. A more efficient one is the [Colada Loader](./colada/) which uses [@pinia/colada](https://github.com/posva/pinia-colada) under the hood. In the following examples, we will be using the *basic loader*.

Loaders are [composables](https://vuejs.org/guide/reusability/composables.html) defined through a `defineLoader` function like `defineBasicLoader` or `defineColadaLoader`. They are *used* in the component `setup` to extract the needed information.

To get started, *define* and ***export*** a loader from a **page** component:

::: code-group

```vue{2,5-7,11-16} twoslash [src/pages/users/[id].vue]
<script lang="ts">
import 'vue-router/auto-routes'
// @errors: 2339
// ---cut---
import { defineBasicLoader } from 'vue-router/experimental'
import { getUserById } from '../api'

export const useUserData = defineBasicLoader('/users/[id]', async (route) => {
  return getUserById(route.params.id)
})
</script>

<script setup lang="ts">
const {
  data: user, // the data returned by the loader
  isLoading, // a boolean indicating if the loader is fetching data
  error, // an error object if the loader failed
  reload, // a function to refetch the data without navigating
} = useUserData()
</script>

<template>
  <main>
    <p v-if="isLoading">Loading...</p>
    <template v-else-if="error">
      <p>{{ error.message }}</p>
      <button @click="reload()">Retry</button>
    </template>
    <template v-else>
      <p>{{ user }}</p>
    </template>
  </main>
</template>
```

:::

The loader will automatically run when the route changes, for example when navigating to `/users/1`, even when coming from `/users/2`, the loader will fetch the data and delay the navigation until the data is ready.

On top of that, you are free to *reuse* the returned composable `useUserData` in any other component, and it will automatically share the same data fetching instance. You can even [organize your loaders in separate files](./organization.md) as long as you **export** the loader from a **page** component.

## Why Data Loaders?

Data fetching is the most common need for a web application. There are many ways of handling data fetching, and they all have their pros and cons. Data loaders are a way to streamline data fetching in your application. Instead of forcing you to choose between different libraries, data loaders provide a consistent way to manage data fetching in your application no matter the underlying library or strategy you use.

---

---
url: /data-loaders/rfc.md
---

# Data Loaders

* Start Date: 2022-07-14
* Target Major Version: Vue 3, Vue Router 4
* Reference Issues: -
* [Discussion](https://github.com/vuejs/rfcs/discussions/460)
* [Implementation PR](https://github.com/posva/unplugin-vue-router/tree/main/src/data-loaders)

## Todo List

List of things that haven't been added to the document yet:

* \[ ] Extendable API for data fetching libraries like vue-apollo, vuefire, vue-query, etc
* \[ ] Warn if a non lazy loader is used without data: meaning it was used in a component without it being exported by a page component. Either make it lazy or export it

## Summary

There is no silver bullet to data fetching because of the different data fetching strategies and how they can define the architecture of the application and its UX. However, I think it's possible to find a solution that is flexible enough to **promote good practices** and **reduce the complexity** of data fetching in applications.
That is the goal of this RFC, to standardize and improve data fetching with vue-router:

* Integrate data fetching to the navigation cycle
  * Blocks navigation while fetching or *defer* less important data (known as *lazy* in Nuxt)
* Deduplicate requests
* Delay data updates until all data loaders are resolved
  * Avoids displaying partially up-to-date data and inconsistent state
  * Configurable through a `commit` option
* Optimal data fetching
  * Defaults to parallel fetching
  * Semantic sequential fetching if needed
* Avoid `<Suspense>`
  * No cascading loading states
  * No double mounting
  * [more...](#suspense)
* Provide atomic and global access to loading/error states
* Allow 3rd party libraries to extend the loaders functionality by establish a set of Interfaces that can be implemented. This targets libraries like [VueFire](https://vuefire.vuejs.org), [@pinia/colada][pinia-colada], [vue-apollo](https://apollo.vuejs.org/), [@tanstack/vue-query][vue-query], etc to provide features like caching, pagination, etc. specific to their use cases.

This proposal concerns Vue Router 4 and is implemented under [unplugin-vue-router][uvr]. This enables types in data loaders but **is not necessary**. This feature is independent of the rest of the plugin and can be used without it, namely **without file-based routing**.

::: tip
In this RFC, data loaders are often referred as *loaders* for short. API names also use the word *loader* instead of *data loader* for brevity.

💡 Some of the examples are interactive: hover or tap on the code to see the types and other information.
:::

## Basic example

We create data loaders with a `defineLoader()` function that returns a **composable that can be used in any component** (not only pages component).

The loader is then picked up by a Navigation Guard. It can be attached to a page component in two ways:

* Export the loader from the page component it is attached to. It must be lazy loaded (`() => import('~/pages/users-details.vue')`)
* Manually add the loader to the route definition's `meta.loaders[]`

Exported from a non-setup `<script>` in a page component:

```vue twoslash
<script lang="ts">
// ---cut-start---
import { defineComponent } from 'vue'
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
// ---cut-end---
// @moduleResolution: bundler
import { getUserById } from '../api'

// name the loader however you want **and export it**
export const useUserData = defineLoader(async route => {
  const user = await getUserById(route.params.id as string)
  // ...
  // return anything you want to expose
  return user
})

// Optional: define other component options
export default defineComponent({
  name: 'custom-name',
  inheritAttrs: false,
})
</script>

<script lang="ts" setup>
// find the user as `data` and some other properties
const { data: user, isLoading, error, reload } = useUserData()
// data is always present, isLoading changes when going from '/users/2' to '/users/3'
</script>
```

When a loader is exported by the page component, it is **automatically** picked up as long as the route is **lazy loaded** (which is a best practice). If the route isn't lazy loaded, the loader can be directly defined in an array of data loaders on `meta.loaders`:

```ts twoslash
import './shims-vue.d'
// ---cut---
// @moduleResolution: bundler
import { createRouter, createWebHistory } from 'vue-router'
import UserList from './pages/UserList.vue'
// could be anywhere
import { useUserList, useUserData, type User } from './loaders/users'

export const router = createRouter({
  history: createWebHistory(),
  routes: [
    {
      path: '/users',
      component: UserList,
      meta: {
        // Required when the component is not lazy loaded
        loaders: [useUserList],
      },
    },
    {
      path: '/users/:id',
      // automatically picks up all exported loaders
      component: () => import('./pages/UserDetails.vue'),
    },
  ],
})
```

Regarding the returned values from `useUserData()`:

* `data` (aliased to `user`), `isLoading`, and `error` are shallow ref and therefore reactive.
* `reload` is a function that can be called to force a reload of the data without a new navigation.

Note `useUserData()` can be used in **any component**, not only in the page component: just import the function and call it within `<script setup>` like other composables

By default, **data loaders block the navigation**, meaning they *just work* with SSR and errors are propagated to the router level (`router.onError()`). On top of that, data loads are deduplicated, which means that no mather how many page components use the same loader (e.g. nested pages), **it will still load the data just once per navigation**.

The simplest of data loaders can be defined in just one line and types will be automatically inferred:

```ts twoslash
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useBookCollection = defineLoader(fetchBookCollection)
const { data } = useBookCollection()
```

Note that this syntax will intentionally be avoided in the RFC. Instead, we will often use slightly longer examples to make things easier to follow.

## Motivation

There are currently too many ways of handling data fetching with vue-router and all of them have problems:

* With navigation guards:
  * using `onBeforeRouteUpdate()`: only works on subsequent navigations. Cannot be properly combined with `beforeRouteEnter()`.
  * using `beforeRouteEnter()`: non typed and non-ergonomic API with `next()`, requires a data store (pinia, vuex, apollo, etc), does not exist in script setup
  * using `meta`: complex to setup even for simple cases, too low level for such a common case
* using a watcher on `route.params...`: component renders without the data (doesn't work with SSR)
* Using Suspense and *awaiting* data within page components
  * Cascading (slow) async states
  * Only loads once (on mounting)
  * Does not wait for navigation (or requires double mounting: pending + current view)
  * Requires handling UI loading state
  * [And more](#suspense)

People are left with a low level API (navigation guards) to handle data fetching themselves. This is often a difficult problem to solve because it requires an extensive knowledge of the Router concepts and in reality, very few people know them. This leads to incomplete implementations that don't handle all the edge cases and don't provide a good user experience.

Thus, the goal of this proposal is to provide a simple yet extendable way of defining data loading in your application that is easy to understand and use. It should also be compatible with SSR and not limited to simple *fetch calls*, but rather any async state. It should be adoptable by frameworks like Nuxt.js to provide an augmented data fetching layer that integrates well with Vue.js concepts and the future of Web APIs like the [Navigation API](https://github.com/WICG/navigation-api/).

## Detailed design

The design of Data Loaders is split into two parts

* [Implementations](#implementations)
  * A bare-bone data loader
  * A more advanced data loader with client side caching using [@pinia/colada][pinia-colada]
* The set of [Interfaces (types)](#interfaces) that define a Data Loader (WIP)

::: tip
You might only be interested in trying out Data Loaders. In that case, check out the [implementations](#implementations) section for instructions on how to use this. It's still recommended to read the rest of the RFC to understand what to expect from Data Loaders.
:::

### Data Loader Setup

`DataLoaderPlugin` adds the [navigation guard](#the-navigation-guard) that handles the data loaders. It requires access to the router instance to attach the navigation guard as well as some other options:

* `router`: The Vue Router instance.
* `selectNavigationResult` (optional): Called wih an array of `NavigationResult` returned by loaders. It allows to decide the *fate* of the navigation that was modified by loaders. See [NavigationResult](#handling-multiple-navigation-results)

```ts{2,9}
import { createApp } from 'vue'
import { createRouter } from 'vue-router'
import { DataLoaderPlugin } from 'vue-router/experimental'

const router = createRouter({
  // ...
})

const app = createApp(App)
app.use(DataLoaderPlugin, { router })
// add the router after the DataLoaderPlugin
app.use(router)
```

It's important to add the `DataLoaderPlugin` before the router to ensure the navigation guards are attached before the router initiates the first navigation.

### Core Data Loader features

These are the core features of the Data Loader API that every data loader should implement. Throughout the RFC, we will use a **non-existent**, **generic** `defineLoader()`. This is a placeholder for the actual name of the function, e.g. [`defineBasicLoader()`](./basic/), [`defineColadaLoader()`](./colada/), etc. In practice, one can globally alias the function to `defineLoader` with [unplugin-auto-import](https://github.com/unplugin/unplugin-auto-import).

Data Loaders should be able to load data based **solely on the URL**. This ensures that the page can be shared and that the rendering is consistent between the server and the client.

#### `defineLoader()` signature

Data Loaders must accept an optional first parameter to type the route:

```ts twoslash
import 'vue-router/auto-routes'
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
// ---cut---
import { getUserById } from '../api'

export const useUserData = defineLoader('/users/[id]', async route => {
  return getUserById(route.params.id)
})
```

The rest of the parameters are up to the implementation of the loader but they should accept [extra options](#defineloader-options).

Within loaders there is no access to the current component or page instance, but it's possible to access global injections created with `app.provide()`. This includes stores created with [Pinia](https://pinia.vuejs.org).

#### Returned Composables

Data Loaders are composables that return a set of properties:

```ts twoslash
import 'vue-router/auto-routes'
import { useUserData } from './loaders/users'
// ---cut---
const {
  // hover over each property to see the type
  data,
  isLoading,
  error,
  reload,
} = useUserData()
```

* `data` contains the resolved value returned by the loader. It's a shallow ref to be more performant, especially with large data-sets
* `isLoading` is `true` while a request is isLoading and becomes `false` once the request is settled
* `error` contains any error thrown by the loader. It's also a shallow ref
* `reload()` reruns the loader outside of a navigation

In practice, rename `data` (or others) to something more meaningful:

```ts twoslash
import 'vue-router/auto-routes'
import { useUserData } from './loaders/users'
// ---cut---
const { data: user } = useUserData()
```

#### `defineLoader()` options

* `lazy`: By default, loaders block the navigation. This means that the navigation is only allowed to continue once all loaders are resolved. Lazy loaders **do not block the navigation**. `data`, `error` and other properties might be updated after the navigation finishes. Setting this to `true` is useful for non-critical data fetching and will change the type of the returned `data` to `ShallowRef<T | undefined>`:

  ```ts twoslash
  import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
  interface Book {
    title: string
    isbn: string
    description: string
  }
  function fetchBookCollection(): Promise<Book[]> {
    return {} as any
  }
  // ---cut---
  export const useBookCollection = defineLoader(fetchBookCollection, {
    lazy: true,
  })
  const { data: bookCollection } = useBookCollection()
  //            ^ can be undefined
  ```

* `commit`: Controls when the async state is reflected in `data` and `error`. You can choose to immediately reflect the state of the loader or
  delay the update of the data until all loaders are resolved (default). The latter is useful to avoid displaying partially up-to-date data and inconsistent state.

  ```ts twoslash
  import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
  interface Book {
    title: string
    isbn: string
    description: string
  }
  function fetchBookCollection(): Promise<Book[]> {
    return {} as any
  }
  // ---cut---
  export const useBookCollection = defineLoader(fetchBookCollection, {
    commit: 'immediate',
  })
  ```

  A lazy loader can use `commit: 'after-load'` but since it's not awaited during the navigation, it might be reflected **after the navigation**.

* `server`: By default, loaders are executed on both, client, and server. Setting this to false will skip its execution on the server. Like `lazy: true`, this also changes the type of the returned `data` to `ShallowRef<T | undefined>`:

  ```ts twoslash
  import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
  interface Book {
    title: string
    isbn: string
    description: string
  }
  function fetchBookCollection(): Promise<Book[]> {
    return {} as any
  }
  // ---cut---
  export const useBookCollection = defineLoader(fetchBookCollection, {
    server: false,
  })
  ```

Each custom implementation can augment the returned properties with more information. For example, [Pinia Colada](./colada/) adds `refresh()`, `status` and other properties specific to its features.

#### Parallel Fetching

By default, loaders are executed as soon as possible, in parallel. This scenario works well for most use cases where data fetching only requires route params/query params or nothing at all.

#### Sequential fetching

Sometimes, requests depend on other fetched data (e.g. fetching additional user information). For these scenarios, we can simply import the other loaders and use them **within a different loader**:

Call **and `await`** the loader inside the one that needs it, it will only be fetched once no matter how many times it is called during a navigation:

```ts twoslash
import 'vue-router/auto-routes'
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
// ---cut---
// import the loader for user information
import { useUserData } from './loaders/users'
import { getCommonFriends, getCurrentUser } from './api'

export const useUserCommonFriends = defineLoader(async route => {
  // loaders must be awaited inside other loaders
  // .        ⤵
  const user = await useUserData() // magically works
  const me = await getCurrentUser()

  // fetch other data
  const commonFriends = await getCommonFriends(me.id, user.id)
  return { ...user, commonFriends }
})
```

You will notice here that we have two different usages for `useUserData()`:

* One that returns all the necessary information we need *synchronously* (not used here). This is the composable that we use in components
* A second version that **only returns a promise of the data**. This is the version used within data loaders that enables sequential fetching.

::: danger
`useUserData()` expects the route to have an `id` param to fetch the current user. We could maybe allow passing the route as a parameter to ensure the type safety as well to further differentiate the two usages (and their type).
:::

##### Nested invalidation

Since `useUserCommonFriends()` loader calls `useUserData()`, if `useUserData()` is somehow *invalidated*, it will also automatically invalidate `useUserCommonFriends()`. This depends on the implementation of the loader and is not a requirement of the API.

::: warning
Two loaders cannot use each other as that would create a *dead lock*.
:::

This can get complex with multiple pages exposing the same loader and other pages using some of their *already exported* loaders within other loaders. But it's not an issue, **the user shouldn't need to handle anything differently**, loaders are still only called once:

```ts twoslash
import 'vue-router/auto-routes'
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
// ---cut---
import {
  getFriends,
  getCommonFriends,
  getUserById,
  getCurrentUser,
} from './api'

export const useUserData = defineLoader('/users/[id]', async route => {
  return getUserById(route.params.id)
})

export const useCurrentUserData = defineLoader('/users/[id]', async route => {
  const me = await getCurrentUser()
  // imagine legacy APIs that cannot be grouped into one single fetch
  const friends = await getFriends(me.id)

  return { ...me, friends }
})

export const useUserCommonFriends = defineLoader('/users/[id]', async route => {
  const user = await useUserData()
  const me = await useCurrentUserData()

  const friends = await getCommonFriends(user.id, me.id)
  return { ...me, commonFriends: { with: user, friends } }
})
```

In the example above we are exporting multiple loaders but we don't need to care about the order in which they are called nor try optimizing them because **they are only called once and share the data**.

::: danger
**Caveat**: must call **and await** all nested loaders at the top of the parent loader (see `useUserData()` and `useCurrentUserData()`). You cannot put a different regular `await` in between. If you really need to await **anything that isn't a loader** in between, wrap the promise with `withDataContext()` to ensure the loader context is properly restored:

```ts{3}
export const useUserCommonFriends = defineLoader(async (route) => {
  const user = await useUserData()
  await withContext(functionThatReturnsAPromise())
  const me = await useCurrentUserData()

  // ...
})
```

This allows nested loaders to be aware of their *parent loader*. This could probably be linted with an eslint plugin. It is similar to the problem `<script setup>` had before introducing the automatic `withAsyncContext()`. The same feature could be introduced (via a vite plugin) but will also have a performance cost. In the future, this *should* be solved with the [async-context](https://github.com/tc39/proposal-async-context) proposal (stage 2).
:::

#### Cache&#x20;

::: warning
This part has been removed from the core features of the API. It's now part of custom implementations like [Pinia Colada](./colada/).
:::

#### Smart Refreshing

This is not a requirement of the API.

When navigating, depending on the loader, the data is refreshed **automatically based on what params, query params, and hash** are used within the loader.

e.g. using [Pinia Colada](./colada/), given this loader in page `/users/:id`:

```ts
export const useUserData = defineColadaLoader(async route => {
  const user = await getUserById(route.params.id)
  return user
})
```

Going from `/users/1` to `/users/2` will reload the data but going from `/users/2` to `/users/2#projects` will not unless the cache expires or is manually invalidated (known as *refresh*).

#### Deduplication

Loaders also have the advantage of behaving as singleton requests. This means that they are only fetched once per navigation no matter how many times the loader is attached or how many regular components use it. It also means that all the refs (`data`, `isLoading`, etc) are created only once and shared by all components, reducing memory usage.

#### SSR

Each Data Loader implementation is responsible for providing a way to serialize the data loaded on the server and pass it to the client. This is a requirement for SSR to work properly.

Different implementations could have different kind of keys. The simplest form is a string:

```ts
export const useBookCollection = defineLoader(
  async () => {
    const books = await fetchBookCollection()
    return books
  },
  { key: 'bookCollection' }
)
```

##### Avoiding double fetch on the client

One of the advantages of having an initial state is that we can avoid fetching on the client. Data Loaders can implement a mechanism to skip fetching on the client if the initial state is provided ([Pinia Colada](./colada/) implements this). This means nested loaders **aren't executed either**. Since data loaders shouldn't contain side effects besides data fetching, this shouldn't be a problem.

### The Navigation Guard

The bulk of the logic of data loaders is handled with navigation guards:

* one `router.beforeEach()` to collect loaders from lazy loaded components
* one `router.beforeResolve()` (triggers after other guards) to execute the loaders

`router.afterEach()` and `router.onError()` are also used to handle errors and cleanup.

Handling the data loading in a navigation guards has the following advantages:

* Ensure data is present before mounting the component
* Flexibility to not wait for non critical data with lazy data loaders
* Enables the UX pattern of letting the browser handle loading state (aligns with [future Navigation API](https://github.com/WICG/navigation-api))
* Makes scrolling work out of the box when navigating between pages (when data loaders are blocking)
* Ensure one single request per loader and navigation
* Allows controlling the navigation (aborting, redirecting, etc)

#### Controlling the navigation

Since the data fetching happens within a navigation guard, it's possible to control the navigation like in regular navigation guards:

* Thrown errors (or rejected Promises) cancel the navigation (same behavior as in a regular navigation guard) and are intercepted by [Vue Router's error handling](https://router.vuejs.org/api/interfaces/router.html#onerror)
* Redirection: `return new NavigationResult(targetLocation)` -> like `return targetLocation` in a regular navigation guard
* Cancelling the navigation: `return new NavigationResult(false)` like `return false` in a regular navigation guard
* Any other returned value is considered as the *resolved data*

```ts{1,11,14}
import { NavigationResult } from 'vue-router'

export const useUserData = defineLoader(
  async (to) => {
    try {
      const user = await getUserById(to.params.id)

      return user
    } catch (error) {
      if (error.status === 404) {
        return new NavigationResult({ name: 'not-found', params: { pathMatch: '' } }
        )
      } else {
        throw error // aborts the vue router navigation
      }
    }
  }
)
```

`new NavigationResult()` accepts as its only argument anything that [can be returned in a navigation guard](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) to alter the navigation. e.g. it doesn't accept `true` or `undefined` as these do not modify the navigation.

Some alternatives:

::: details

* `createNavigationResult()`: too verbose
* `NavigationResult()` (no `new`): `NavigationResult` is not a primitive so it should use `new`
* Accept a second argument for extra custom context that can be retrieved in `selectNavigationResult()`

:::

::: tip

Throwing an error does not trigger the `selectNavigationResult()` method. Instead, it immediately cancels the navigation and triggers the `router.onError()` method, just like in a regular navigation guard.

:::

#### Handling multiple navigation results

Since navigation loaders can run in parallel, they can return different navigation results as well. In this case, you can decide which result should be used by providing a `selectNavigationResult()` method to [`DataLoaderPlugin`](#data-loader-setup):

```ts{3-6} twoslash
import 'vue-router/auto-routes'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { DataLoaderPlugin } from 'vue-router/experimental'
const app = createApp({})
const router = createRouter({
  history: createWebHistory(),
  routes: [],
})
// ---cut---
// @moduleResolution: bundler
// @noErrors
app.use(DataLoaderPlugin, {
  router,
  selectNavigationResult(results) {
    for (const { value } of results) {
      if (
        typeof value === 'object' &&
        'name' in value &&
        value.name === 'not-found'
      ) {
        return value
      }
    }
  },
})
```

`selectNavigationResult()` is called with an array of all the returned `new NavigationResult(value)` **after all data loaders** have been resolved. **If any of them throws an error** or if none of them return a `NavigationResult`, `selectNavigationResult()` isn't called.

By default, `selectNavigation` returns the first value of the array.

#### Eagerly changing the navigation

If a loader wants to eagerly alter the navigation, it can `throw` the `NavigationResult` instead of returning it. This skips the `selectNavigationResult()` and take precedence without triggering `router.onError()`.

```ts{10-15}
import { NavigationResult } from 'vue-router/experimental'

export const useUserData = defineLoader(
  async (to) => {
    try {
      const user = await getUserById(to.params.id)

      return user
    } catch (error) {
      throw new NavigationResult({
        name: 'not-found',
        params: { pathMatch: to.path.split('/') },
        query: to.query,
        hash: to.hash,
      })
    }
  }
)
```

::: info

When using vue router named views, each named view can have their own loaders but note any navigation to the route will trigger **all loaders from all page components**. This is because the router doesn't know which named views will be used.

:::

### Advanced Error handling

Since throwing an error in a loader cancels the navigation, this doesn't allow to have an error property in *non lazy loaders* to display the error in the UI. To solve this, we can specify expected errors when defining the loader:

```ts{2-9,16}
// custom error class
class MyError extends Error {
  // override is only needed in TS
  override name = 'MyError' // Displays in logs instead of 'Error'
  // defining a constructor is optional
  constructor(message: string) {
    super(message)
  }
}

export const useUserData = defineLoader(
  async (to) => {
    // ...
  },
  {
    errors: [MyError],
  }
)
```

These can also be specified globally:

```ts{11-13}
class MyError extends Error {
  name = 'MyError'
  constructor(message: string) {
    super(message)
  }
}

app.use(DataLoaderPlugin, {
  router,
// checks with `instanceof MyError`
  errors: [MyError],
})
```

::: tip

In a lazy loader, you can throw an error and since it doesn't block the navigation it will **always** appear in the `error` property. Defining an `errors` property won't change anything.

:::

### Usage outside of page components

Loaders can be attached to a page even if the page component doesn't use it (invoke the composable returned by `defineLoader()`). This is possible if a nested component uses the data. It can be used in any component by importing the *returned composable*, even outside of the scope of the page components, even by a parent.

On top of that, loaders can be **defined anywhere** and imported where using the data makes sense. This allows to define loaders in a separate `src/loaders` folder and reuse them across pages:

```ts
// src/loaders/user.ts
export const useUserData = defineLoader(...)
// ...
```

Then, in a page component, export it:

```vue
<!-- src/pages/users/[id].vue -->
<script>
export { useUserData } from '~/loaders/user.ts'
</script>
<script setup>
// ...
</script>
```

The page component might not even use `useUserData()` but we can still use it anywhere else:

```vue
<!-- src/components/NavBar.vue -->
<script setup>
import { useUserData } from '~/loaders/user.ts'

const { data: user } = useUserData()
</script>
```

::: warning
If you use a loader in a component while it wasn't exported by a page, it won't be awaited during navigation. This can lead to unexpected behavior but it can be caught during development with a warning.
:::

### TypeScript

Types are automatically generated for the routes by [unplugin-vue-router][uvr] and can be referenced with the name of each route to hint `defineLoader()` the possible values of the current types. On top of that, `defineLoader()` infers the returned types:

```vue twoslash
<script lang="ts">
// ---cut-start---
import 'vue-router/auto-routes'
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
// ---cut-end---
import { getUserById } from '../api'

export const useUserData = defineLoader('/users/[id]', async route => {
  //                                                ^|

  //
  const user = await getUserById(route.params.id)
  //                                          ^|
  // ...
  return user
})
</script>

<script lang="ts" setup>
const { data: user, isLoading, error } = useUserData()
//            ^?
//            👆 hover or tap
</script>
```

The arguments can be removed during the compilation step in production mode since they are only used for types and are ignored at runtime.

### Non blocking data fetching (Lazy Loaders)

Also known as [lazy async data in Nuxt](https://v3.nuxtjs.org/api/composables/use-async-data), loaders can be marked as lazy to **not block the navigation**.

```vue{10,16-17} twoslash
<script lang="ts">
// ---cut-start---
import 'vue-router/auto-routes'
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
// ---cut-end---
import { getUserById } from '../api'

export const useUserData = defineLoader(
  '/users/[id]',
  async (route) => {
    const user = await getUserById(route.params.id)
    return user
  },
  { lazy: true } // 👈  marked as lazy
)
</script>

<script setup>
// Differently from the example above, `user.value` can and will be initially `undefined`
const { data: user, isLoading, error } = useUserData()
//            ^?
//            👆 hover or tap
</script>
```

This patterns is useful to avoid blocking the navigation while *non critical data* is being fetched. It will display the page earlier while some of the parts of it are still loading and you are able to display loader indicators thanks to the `isLoading` property.

Note this still allows for having different behavior during SSR and client side navigation, e.g.: if we want to wait for the loader during SSR but not during client side navigation:

```ts{6-7}
export const useUserData = defineLoader(
  async (route) => {
    // ...
  },
  {
    lazy: !import.env.SSR, // Vite
    lazy: process.client, // NuxtJS
  }
)
```

Existing questions:

* [~~Should it be possible to await all pending loaders with `await allPendingLoaders()`? Is it useful for SSR? Otherwise we could always ignore lazy loaders in SSR. Do we need both? Do we need to selectively await some of them?~~](https://github.com/vuejs/rfcs/discussions/460#discussioncomment-3532011)
* Should we be able to transform a loader into a lazy version of it: `const useUserDataLazy = asLazyLoader(useUserData)`

### AbortSignal

The loader receives in a second argument access to an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can be passed on to `fetch` and other Web APIs. If the navigation is cancelled because of errors or a new navigation, the signal aborts, causing any request using it to abort as well.

```ts twoslash
import { defineBasicLoader as defineLoader } from 'vue-router/experimental'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(options: {
  signal?: AbortSignal
}): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useBookCollection = defineLoader(async (_route, { signal }) => {
  return fetchBookCollection({ signal })
})
```

This aligns with the future [Navigation API](https://github.com/WICG/navigation-api#navigation-monitoring-and-interception) and other web APIs that use the `AbortSignal` to cancel an ongoing invocation.

### Implementations

### Interfaces

Defining a minimal set of information and options for Data Loaders is what enables external libraries to implement their own data loaders. They are meant to extend these interfaces to add more features that are specific to them. You can see a practical example with the [Pinia Colada](./colada/) implementation.

::: danger
This section is still a work in progress, see the [implementations](#implementations) instead.
:::

### Global API

It's possible to access a global state of when data loaders are fetching (during navigation or when `reload()` is called) as well as when the data fetching navigation guard is running (only when navigating).

* `isFetchingData: Ref<boolean>`: is any loader currently fetching data? e.g. calling the `reload()` method of a loader
* `isNavigationFetching: Ref<boolean>`: is navigation being hold by a loader? (implies `isFetchingData.value === true`). Calling the `reload()` method of a loader doesn't change this.

TBD: is this worth it? Are any other functions needed?

### Limitations

* \~~Injections (`inject`/`provide`) cannot be used within a loader~~ They can now
* Watchers and other composables shouldn't be used within data loaders:
  * if `await` is used before calling a composable e.g. `watch()`, the scope **is not guaranteed**
  * In practice, **this shouldn't be a problem** because there is **no need** to create composables within a loader

## Drawbacks

* At first, it looks less intuitive than just awaiting something inside `setup()` with `<Suspense>` [but it doesn't have its limitations](#suspense) and have many more features
* Requires an extra `<script>` tag but only for page components. A macro `definePageLoader()`/`defineLoader()` could be error-prone as it's very tempting to use reactive state declared within the component's `<script setup>` but that's not possible as the loader must be created outside of its `setup()` function

## Alternatives

### Suspense

Using Suspense is probably the first alternative that comes to mind and it has been considered as a solution for data fetching by implementing proofs of concepts. It however suffers from major drawbacks that are tied to its current design and is not a viable solution for data fetching.

One could imagine being able to write something like:

```vue
<!-- src/pages/users.vue = /users -->
<!-- Displays a list of all users -->
<script setup>
const userList = shallowRef(await fetchUserList())

// manually expose a reload function to be called whenever needed
function reload() {
  userList.value = await fetchUserList()
}
</script>
```

Or when params are involved in the data fetching:

```vue
<!-- src/pages/users.[id].vue = /users/:id -->
<!-- Displays a list of all users -->
<script setup>
const route = useRoute()
const user = shallowRef(await fetchUserData(route.params.id))

// manually expose a reload function to be called whenever needed
function reload() {
  user.value = await fetchUserData(route.params.id)
}

// hook into navigation instead of a watcher because we want to block the navigation
onBeforeRouteUpdate(async (to) => {
  // note how we need to use `to` and not `route` here
  user.value = await fetchUserData(to.params.id)
})
</script>
```

This setup has many limitations:

* Nested routes will force **sequential data fetching**: it's not possible to ensure an **optimal parallel fetching**

* Manual data refreshing is necessary **unless you add a `key` attribute** to the `<RouterView>` which will force a remount of the component on navigation. This is not ideal because it will remount the component on every navigation, even when the data is the same. It's necessary if you want to do a `<transition>` but less flexible than the proposed solution which also works with a `key` if needed.

* By putting the fetching logic within the `setup()` of the component we face other issues:
  * No abstraction of the fetching logic => **code duplication** when fetching the same data in multiple components
  * No native way to deduplicate requests among multiple components using them: it requires using a store and extra logic to skip redundant fetches when multiple components are using the same data
  * Does not block the navigation
    * We can block it by mounting the upcoming page component (while the navigation is still blocked by the data loader navigation guard) which can be **expensive in terms of rendering and memory** as we still need to render the old page while we ***try** to mount the new page*.
  * Cannot modify the output of the navigation (e.g. redirecting, cancelling, etc), if the fetching fails, we end up in an error state

* No native way of caching data, even for very simple cases (e.g. no refetching when fast traveling back and forward through browser UI)

* Not possible to precisely read (or write) the loading state (see [vuejs/core#1347](https://github.com/vuejs/core/issues/1347)])

On top of this it's important to note that this RFC doesn't limit you: you can still use Suspense for data fetching or other async state or even use both, **this API is completely tree shakable** and doesn't add any runtime overhead if you don't use it. Aligning with the progressive enhancement nature of Vue.js.

### Other alternatives

* Allowing blocking data loaders to return objects of properties:

  ::: details

  ```ts
  export const useUserData = defineLoader(async route => {
    const user = await getUserById(route.params.id)
    // instead of return user
    return { user }
  })
  // instead of const { data: user } = useUserData()
  const { user } = useUserData()
  ```

  This was the initial proposal but since this is not possible with lazy loaders it was more complex and less intuitive. Having one single version is overall easier to handle. It does allow to return pending promises in the object that aren't awaited:

  ```ts
    export const useUserData = defineLoader(async (route) => {
    return {
      // awaited
      user: await getUserById(route.params.id)
      // not awaited, like lazy
      nonCriticalData: getNonCriticalData() // Promise<...>
    }
  })
  ```

  But this version overlaps with `lazy: true`. While semantically it would be more natural if it was defined with **one** loader, it limits the API to one loader per page and not being able to reuse the data, loading state, error, etc across pages and components, which also limits the extensibility.

  :::

* Adding a new `<script loader>` similar to `<script setup>`:

  ::: details

  ```vue
  <script lang="ts" loader="useUserData">
  import { getUserById } from '~/api/users'
  import { useRoute } from 'vue-router' // could be automatically imported

  const route = useRoute()
  // any variable created here is available in useLoader()
  const user = await getUserById(route.params.id)
  </script>

  <script lang="ts" setup>
  const { user, isLoading, error } = useUserData()
  </script>
  ```

  Too magical without clear benefit.

  :::

* Pass route properties instead of the whole `route` object:

  ::: details

  ```ts
  import { getUserById } from '../api'

  export const useUserData = defineLoader(async ({ params }) => {
    const user = await getUserById(params.id)
    return { user }
  })
  ```

  This has the problem of not being able to use the `route.name` to determine the correct typed params (with [unplugin-vue-router][uvr]):

  ```ts
  import { getUserById } from '../api'

  export const useUserData = defineLoader(async route => {
    if (route.name === 'user-details') {
      const user = await getUserById(route.params.id)
      //                                    ^ typed!
      return { user }
    }
  })
  ```

  :::

* Naming

  ::: details

  Variables could be named differently and proposals are welcome:

  * `isLoading` -> `isPending`, `pending` (same as Nuxt)
  * Rename `defineLoader()` to `defineDataFetching()` (or others)

  :::

* Nested/Sequential Loaders drawbacks

  ::: details

  * Allowing `await getUserById()` could make people think they should also await inside `<script setup>` and that would be a problem because it would force them to use `<Suspense>` when they don't need to. I think this is solved by changing the return type of the loader to a promise of just data, making it easy to spot the mistake. It could also be solved by forcing the need of a parameter `to` to ensure the type safety as explained [above](#sequential-fetching).

  * Another alternative is to pass an array of loaders to the loader that needs them and let it retrieve them through an argument, but it feels *considerably* less ergonomic:

    ```ts
    import { useUserData } from '~/pages/users/[id].vue'

    export const useUserFriends = defineLoader(
      async (route, { loaders: [userData] }) => {
        const friends = await getFriends(user.value.id)
        return { ...userData.value, friends }
      },
      {
        // explicit dependencies
        waitFor: [useUserData],
      }
    )
    ```

  :::

* Advanced `lazy`

  ::: details

  The `lazy` flag could be extended to also accept a number (timeout) or a function (dynamic value). I think this is too much and should therefore not be included. It can always be implemented by custom data loaders but I don't think it should be a requirement for the basic API.

  Passing a *number* to `lazy` could block the navigation for that number of milliseconds, then let it be:

  ```vue
  <script lang="ts">
  import { getUserById } from '../api'

  export const useUserData = defineLoader(
    async route => {
      const user = await getUserById(route.params.id)
      return user
    },
    // block the navigation for 1 second and then let the navigation go through
    { lazy: 1000 }
  )
  </script>

  <script setup>
  const { data, isLoading, error } = useUserData()
  //      ^ Ref<User | undefined>
  </script>
  ```

  Note that lazy loaders can only control their own blocking mechanism. They can't control the blocking of other loaders. If multiple loaders are being used and one of them is blocking, the navigation will be blocked until all of the blocking loaders are resolved.

  A function could allow to conditionally block upon navigation:

  ```ts
  export const useUserData = defineLoader(
    loader,
    // ...
    {
      lazy: route => {
        // ...
        return true // or a number
      },
    }
  )
  ```

  :::

* One could argue being able to reuse the result of loaders across any component other than page makes this more complex. Other frameworks expose a single *load* function from page components (SvelteKit, Remix)

## Adoption strategy

Introduce this as part of [unplugin-vue-router][uvr] to test it first and make it part of the router later on.

## Unresolved questions

* Integration with Server specifics in Frameworks like Nuxt: cookies, headers, server only loaders (can create redirect codes)
* Should there by a `beforeLoad()` hook that is called and awaited before all data loaders
* Same for `afterLoad()` that is always called after all data loaders
* What else is needed besides the `route` inside loaders?
* \~~Add option for placeholder data?~~ Data Loaders should implement this themselves
* What other operations might be necessary for users?

[uvr]: https://github.com/posva/unplugin-vue-router "unplugin-vue-router"

[pinia-colada]: https://github.com/posva/pinia-colada "@pinia/colada"

[vue-query]: https://tanstack.com/query/latest/docs/framework/vue/overview "@tanstack/vue-query"

---

---
url: /data-loaders/defining-loaders.md
---
# Defining Data Loaders

In order to use data loaders, you need to define them first. Data loaders themselves are the composables returned by the different `defineLoader` functions. Each loader definition is specific to the `defineLoader` function used. For example, `defineBasicLoader` expects an async function as the first argument while `defineColadaLoader` expects an object with a `query` function. All loaders should allow to pass an async function that can throw errors, and call `reroute()` to control the navigation.

Any composables returned by *any* `defineLoader` function share the same signature:

```vue twoslash
<script lang="ts">
import 'vue-router/auto-routes'
// ---cut---
import { defineBasicLoader } from 'vue-router/experimental'
import { getUserById } from '../api'

export const useUserData = defineBasicLoader('/users/[id]', async to => {
  return getUserById(to.params.id)
})
</script>

<script setup lang="ts">
const {
  data: user, // the data returned by the loader
  isLoading, // a boolean indicating if the loader is fetching data
  error, // an error object if the loader failed
  reload, // a function to refetch the data without navigating
} = useUserData()
</script>
```

**But they are not limited by it!** For example, the `defineColadaLoader` function returns a composable with a few more properties like `status` and `refresh`. Because of this it's important to refer to the documentation of the specific loader you are using.

This page will guide you through the **foundation** of defining data loaders, no matter their implementation.

## The loader function

The loader function is the *core* of data loaders. They are asynchronous functions that return the data you want to expose in the `data` property of the returned composable.

### The `to` argument

The `to` argument represents the location object we are navigating to. It should be used as the source of truth for all data fetching parameters.

```ts twoslash
import 'vue-router/auto-routes'
import { defineBasicLoader } from 'vue-router/experimental'
import { getUserById } from '../api'
// ---cut---
export const useUserData = defineBasicLoader('/users/[id]', async to => {
  const user = await getUserById(to.params.id)
  // here we can modify the data before returning it
  return user
})
```

By using the route location to fetch data, we ensure a consistent relationship between the data and the URL, **improving the user experience**.

### Side effects

It's important to avoid side effects in the loader function. Don't call `watch`, or create reactive effects like `ref`, `toRefs()`, `computed`, etc.

### Global Properties

In the loader function, you can access global properties like the router instance, a store, etc. This is because using `inject()` within the loader function **is possible**, just like within navigation guards. Since loaders are asynchronous, make sure you are using the `inject` function **before any `await`**:

```ts twoslash
import 'vue-router/auto-routes'
import { defineBasicLoader } from 'vue-router/experimental'
import { getUserById } from '../api'
// ---cut---
import { inject } from 'vue'
import { useSomeStore, useOtherStore } from '@/stores'

export const useUserData = defineBasicLoader('/users/[id]', async to => {
  // ✅ This will work
  const injectedValue = inject('key') // [!code ++]
  const store = useSomeStore() // [!code ++]

  const user = await getUserById(to.params.id)
  // ❌ These won't work
  const injectedValue2 = inject('key-2') // [!code error]
  const store2 = useOtherStore() // [!code error]
  // ...
  return user
})
```

### Navigation control

Since loaders happen within the context of a navigation, you can control the navigation by calling `reroute()`. This is similar to returning a value in a navigation guard. It throws internally, so execution stops immediately.

```ts{1,8,9}
import { reroute } from 'vue-router/experimental'

const useDashboardStats = defineBasicLoader('/admin', async (to) => {
  try {
    return await getDashboardStats()
  } catch (err) {
    if (err.code === 401) {
      // same as returning '/login' in a navigation guard
      reroute('/login')
    }
    throw err // unexpected error
  }
})
```

::: tip

Note that [lazy loaders](#lazy-loaders) cannot control the navigation since they do not block it.

:::

Read more in the [Navigation Aware](./navigation-aware.md) section.

### Errors

Any thrown Error will abort the navigation, just like in navigation guards. They will trigger the `router.onError` handler if defined.

::: tip

Note that [lazy loaders](#lazy-loaders) cannot control the navigation since they do not block it, any thrown error will appear in the `error` property and not abort the navigation nor appear in the `router.onError` handler.

:::

It's possible to define expected errors so they don't abort the navigation. You can read more about it in the [Error Handling](./error-handling.md) section.

## Options

Data loaders are designed to be flexible and allow for customization. Despite being navigation-centric, they can be used outside of a navigation and this flexibility is key to their design.

### Non blocking loaders with `lazy`

By default, loaders are *non-lazy*, meaning they will block the navigation until the data is fetched. But this behavior can be changed by setting the `lazy` option to `true`.

```vue{10,16} twoslash
<script lang="ts">
// ---cut-start---
import 'vue-router/auto-routes'
import { defineBasicLoader } from 'vue-router/experimental'
// ---cut-end---
import { getUserById } from '../api'

export const useUserData = defineBasicLoader(
  '/users/[id]',
  async (to) => {
    const user = await getUserById(to.params.id)
    return user
  },
  { lazy: true } // 👈  marked as lazy
)
</script>

<script setup>
// Differently from the example above, `user.value` can and will be initially `undefined`
const { data: user, isLoading, error } = useUserData()
//            ^?
</script>

<!-- ... -->
```

This patterns is useful to avoid blocking the navigation while *non critical data* is being fetched. It will display the page earlier while lazy loaders are still loading and you are able to display loader indicators thanks to the `isLoading` property.

Since lazy loaders do not block the navigation, any thrown error will not abort the navigation nor appear in the `router.onError` handler. Instead, the error will be available in the `error` property.

Note this still allows for having different behavior during SSR and client side navigation, e.g.: if we want to wait for the loader during SSR but not during client side navigation:

```ts{6-7}
export const useUserData = defineBasicLoader(
  async (to) => {
    // ...
  },
  {
    lazy: !import.meta.env.SSR, // Vite specific
  }
)
```

You can even pass a function to `lazy` to determine if the loader should be lazy or not based on each load/navigation:

```ts{6-7}
export const useSearchResults = defineBasicLoader(
  async (to) => {
    // ...
  },
  {
    // lazy if we are on staying on the same route
    lazy: (to, from) => to.name === from.name,
  }
)
```

This is really useful when you can display the old data while fetching the new one and some of the parts of the page require the route to be updated like search results and pagination buttons. By using a lazy loader only when the route changes, the pagination can be updated immediately while the search results are being fetched, allowing the user to click multiple times on the pagination buttons without waiting for the search results to be fetched.

### Delaying data updates with `commit`

By default, the data is updated only once all loaders are resolved. This is useful to avoid displaying partially loaded data or worse, incoherent data aggregation.

Sometimes you might want to immediately update the data as soon as it's available, even if other loaders are still pending. This can be achieved by changing the `commit` option:

```ts twoslash
import { defineBasicLoader } from 'vue-router/experimental'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchBookCollection(): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useBookCollection = defineBasicLoader(fetchBookCollection, {
  commit: 'immediate',
})
```

In the case of [lazy loaders](#lazy-loaders), they also default to `commit: 'after-load'`. They will commit after all other non-lazy loaders if they can but since they are not awaited, they might not be able to. In this case, the data will be available when finished loading, which can be much later than the navigation is completed.

### Server optimization with `server`

During SSR, it might be more performant to avoid loading data that isn't critical for the initial render. This can be achieved by setting the `server` option to `false`. That will completely skip the loader during SSR.

```ts{3} twoslash
import { defineBasicLoader } from 'vue-router/experimental'
interface Book {
  title: string
  isbn: string
  description: string
}
function fetchRelatedBooks(id: string | string[]): Promise<Book[]> {
  return {} as any
}
// ---cut---
export const useRelatedBooks = defineBasicLoader(
  (to) => fetchRelatedBooks(to.params.id),
  { server: false }
)
```

You can read more about server side rendering in the [SSR](./ssr.md) section.

## Connecting a loader to a page

The router needs to know what loaders should be ran with which page. This is achieved in two ways:

* **Automatically**: when a loader is exported from a page component that is lazy loaded, the loader will be automatically connected to the page

  ::: code-group

  ```ts{8} [router.ts]
  import { createRouter, createWebHistory } from 'vue-router'

  export const router = createRouter({
    history: createWebHistory(),
    routes: [
      {
        path: '/settings',
        component: () => import('./settings.vue'),
      },
    ],
  })
  ```

  ```vue{3-5} [settings.vue]
  <script lang="ts">
  import { getSettings } from './api'
  export const useSettings = defineBasicLoader('/settings', async (to) =>
    getSettings()
  )
  </script>

  <script lang="ts" setup>
  const { data: settings } = useSettings()
  </script>
  <!-- ...rest of the component -->
  ```

  :::

* **Manually**: by passing the defined loader into the `meta.loaders` property:

  ::: code-group

  ```ts{2,10-12} [router.ts]
  import { createRouter, createWebHistory } from 'vue-router'
  import Settings, { useSettings } from './settings.vue'

  export const router = createRouter({
    history: createWebHistory(),
    routes: [
      {
        path: '/settings',
        component: Settings,
        meta: {
          loaders: [useSettings],
        },
      }
    ],
  })
  ```

  ```vue{3-5} [settings.vue]
  <script lang="ts">
  import { getSettings } from './api'
  export const useSettings = defineBasicLoader('/settings', async (to) =>
    getSettings()
  )
  </script>

  <script lang="ts" setup>
  const { data: settings } = useSettings()
  </script>
  <!-- ...rest of the component -->
  ```

### *Disconnecting* a loader from a page

It is also possible **not to connect a loader to a page**. This allows you to delay the loading until the component is mounted. Usually you want to start loading the data as soon as possible but in some cases, it might be better to wait until the component is mounted. This can be achieved by not exporting the loader from the page component.

---

---
url: /guide/essentials/history-mode.md
---
# Different History modes

The `history` option when creating the router instance allows us to choose among different history modes.

## HTML5 Mode

The HTML5 mode is created with `createWebHistory()` and is the recommended mode:

```js
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    //...
  ],
})
```

When using `createWebHistory()`, the URL will look "normal," e.g. `https://example.com/user/id`. Beautiful!

Here comes a problem, though: Since our app is a single page client side app, without a proper server configuration, the users will get a 404 error if they access `https://example.com/user/id` directly in their browser. Now that's ugly.

Not to worry: To fix the issue, all you need to do is add a simple catch-all fallback route to your server. If the URL doesn't match any static assets, it should serve the same `index.html` page that your app lives in. Beautiful, again!

## Hash Mode

The hash history mode is created with `createWebHashHistory()`:

```js
import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    //...
  ],
})
```

It uses a hash character (`#`) before the actual URL that is internally passed. Because this section of the URL is never sent to the server, it doesn't require any special treatment on the server level. **It does however have a bad impact in SEO**. If that's a concern for you, use the HTML5 history mode.

## Memory mode

The memory history mode doesn't assume a browser environment and therefore doesn't interact with the URL **nor automatically triggers the initial navigation**. This makes it perfect for Node environment and SSR. It is created with `createMemoryHistory()` and **requires you to push the initial navigation** after calling `app.use(router)`.

```js
import { createRouter, createMemoryHistory } from 'vue-router'

const router = createRouter({
  history: createMemoryHistory(),
  routes: [
    //...
  ],
})
```

While it's not recommended, you can use this mode inside Browser applications but note **there will be no history**, meaning you won't be able to go *back* or *forward*.

## Example Server Configurations

**Note**: The following examples assume you are serving your app from the root folder. If you deploy to a subfolder, you should use [the `publicPath` option of Vue CLI](https://cli.vuejs.org/config/#publicpath) and the related [`base` property of the router](../../api/interfaces/Router.md#createWebHistory). You also need to adjust the examples below to use the subfolder instead of the root folder (e.g. replacing `RewriteBase /` with `RewriteBase /name-of-your-subfolder/`).

### Apache

```
<IfModule mod_negotiation.c>
  Options -MultiViews
</IfModule>

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>
```

Instead of `mod_rewrite`, you could also use [`FallbackResource`](https://httpd.apache.org/docs/2.4/mod/mod_dir.html#fallbackresource).

### nginx

```nginx
location / {
  try_files $uri $uri/ /index.html;
}
```

### Native Node.js

```js
const http = require('http')
const fs = require('fs')
const httpPort = 80

http
  .createServer((req, res) => {
    fs.readFile('index.html', 'utf-8', (err, content) => {
      if (err) {
        console.log('We cannot open "index.html" file.')
      }

      res.writeHead(200, {
        'Content-Type': 'text/html; charset=utf-8',
      })

      res.end(content)
    })
  })
  .listen(httpPort, () => {
    console.log('Server listening on: http://localhost:%s', httpPort)
  })
```

### Express with Node.js

For Node.js/Express, consider using [connect-history-api-fallback middleware](https://github.com/bripkens/connect-history-api-fallback).

### Internet Information Services (IIS)

1. Install [IIS UrlRewrite](https://www.iis.net/downloads/microsoft/url-rewrite)
2. Create a `web.config` file in the root directory of your site with the following:

```xml [web.config ~vscode-icons:file-type-xml~]
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Handle History Mode and custom 404/500" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>
```

### Caddy v2

```
try_files {path} /
```

### Caddy v1

```
rewrite {
    regexp .*
    to {path} /
}
```

### Firebase hosting

Add this to your `firebase.json`:

```json [firebase.json ~vscode-icons:file-type-firebase~]
{
  "hosting": {
    "public": "dist",
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}
```

### Netlify

Create a `_redirects` file that is included with your deployed files:

```[_redirects ~vscode-icons:file-type-light-netlify~]
/* /index.html 200
```

In vue-cli, nuxt, and vite projects, this file usually goes under a folder named `static` or `public`.

You can read more about the syntax on [Netlify documentation](https://docs.netlify.com/routing/redirects/rewrites-proxies/#history-pushstate-and-single-page-apps). You can also [create a `netlify.toml`](https://docs.netlify.com/configure-builds/file-based-configuration/) to combine *redirections* with other Netlify features.

### Vercel

Create a `vercel.json` file under the root directory of your project with the following:

```json [vercel.json ~vscode-icons:file-type-light-vercel~]
{
  "rewrites": [{ "source": "/:path*", "destination": "/index.html" }]
}
```

## Caveat

There is a caveat to this: Your server will no longer report 404 errors as all not-found paths now serve up your `index.html` file. To get around the issue, you should implement a catch-all route within your Vue app to show a 404 page:

```js
const router = createRouter({
  history: createWebHistory(),
  routes: [{ path: '/:pathMatch(.*)', component: NotFoundComponent }],
})
```

Alternatively, if you are using a Node.js server, you can implement the fallback by using the router on the server side to match the incoming URL and respond with 404 if no route is matched. Check out the [Vue server side rendering documentation](https://vuejs.org/guide/scaling-up/ssr.html) for more information.

---

---
url: /guide/essentials/dynamic-matching.md
---
# Dynamic Route Matching with Params

Very often we will need to map routes with the given pattern to the same component. For example, we may have a `User` component which should be rendered for all users but with different user IDs. In Vue Router we can use a dynamic segment in the path to achieve that, we call that a *param*:

```js
import User from './User.vue'

// these are passed to `createRouter`
const routes = [
  // dynamic segments start with a colon
  { path: '/users/:id', component: User },
]
```

Now URLs like `/users/johnny` and `/users/jolyne` will both map to the same route.

A *param* is denoted by a colon `:`. When a route is matched, the value of its *params* will be exposed as `route.params` in every component. Therefore, we can render the current user ID by updating `User`'s template to this:

```vue
<template>
  <div>
    <!-- The current route is accessible as $route in the template -->
    User {{ $route.params.id }}
  </div>
</template>
```

You can have multiple *params* in the same route, and they will map to corresponding fields on `route.params`. Examples:

| pattern                        | matched path             | route.params                             |
| ------------------------------ | ------------------------ | ---------------------------------------- |
| /users/:username               | /users/eduardo           | `{ username: 'eduardo' }`                |
| /users/:username/posts/:postId | /users/eduardo/posts/123 | `{ username: 'eduardo', postId: '123' }` |

In addition to `route.params`, the `route` object also exposes other useful information such as `route.query` (if there is a query in the URL), `route.hash`, etc. You can check out the full details in the [API Reference](../../api/#RouteLocationNormalized).

A working demo of this example can be found [here](https://codesandbox.io/s/route-params-vue-router-examples-mlb14?from-embed\&initialpath=%2Fusers%2Feduardo%2Fposts%2F1).

## Reacting to Params Changes

One thing to note when using routes with params is that when the user navigates from `/users/johnny` to `/users/jolyne`, **the same component instance will be reused**. Since both routes render the same component, this is more efficient than destroying the old instance and then creating a new one. **However, this also means that some lifecycle hooks of the component will not be called**.

To react to params changes in the same component, you can simply watch anything on the `route` object, in this scenario, the `route.params`:

::: code-group

```vue [Composition API]
<script setup>
import { watch } from 'vue'
import { useRoute } from 'vue-router'

const route = useRoute()

watch(
  () => route.params.id,
  (newId, oldId) => {
    // react to route changes...
  }
)
</script>
```

```vue [Options API]
<script>
export default {
  created() {
    this.$watch(
      () => this.$route.params.id,
      (newId, oldId) => {
        // react to route changes...
      }
    )
  },
}
</script>
```

:::

Or, use the `beforeRouteUpdate` [navigation guard](../advanced/navigation-guards.md), which also allows you to cancel the navigation:

::: code-group

```vue [Composition API]
<script setup>
import { onBeforeRouteUpdate } from 'vue-router'
// ...

onBeforeRouteUpdate(async (to, from) => {
  // react to route changes...
  userData.value = await fetchUser(to.params.id)
})
</script>
```

```vue [Options API]
<script>
export default {
  async beforeRouteUpdate(to, from) {
    // react to route changes...
    this.userData = await fetchUser(to.params.id)
  },
  // ...
}
</script>
```

:::

## Catch all / 404 Not found Route

Regular params will only match characters in between url fragments, separated by `/`. If we want to match **anything**, we can use a custom *param* regexp by adding the regexp inside parentheses right after the *param*:

```js
const routes = [
  // will match everything and put it under `route.params.pathMatch`
  { path: '/:pathMatch(.*)*', name: 'NotFound', component: NotFound },
  // will match anything starting with `/user-` and put it under `route.params.afterUser`
  { path: '/user-:afterUser(.*)', component: UserGeneric },
]
```

In this specific scenario, we are using a [custom regexp](./route-matching-syntax.md#custom-regexp-in-params) between parentheses and marking the `pathMatch` param as [optionally repeatable](./route-matching-syntax.md#optional-parameters). This allows us to directly navigate to the route if we need to by splitting the `path` into an array:

```js
router.push({
  name: 'NotFound',
  // preserve current path and remove the first char to avoid the target URL starting with `//`
  params: { pathMatch: route.path.substring(1).split('/') },
  // preserve existing query and hash if any
  query: route.query,
  hash: route.hash,
})
```

See more in the [repeated params](./route-matching-syntax.md#Repeatable-params) section.

If you are using [History mode](./history-mode.md), make sure to follow the instructions to correctly configure your server as well.

## Advanced Matching Patterns

Vue Router uses its own path matching syntax, inspired by the one used by `express`, so it supports many advanced matching patterns such as optional params, zero or more / one or more requirements, and even custom regex patterns. Please check the [Advanced Matching](./route-matching-syntax.md) documentation to explore them.

---

---
url: /guide/advanced/dynamic-routing.md
---
# Dynamic Routing

Adding routes to your router is usually done via the `routes` option but in some situations, you might want to add or remove routes while the application is already running. Applications with extensible interfaces like [Vue CLI UI](https://cli.vuejs.org/dev-guide/ui-api.html) can use this to make the application grow.

## Adding routes

Dynamic routing is achieved mainly via two functions: `router.addRoute()` and `router.removeRoute()`. They **only** register a new route, meaning that if the newly added route matches the current location, it would require you to **manually navigate** with `router.push()` or `router.replace()` to display that new route. Let's take a look at an example:

Imagine having the following router with one single route:

```js
const router = createRouter({
  history: createWebHistory(),
  routes: [{ path: '/:articleName', component: Article }],
})
```

Going to any page like `/about`, `/store`, or `/3-tricks-to-improve-your-routing-code` ends up rendering the `Article` component. If we are on `/about` and we add a new route:

```js
router.addRoute({ path: '/about', component: About })
```

The page will still show the `Article` component. We need to manually call `router.replace()` to change the current location and overwrite where we were (instead of pushing a new entry, ending up in the same location twice in our history):

```js
router.addRoute({ path: '/about', component: About })
// we could also use this.$route or useRoute()
router.replace(router.currentRoute.value.fullPath)
```

Remember you can `await router.replace()` if you need to wait for the new route to be displayed.

## Adding routes inside navigation guards

If you decide to add or remove routes inside of a navigation guard, you should not call `router.replace()` but trigger a redirection by returning the new location:

```js
router.beforeEach(to => {
  if (!hasNecessaryRoute(to)) {
    router.addRoute(generateRoute(to))
    // trigger a redirection
    return to.fullPath
  }
})
```

The example above assumes two things: first, the newly added route record will match the `to` location, effectively resulting in a different location from the one we were trying to access. Second, `hasNecessaryRoute()` returns `true` after adding the new route to avoid an infinite redirection.

Because we are redirecting, we are replacing the ongoing navigation, effectively behaving like the example shown before. In real world scenarios, adding is more likely to happen outside of navigation guards, e.g. when a view component mounts, it register new routes.

## Removing routes

There are few different ways to remove existing routes:

* By adding a route with a conflicting name. If you add a route that has the same name as an existing route, it will remove the route first and then add the route:

  ```js
  router.addRoute({ path: '/about', name: 'about', component: About })
  // this will remove the previously added route because they have
  // the same name and names are unique across all routes
  router.addRoute({ path: '/other', name: 'about', component: Other })
  ```

* By calling the callback returned by `router.addRoute()`:

  ```js
  const removeRoute = router.addRoute(routeRecord)
  removeRoute() // removes the route if it exists
  ```

  This is useful when the routes do not have a name

* By using `router.removeRoute()` to remove a route by its name:

  ```js
  router.addRoute({ path: '/about', name: 'about', component: About })
  // remove the route
  router.removeRoute('about')
  ```

  Note you can use `Symbol`s for names in routes if you wish to use this function but want to avoid conflicts in names.

Whenever a route is removed, **all of its aliases and children** are removed with it.

## Adding nested routes

To add nested routes to an existing route, you can pass the *name* of the route as its first parameter to `router.addRoute()`. This will effectively add the route as if it was added through `children`:

```js
router.addRoute({ name: 'admin', path: '/admin', component: Admin })
router.addRoute('admin', { path: 'settings', component: AdminSettings })
```

This is equivalent to:

```js
router.addRoute({
  name: 'admin',
  path: '/admin',
  component: Admin,
  children: [{ path: 'settings', component: AdminSettings }],
})
```

## Looking at existing routes

Vue Router gives you two functions to look at existing routes:

* [`router.hasRoute()`](/api/interfaces/Router.md#hasRoute): check if a route exists.
* [`router.getRoutes()`](/api/interfaces/Router.md#getRoutes): get an array with all the route records.

---

---
url: /data-loaders/error-handling.md
---
# Error handling

By default, all errors thrown in a loader are considered *unexpected errors*: they will abort the navigation, just like in a navigation guard. Because they abort the navigation, they will not appear in the `error` property of the loader. Instead, they will be intercepted by Vue Router's error handling with `router.onError()`.

However, if the loader is **not navigation-aware**, the error cannot be intercepted by Vue Router and will be kept in the `error` property of the loader. This is the case for *lazy loaders* and [*reloading data*](./reloading-data.md).

## Defining expected Errors

To be able to intercept errors in non-lazy loaders, we can specify a list of error classes that are considered *expected errors*. This allows blocking loader to **not abort the navigation** and instead keep the error in the `error` property of the loader and let the page locally display the error state.

```ts{3-10,14,18} twoslash
import { defineBasicLoader } from 'vue-router/experimental'
// custom error class
class MyError extends Error {
  // override is only needed in TS
  override name = 'MyError' // Displays in logs instead of 'Error'
  // defining a constructor is optional
  constructor(message: string) {
    super(message)
  }
}

export const useUserData = defineBasicLoader(
  async (to) => {
    throw new MyError('Something went wrong')
    // ...
    // ---cut-start---
    return { name: 'John' }
    // ---cut-end---
  },
  {
    errors: [MyError],
  }
)
```

You can also specify *expected errors* globally for all loaders by providing the `errors` option to the `DataLoaderPlugin`.

```ts{4} twoslash
import { createApp } from 'vue'
import type { Router } from 'vue-router'
import { DataLoaderPlugin } from 'vue-router/experimental'
const app = createApp({})
const router = {} as Router
class MyError extends Error {
  name = 'MyError'
  constructor(message: string) {
    super(message)
  }
}
// @errors: 2769
// ---cut---
app.use(DataLoaderPlugin, {
  router,
  // checks with `instanceof MyError`
  errors: [MyError],
})
```

Then you need to opt-in in the loader by setting the `errors` option to `true` to keep the error in the `error` property of the loader.

```ts{7} twoslash
import { defineBasicLoader } from 'vue-router/experimental'
// ---cut---
export const useUserData = defineBasicLoader(
  async (to) => {
    throw new Error('Something went wrong')
    // ...
    // ---cut-start---
    return { name: 'John' }
    // ---cut-end---
  },
  {
    errors: true,
  }
)
```

::: details Why is `errors: true` needed?

One of the benefits of Data Loaders is that they ensure the `data` to be ready before the component is rendered. With expected errors, this is no longer true and `data` can be `undefined`:

```ts{11} twoslash
import { defineBasicLoader } from 'vue-router/experimental'
// ---cut---
export const useDataWithErrors = defineBasicLoader(
  async (to) => {
    // ...
    // ---cut-start---
    return { name: 'John' }
    // ---cut-end---
  },
  {
    errors: true,
  }
)

const { data } = useDataWithErrors()
data.value // `data` can be `undefined`
```

:::

## Custom Error handling

If you need more control over the error handling, you can provide a function to the `errors` option. This option is available in both the `DataLoaderPlugin` and when defining a loader.

```ts{3-9} twoslash
// @errors: 2769
import { createApp } from 'vue'
import { DataLoaderPlugin } from 'vue-router/experimental'
const app = createApp({})
const router = {} as any
// ---cut---
app.use(DataLoaderPlugin, {
  router,
  errors: (error) => {
    // Convention for custom errors
    if (error instanceof Error && error.name?.startsWith('My')) {
      return true
    }
    return false // unexpected error
  },
})
```

## Handling both, local and global errors

TODO: this hasn't been implemented yet

## Error handling priority

When you use both, global and local error handling, the local error handling has a higher priority and will override the global error handling. This is how the local and global errors are checked:

* if local `errors` is `false`: abort the navigation -> `data` is not `undefined`
* if local `errors` is `true`: rely on the globally defined `errors` option -> `data` is possibly `undefined`
* else: rely on the local `errors` option -> `data` is possibly `undefined`

## TypeScript

You will notice that the type of `error` is `Error | null` even when you specify the `errors` option. This is because if we call the `reload()` method (meaning we are outside of a navigation), the error isn't discarded, it appears in the `error` property **without being filtered** by the `errors` option.

In practice, depending on how you handle the error, you will add a [type guard](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards) inside the component responsible for displaying an error or directly in a `v-if` in the template.

```vue-html
<template>
  <!-- ... -->
  <p v-if="isMyError(error)">{{ error.message }}</p>
</template>
```

If you want to be even stricter, you can override the default `Error` type with `unknown` (or anything else) by augmenting the `TypesConfig` interface.

```ts
// types-extension.d.ts
import 'vue-router'
export {}

declare module 'vue-router' {
  interface TypesConfig {
    Error: unknown
  }
}
```

---

---
url: /file-based-routing/eslint.md
---
# ESLint

If you are not using auto imports, you will need to tell ESLint about `vue-router/auto-routes`. Add these lines to your eslint configuration:

```json{3}
{
  "settings": {
    "import/core-modules": ["vue-router/auto-routes"]
  }
}
```

## `definePage()`

Since `definePage()` is a global macro, you need to tell ESLint about it. Add these lines to your eslint configuration:

```json{3}
{
  "globals": {
    "definePage": "readonly"
  }
}
```

---

---
url: /guide/advanced/extending-router-link.md
---
# Extending RouterLink

The RouterLink component exposes enough `props` to suffice most basic applications but it doesn't try to cover every possible use case and you will likely find yourself using `v-slot` for some advanced cases. In most medium to large sized applications, it's worth creating one if not multiple custom RouterLink components to reuse them across your application. Some examples are Links in a Navigation Menu, handling external links, adding an `inactive-class`, etc.

Let's extend RouterLink to handle external links as well and adding a custom `inactive-class` in an `AppLink.vue` file:

::: code-group

```vue [Composition API]
<script setup>
import { computed } from 'vue'
import { RouterLink } from 'vue-router'

defineOptions({
  inheritAttrs: false,
})

const props = defineProps({
  // add @ts-ignore if using TypeScript
  ...RouterLink.props,
  inactiveClass: String,
})

const isExternalLink = computed(() => {
  return typeof props.to === 'string' && props.to.startsWith('http')
})
</script>

<template>
  <a v-if="isExternalLink" v-bind="$attrs" :href="to" target="_blank">
    <slot />
  </a>
  <router-link
    v-else
    v-bind="$props"
    custom
    v-slot="{ isActive, href, navigate }"
  >
    <a
      v-bind="$attrs"
      :href="href"
      @click="navigate"
      :class="isActive ? activeClass : inactiveClass"
    >
      <slot />
    </a>
  </router-link>
</template>
```

```vue [Options API]
<script>
import { RouterLink } from 'vue-router'

export default {
  name: 'AppLink',
  inheritAttrs: false,

  props: {
    // add @ts-ignore if using TypeScript
    ...RouterLink.props,
    inactiveClass: String,
  },

  computed: {
    isExternalLink() {
      return typeof this.to === 'string' && this.to.startsWith('http')
    },
  },
}
</script>

<template>
  <a v-if="isExternalLink" v-bind="$attrs" :href="to" target="_blank">
    <slot />
  </a>
  <router-link
    v-else
    v-bind="$props"
    custom
    v-slot="{ isActive, href, navigate }"
  >
    <a
      v-bind="$attrs"
      :href="href"
      @click="navigate"
      :class="isActive ? activeClass : inactiveClass"
    >
      <slot />
    </a>
  </router-link>
</template>
```

:::

If you prefer using a render function or create `computed` properties, you can use the `useLink` from the [Composition API](./composition-api.md):

```js
import { RouterLink, useLink } from 'vue-router'

export default {
  name: 'AppLink',

  props: {
    // add @ts-ignore if using TypeScript
    ...RouterLink.props,
    inactiveClass: String,
  },

  setup(props) {
    // `props` contains `to` and any other prop that can be passed to <router-link>
    const { navigate, href, route, isActive, isExactActive } = useLink(props)

    // profit!

    return { isExternalLink }
  },
}
```

In practice, you might want to use your `AppLink` component for different parts of your application. e.g. using [Tailwind CSS](https://tailwindcss.com), you could create a `NavLink.vue` component with all the classes:

```vue
<template>
  <AppLink
    v-bind="$attrs"
    class="inline-flex items-center px-1 pt-1 border-b-2 border-transparent text-sm font-medium leading-5 text-gray-500 hover:text-gray-700 hover:border-gray-300 focus:outline-none focus:text-gray-700 focus:border-gray-300 transition duration-150 ease-in-out"
    active-class="border-indigo-500 text-gray-900 focus:border-indigo-700"
    inactive-class="text-gray-500 hover:text-gray-700 hover:border-gray-300 focus:text-gray-700 focus:border-gray-300"
  >
    <slot />
  </AppLink>
</template>
```

---

---
url: /file-based-routing/extending-routes.md
---
# Extending Routes

## Extending routes in config

You can extend the routes at build time with the `extendRoute` or the `beforeWriteFiles` options. Both can return a Promise:

```ts
import VueRouter from 'vue-router/vite'
import path from 'node:path'

VueRouter({
  extendRoute(route) {
    if (route.name === '/[name]') {
      route.addAlias('/hello-vite-:name')
    }
  },

  beforeWriteFiles(root) {
    root.insert('/from-root', path.join(__dirname, './src/pages/index.vue'))
  },
})
```

Routes modified this way will be reflected in the generated `typed-router.d.ts` file.

## In-Component Routing

It's possible to override the route configuration directly in the page component file. These changes are picked up by the plugin and reflected in the generated `typed-router.d.ts` file.

### `definePage()`

You can modify and extend any page component with the `definePage()` macro. This is useful for adding meta information, or modifying the route object. It's globally available in Vue components but you can import it from `vue-router` if needed.

```vue{2-7}
<script setup lang="ts">
definePage({
  alias: ['/n/:name'],
  meta: {
    requiresAuth: true,
  },
})
</script>

<template>
  <!-- ... -->
</template>
```

If you are using ESLint, you will need [to declare it as a global variable](./eslint#definepage).

::: danger

You cannot use variables in `definePage()` as its passed parameter gets extracted at build time and is removed from `<script setup>`. Similar to other macros like `definePageMeta()` in Nuxt.

For similar reasons, `beforeEnter` guards are **not supported** in `definePage()`. Their function nature make them look like they can access outside variable when they can't. \*\*Use a [global navigation guard](../guide/advanced/navigation-guards.md#global-before-guards**) with [route meta fields](../guide/advanced/meta.md) instead, **or add the guard at runtime (see [Extending routes at runtime](#extending-routes-at-runtime) below)**.

:::

### SFC `<route>` custom block

The `<route>` custom block is a way to extend existing routes. It can be used to add new `meta` fields, override the `path`, the `name`, or anything else in a route. **It has to be added to a `.vue` component inside of the [routes folder](./file-based-routing#routes-folder-structure)**. It is similar to [the same feature in vite-plugin-pages](https://github.com/hannoeru/vite-plugin-pages#sfc-custom-block-for-route-data) to facilitate migration.

```vue
<route lang="json">
{
  "name": "name-override",
  "meta": {
    "requiresAuth": false
  }
}
</route>
```

Note you can specify the language to use with `<route lang="yaml">`. By default, the language is JSON5 (more flexible version of JSON) but yaml and JSON are also supported.

## Extending routes at runtime

As an escape-hatch, it's possible to extend the routes **at runtime** by simply changing or cloning the `routes` array before passing it to `createRouter()`. Since these changes are made at runtime, they are not reflected in the generated `typed-router.d.ts` file.

```js{4-9}
import { createWebHistory, createRouter } from 'vue-router'
import { routes } from 'vue-router/auto-routes'

for (const route of routes) {
  if (route.name === '/admin') {
    route.meta ??= {}
    route.meta.requiresAuth = true
  }
}

const router = createRouter({
  history: createWebHistory(),
  routes,
})
```

::: warning
Routes added at runtime [require special handling for HMR](./hmr#runtime-routes).
:::

As this plugin evolves, this should be used less and less and only become necessary in specific scenarios.

One example of this is using [vite-plugin-vue-layouts](https://github.com/JohnCampionJr/vite-plugin-vue-layouts) which can only be used this way:

```ts
import { createRouter } from 'vue-router'
import { routes } from 'vue-router/auto-routes'
import { setupLayouts } from 'virtual:generated-layouts'

const router = createRouter({
  // ...
  routes: setupLayouts(routes),
})
```

Another one is adding *redirect* records to the router:

```ts
import { routes } from 'vue-router/auto-routes'

routes.push({
  path: '/path-to-redirect',
  redirect: '/redirected-path',
})

routes.push({
  path: '/path-to-redirect/:id',
  redirect: to => `/redirected-path/${to.params.id}`,
})
```

One benefit of adding redirects at runtime only is that they are not reflected in the generated `typed-router.d.ts` and won't appear in autocompletion but will still work as expected when the user enters the URL or clicks on a link.

---

---
url: /file-based-routing/file-based-routing.md
---
# File Conventions

The file-based routing is as close as possible to [Nuxt](https://nuxt.com/docs/guide/directory-structure/pages).

## Routes folder structure

By default, this plugin checks the folder at `src/pages` for any `.vue` files and generates the corresponding routing structure based on the file name. This way, you no longer need to maintain a `routes` array when adding routes to your application, **instead just add the new `.vue` component to the routes folder and let the plugin do the rest!**

Let's take a look at a simple example:

```text
src/pages/
├── index.vue
├── about.vue
└── users/
    ├── index.vue
    └── [id].vue
```

This will generate the following routes:

* `/`: -> renders the `index.vue` component
* `/about`: -> renders the `about.vue` component
* `/users`: -> renders the `users/index.vue` component
* `/users/:id`: -> renders the `users/[id].vue` component. `id` becomes a route param.

### Index Routes

Any `index.vue` (**must be all lowercase**) file will generate an empty path (similar to `index.html` files):

* `src/pages/index.vue`: generates a `/` route
* `src/pages/users/index.vue`: generates a `/users` route

### Nested Routes

Nested routes are automatically defined by defining a `.vue` file alongside a folder **with the same name**. If you create both a `src/pages/users/index.vue` and a `src/pages/users.vue` components, the `src/pages/users/index.vue` will be rendered within the `src/pages/users.vue`'s `<RouterView>`.

In other words, given this folder structure:

```text
src/pages/
├── users/
│   └── index.vue
└── users.vue
```

You will get this `routes` array:

```js
const routes = [
  {
    path: '/users',
    component: () => import('src/pages/users.vue'),
    children: [
      { path: '', component: () => import('src/pages/users/index.vue') },
    ],
  },
]
```

While omitting the `src/pages/users.vue` component will generate the following routes:

```js
const routes = [
  {
    path: '/users',
    // notice how there is no component here
    children: [
      { path: '', component: () => import('src/pages/users/index.vue') },
    ],
  },
]
```

Note the folder and file's name `users/` could be any valid naming like `my-[id]-param/`.

#### Nested routes without nesting layouts

Sometimes you might want to add *nesting to the URL* in the form of slashes but you don't want it to impact your UI hierarchy. Consider the following folder structure:

```text
src/pages/
├── users/
│   ├── [id].vue
│   └── index.vue
└── users.vue
```

If you want to add a new route `/users/create` you could add a new file `src/pages/users/create.vue` but that would nest the `create.vue` component within the `users.vue` component. To avoid this you can instead create a file `src/pages/users.create.vue`. The `.` will become a `/` when generating the routes:

```js
const routes = [
  {
    path: '/users',
    component: () => import('src/pages/users.vue'),
    children: [
      { path: '', component: () => import('src/pages/users/index.vue') },
      { path: ':id', component: () => import('src/pages/users/[id].vue') },
    ],
  },
  {
    path: '/users/create',
    component: () => import('src/pages/users.create.vue'),
  },
]
```

### Named routes

All generated routes that have a `component` property will have a `name` property. This avoids accidentally directing your users to a parent route. By default, names are generated using the file path, but you can override this behavior by passing a custom `getRouteName()` function. You will get TypeScript validation almost everywhere, so changing this should be easy.

## Route groups

Sometimes, it helps to organize your file structure in a way that doesn't change the URL of your routes. Route groups let you organize your routes logically, in a way that makes sense to you, without affecting the actual URLs. For example, if you have several routes that share the same layout, you can group them together using route groups. Consider the following file structure:

```text
src/pages/
├── (admin)/
│   ├── dashboard.vue
│   └── settings.vue
└── (user)/
    ├── profile.vue
    └── order.vue
```

Resulting URLs:

```text
- `/dashboard` -> renders `src/pages/(admin)/dashboard.vue`
- `/settings` -> renders `src/pages/(admin)/settings.vue`
- `/profile` -> renders `src/pages/(user)/profile.vue`
- `/order` -> renders `src/pages/(user)/order.vue`
```

This approach allows you to organize your files for better maintainability without changing the structure of your application's routes.

You can also use route groups in page components. This is equivalent to naming the page component `index.vue`:

```text
src/pages/
└─── admin/
    ├── (dashboard).vue // Becomes index.vue of admin route
    └── settings.vue
```

## Named views

It is possible to define [named views](https://router.vuejs.org/guide/essentials/named-views.html#named-views) by appending an `@` + a name to their filename, e.g. a file named `src/pages/index@aux.vue` will generate a route of:

```js
{
  path: '/',
  component: {
    aux: () => import('src/pages/index@aux.vue')
  }
}
```

Note that by default a non named route is named `default` and that you don't need to name your file `index@default.vue` even if there are other named views (e.g. having `index@aux.vue` and `index.vue` is the same as having `index@aux.vue` and `index@default.vue`).

## Dynamic Routes

You can add [route params](https://router.vuejs.org/guide/essentials/dynamic-matching.html) by wrapping the *param name* with brackets, e.g. `src/pages/users/[id].vue` will create a route with the following path: `/users/:id`. Note you can add a param in the middle in between static segments: `src/pages/users_[id].vue` -> `/users_:id`. You can even add multiple params: `src/pages/product_[skuId]_[seoDescription].vue`.

You can create [**optional params**](https://router.vuejs.org/guide/essentials/route-matching-syntax.html#optional-parameters) by wrapping the *param name* with an extra pair of brackets, e.g. `src/pages/users/[[id]].vue` will create a route with the following path: `/users/:id?`.

You can create [**repeatable params**](https://router.vuejs.org/guide/essentials/route-matching-syntax.html#repeatable-params) by adding a plus character (`+`) after the closing bracket, e.g. `src/pages/articles/[slugs]+.vue` will create a route with the following path: `/articles/:slugs+`.

And you can combine both to create optional repeatable params, e.g. `src/pages/articles/[[slugs]]+.vue` will create a route with the following path: `/articles/:slugs*`.

## Catch all / 404 Not found route

To create a catch all route prepend 3 dots (`...`) to the param name, e.g. `src/pages/[...path].vue` will create a route with the following path: `/:path(.*)`. This will match any route. Note this can be done inside a folder too, e.g. `src/pages/articles/[...path].vue` will create a route with the following path: `/articles/:path(.*)`.

## Multiple routes folders

It's possible to provide multiple routes folders by passing an array to `routesFolder`:

```js
VueRouter({
  routesFolder: ['src/pages', 'src/admin/routes'],
})
```

You can also provide a path prefix for each of these folders, it will be used *as is*, and **cannot start with a `/`** but can contain any params you want or even **not finish with a `/`**:

```ts
import VueRouter from 'vue-router/vite'

VueRouter({
  routesFolder: [
    'src/pages',
    {
      src: 'src/admin/routes',
      // note there is always a trailing slash and never a leading one
      path: 'admin/',
      // src/admin/routes/dashboard.vue -> /admin/dashboard
    },
    {
      src: 'src/docs',
      // you can add parameters
      path: 'docs/:lang/',
      // src/docs/introduction.vue -> /docs/:lang/introduction
    },
    {
      src: 'src/promos',
      // you can omit the trailing slash
      path: 'promos-',
      // src/promos/black-friday.vue -> /promos-black-friday
    },
  ],
})
```

Note that the provided folders must be separate and one *route folder* cannot contain another specified *route folder*. If you need further customization, give [definePage()](./extending-routes#definepage) a try.

## Custom extensions

While most of the time you will be using `.vue` files, you can also specify custom extensions to be considered as pages. You can for example use *markdown* files as pages:

```ts
import VueRouter from 'vue-router/vite'

VueRouter({
  // globally set the extensions
  extensions: ['.vue', '.md'],
  routesFolder: [
    'src/pages',
    {
      src: 'src/docs',
      // override the global extensions to **only** accept markdown files
      extensions: ['.md'],
    },
  ],
})
```

In this scenario, files named `index.md` (**must be all lowercase**) will generate an empty path like `index.vue` files.

---

---
url: /file-based-routing.md
---
# Getting Started

Vue Router includes a built-in file-based routing plugin. It generates the routes and types automatically from your page components, so you no longer need to maintain a `routes` array manually.

## Setup

Add the plugin to your bundler:

::: code-group

```ts [vite.config.ts]
import VueRouter from 'vue-router/vite'

export default defineConfig({
  plugins: [
    VueRouter({
      /* options */
    }),
    // ⚠️ Vue must be placed after VueRouter()
    Vue(),
  ],
})
```

```ts [rollup.config.js]
import VueRouter from 'vue-router/unplugin/rollup'

export default {
  plugins: [
    VueRouter({
      /* options */
    }),
    // ⚠️ Vue must be placed after VueRouter()
    Vue(),
  ],
}
```

```ts [webpack.config.js]
module.exports = {
  /* ... */
  plugins: [
    require('vue-router/unplugin/webpack')({
      /* options */
    }),
  ],
}
```

```ts [vue.config.js]
module.exports = {
  configureWebpack: {
    plugins: [
      require('vue-router/unplugin/webpack')({
        /* options */
      }),
    ],
  },
}
```

```ts [esbuild.config.js]
import { build } from 'esbuild'
import VueRouter from 'vue-router/unplugin/esbuild'

build({
  plugins: [VueRouter()],
})
```

:::

After adding this plugin, **start the dev server** (usually `npm run dev`) **to generate the first version of the types** at `typed-router.d.ts` which should be added to your `tsconfig.json` along with `"moduleResolution": "Bundler"`. This is what it should look like:

::: code-group

```json{8} [tsconfig.json]
{
  "include": [
    // other files...
    "./typed-router.d.ts" // [!code ++]
  ],
  "compilerOptions": {
    // ...
    "moduleResolution": "Bundler",
    // ...
  }
}
```

```ts [typed-router.d.ts]
/* eslint-disable */
/* prettier-ignore */
// @ts-nocheck
// Generated by vue-router. ‼️ DO NOT MODIFY THIS FILE ‼️
// It's recommended to commit this file.
// Make sure to add this file to your tsconfig.json file as an "includes" or "files" entry.

declare module 'vue-router/auto-routes' {
  import type {
    RouteRecordInfo,
    ParamValue,
    ParamValueOneOrMore,
    ParamValueZeroOrMore,
    ParamValueZeroOrOne,
  } from 'vue-router'

  /**
   * Route name map generated by vue-router file-based routing
   */
  export interface RouteNamedMap {
    '/': RouteRecordInfo<
      '/',
      '/',
      Record<never, never>,
      Record<never, never>,
      | never
    >
    '/about': RouteRecordInfo<
      '/about',
      '/about',
      Record<never, never>,
      Record<never, never>,
      | never
    >
    '/users/[id]': RouteRecordInfo<
      '/users/[id]',
      '/users/:id',
      { id: ParamValue<true> },
      { id: ParamValue<false> },
      | never
    >
  }
}
```

:::

### Volar Plugins

To get the best TypeScript experience in Single File Components, add the following Volar plugins to your `tsconfig.json` (or `tsconfig.app.json`):

```jsonc [tsconfig.json]
{
  "vueCompilerOptions": {
    "plugins": [
      "vue-router/volar/sfc-route-blocks",
      "vue-router/volar/sfc-typed-router",
    ],
  },
}
```

* `vue-router/volar/sfc-route-blocks` — enables `<route>` blocks in SFCs for defining per-page route metadata
* `vue-router/volar/sfc-typed-router` — makes `useRoute()` return a typed route based on the current page component, so `route.params` is correctly typed

### Migrating an existing project

Move your page components to `src/pages` and rename them accordingly. Here is an example of migration.
Given the following route configuration:

::: code-group

```ts [src/router.ts]
import { createRouter, createWebHistory } from 'vue-router'
import { routes, handleHotUpdate } from 'vue-router/auto-routes' // [!code ++]

export const router = createRouter({
  history: createWebHistory(),
  routes: [ // [!code --]
    { // [!code --]
      path: '/', // [!code --]
      component: () => import('src/pages/Home.vue'), // [!code --]
    }, // [!code --]
    { // [!code --]
      path: '/users/:id', // [!code --]
      component: () => import('src/pages/User.vue'), // [!code --]
    } // [!code --]
    { // [!code --]
      path: '/about', // [!code --]
      component: () => import('src/pages/About.vue'), // [!code --]
    }, // [!code --]
  ] // [!code --]
  routes, // [!code ++]
})

// This will update routes at runtime without reloading the page
if (import.meta.hot) { // [!code ++]
  handleHotUpdate(router) // [!code ++]
} // [!code ++]
```

```ts{2,5} [main.ts]
import { createApp } from 'vue'
import { router } from './router'
import App from './App.vue'

createApp(App).use(router).mount('#app')
```

:::

* Rename `src/pages/Home.vue` to `src/pages/index.vue`
* Rename `src/pages/User.vue` to `src/pages/users/[id].vue`
* Rename `src/pages/About.vue` to `src/pages/about.vue`

Check the [file conventions](./file-based-routing) guide for more information about the naming conventions.

### From scratch

* Create a `src/pages` folder and add an `index.vue` component to it. This will render your home page at `/`.
* Import the `routes` from `vue-router/auto-routes` and pass them to the `createRouter` function.

::: code-group

```ts{2-3,6-9,12} [src/main.ts]
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { routes } from 'vue-router/auto-routes'
import App from './App.vue'

const router = createRouter({
  history: createWebHistory(),
  routes,
})

createApp(App)
  .use(router)
  .mount('#app')
```

```vue [src/pages/index.vue]
<template>
  <h1>Home</h1>
</template>
```

:::

Check the [file conventions](./file-based-routing) guide for more information about the naming conventions.

### Manipulating the routes

You can pass the `routes` to any plugin that needs to add changes to them but note that **these changes will not be reflected in types**. Use [build-time routes instead](./extending-routes) if you want to have types support. Here is an example with [Vitesse starter](https://github.com/antfu-collective/vitesse/blob/main/src/main.ts):

```ts
import { ViteSSG } from 'vite-ssg'
import { setupLayouts } from 'virtual:generated-layouts'
import App from './App.vue'
import type { UserModule } from './types'
import generatedRoutes from '~pages' // [!code --]
import { routes } from 'vue-router/auto-routes' // [!code ++]

import '@unocss/reset/tailwind.css'
import './styles/main.css'
import 'uno.css'

const routes = setupLayouts(generatedRoutes) // [!code --]

// https://github.com/antfu/vite-ssg
export const createApp = ViteSSG(
  App,
  {
    routes, // [!code --]
    routes: setupLayouts(routes), // [!code ++]
    base: import.meta.env.BASE_URL,
  },
  ctx => {
    // install all modules under `modules/`
    Object.values(
      import.meta.glob<{ install: UserModule }>('./modules/*.ts', {
        eager: true,
      })
    ).forEach(i => i.install?.(ctx))
  }
)
```

## ESLint

If you use ESlint, check [the ESlint section](./eslint).

---

---
url: /guide.md
---
# Getting Started

Watch a Free Vue Router Video Course

Vue Router is the official client-side routing solution for Vue.

Client-side routing is used by single-page applications (SPAs) to tie the browser URL to the content seen by the user. As users navigate around the application, the URL updates accordingly, but the page doesn't need to be reloaded from the server.

Vue Router is built on Vue's component system. You configure **routes** to tell Vue Router which components to show for each URL path.

This guide will assume that you are already familiar with Vue itself. You don't need to be a Vue expert, but you may occasionally need to refer back to [the core Vue documentation](https://vuejs.org/) for more information about certain features.

## An example

To introduce some of the main ideas, we're going to consider this example:

* [Vue Playground example](https://play.vuejs.org/#eNqFVttu20YQ/ZUpU0AyapGKekGhKorTIKhTpKlhp81D2QeKXImMl7vM7tKWIOjfc3aXN8l2YsM2Odczc2ZG3gdlUojwkw7mQVFWUhnaU6pYYtirqqIDrZUsaXRXs1EsGgMla8NUowkj/9qrrV+rS6oq9L6x6KKO8XMWC6Kw1mzs3f17KWthxqNncBudBedB4w5sC8PKisN/aQ0X+fPlJeNc2mTfLSK8OnHl/uBBGyXFZvm6VoqJBjFVicnni6jR0X5P3ztFuK45v4KSDgcXJvJxFiK5awNeO5TvCnFLRr6IgygOln9IPNOlLNki6vVPeiQrSDq3V/btgd8ianMuLC/Hsf4t2D1FjV2jXkRdY9Av38tH2fyLlVLtLgtt8Oe8Efq4Q5YnHZsdn7ZAl7oltRU0zLa024KO7DpJPwJS6IYNTS/oP1vK3vNCo2gEWBLBBCib92kP58dmro/Htn1ua/z/SSqFVMN6x3sbMIrovTRsTh/ZSDGqdSE2j/VqfEY5g8FaKpcyMcWq4IXZNUH8132B8TE5oyue7DZIK7KQ3gpKCBE5YZB5kcJVCtrJepQhX51wfhwE69Ag+MhWfXqbuJMmOu81BWpkSeYa1EUxO1uJxeLHHsNmX1ZK3mv04p/rdyHdMMghzGRal2ihQ3YUxZaLLjDkwGPpobvWU+7zQ50xHVqvRjJ/vH8OnicdjweseizY1g1NxtZJzVueMMHD2bJrr1NVVAaDfuLgKCyZyWWm5/6NaCM/SDcKaE0jQjsALvSLrsKq1vm4HSF3c6iZL/sb24/z0GbEy8nRmS1beDg5My9c1cagMxcp+L3FmncYTjfdGz5Y2aMl6SsmzUxtz1C/xpg91JA9fpP3dnjceJ93T08u9sludPZjdGSgG6isptVplqg0tzvVIPL7tGGDtiugV8KHCT/XTO3Cxu3lSxoBRNt2lDn2mt7XU6UYepSy8Z6cP0huMx/IzhAi+GH6BmVdg3vOeLJivLmtNy7mnBaFQDF0N7FTzUOjihJs+oxxQGWy5UxsTA7hbApu/RVuIx1z6jmZlEmFUywFWHWlxY1Cx0E3snHQc2PFcZAbU+l5FNWiut2E6HHUW1z8HE7DWZRhswbSkOly0qw3EsaB66yNfQGjKGN3RkquJ0lVPJXigeHFr8j0S59pqHuQryUDpRuNIVkXm5PC7agUnKm/K3tHjhuAMyjv/3Qyo2rWgU9zlt4+Iv+kt76MK8WA4I4NCjaJwhx69Zub92yL504JZmsO668or5mWvHbH0Jn9jjsO2AM7h/at4xFn9oN+szVM6LYoC7Qfbkfu66+U3sP9Mfxp0EVtdhynNdX2gxz/EZxj/grh/VZSZUzNaVZtCWCLjJ5Np9Pf3D1EuEJMVhKXppzT82m1dfIqyTKA7STIEguEpSU+n37Aj7+m3puzNT5Rh5b5bJi5D98DSNN0AGBOU3zPmgjB4QtAqIeC)

Let's start by looking at the root component, `App.vue`.

### App.vue

```vue [App.vue]
<template>
  <h1>Hello App!</h1>
  <p><strong>Current route path:</strong> {{ $route.fullPath }}</p>
  <nav>
    <RouterLink to="/">Go to Home</RouterLink>
    <RouterLink to="/about">Go to About</RouterLink>
  </nav>
  <main>
    <RouterView />
  </main>
</template>
```

This template is using two components provided by Vue Router, `RouterLink` and `RouterView`.

Instead of using regular `<a>` tags, we use the custom component `RouterLink` to create links. This allows Vue Router to change the URL without reloading the page, handle URL generation, encoding, and various other features. We'll go into more detail about `RouterLink` in later sections of the guide.

The `RouterView` component tells Vue Router where to render the current **route component**. That's the component that corresponds to the current URL path. It doesn't have to be in `App.vue`, you can put it anywhere to adapt it to your layout, but it does need to be included somewhere, otherwise Vue Router won't render anything.

The example above also uses {{ $route.fullPath }}. You can use `$route` in your component templates to access an object that represents the current route.

### Creating the router instance

The router instance is created by calling the function `createRouter()`:

```js
import { createMemoryHistory, createRouter } from 'vue-router'

import HomeView from './HomeView.vue'
import AboutView from './AboutView.vue'

const routes = [
  { path: '/', component: HomeView },
  { path: '/about', component: AboutView },
]

export const router = createRouter({
  history: createMemoryHistory(),
  routes,
})
```

The `routes` option defines the routes themselves, mapping URL paths to components. The component specified by the `component` option is the one that will be rendered by the `<RouterView>` in our earlier `App.vue`. These route components are sometimes referred to as *views*, though they are just normal Vue components.

Routes support various other options that we'll see later in the guide, but for now we only need `path` and `component`.

The `history` option controls how routes are mapped onto URLs and vice versa. For the Playground example we're using `createMemoryHistory()`, which ignores the browser URL entirely and uses its own internal URL instead. That works well for the Playground, but it's unlikely to be what you'd want in a real application. Typically, you'd want to use `createWebHistory()` instead, or perhaps `createWebHashHistory()`. We'll cover that topic in more detail in the guide to [History modes](./essentials/history-mode).

### Registering the router plugin

Once we've created our router instance, we need to register it as a plugin by calling `use()` on our application:

```js
createApp(App).use(router).mount('#app')
```

Or, equivalently:

```js
const app = createApp(App)
app.use(router)
app.mount('#app')
```

Like with most Vue plugins, the call to `use()` needs to happen before the call to `mount()`.

If you're curious about what this plugin does, some of its responsibilities include:

1. [Globally registering](https://vuejs.org/guide/components/registration.html#global-registration) the `RouterView` and `RouterLink` components.
2. Adding the global `$router` and `$route` properties.
3. Enabling the `useRouter()` and `useRoute()` composables.
4. Triggering the router to resolve the initial route.

### Accessing the router and current route

You'll likely want to access the router from elsewhere in your application.

If you're exporting the router instance from an ES module, you could import the router instance directly where you need it. In some cases this is the best approach, but we have other options if we're inside a component.

In component templates, the router instance is exposed as `$router`. This is similar to the `$route` property we saw earlier, but note the extra `r` on the end.

If we're using the Options API, we can access these same two properties as `this.$router` and `this.$route` in our JavaScript code. The `HomeView.vue` component in the Playground example accesses the router that way:

```js
export default {
  methods: {
    goToAbout() {
      this.$router.push('/about')
    },
  },
}
```

This method is calling `push()`, which is used for [programmatic navigation](./essentials/navigation). We'll learn more about that later.

With the Composition API, we don't have access to the component instance via `this`, so Vue Router includes some composables that we can use instead. `AboutView.vue` in the Playground example is using that approach:

```vue
<script setup>
import { computed } from 'vue'
import { useRoute, useRouter } from 'vue-router'

const router = useRouter()
const route = useRoute()

const search = computed({
  get() {
    return route.query.search ?? ''
  },
  set(search) {
    router.replace({ query: { search } })
  },
})
</script>
```

It's not necessary to understand all of that code right now. The key thing to notice is that the composables `useRouter()` and `useRoute()` are used to access the router instance and current route respectively.

### Next steps

If you'd like to see a complete example using Vite, you can use the [create-vue](https://github.com/vuejs/create-vue) scaffolding tool, which has the option to include Vue Router in its example project:

::: code-group

```bash [npm]
npm create vue@latest
```

```bash [yarn]
yarn create vue
```

```bash [pnpm]
pnpm create vue
```

:::

The example project created by create-vue uses similar features to the ones we've seen here. You may find that a useful starting point for exploring the features introduced in the next few pages of this guide.

## Conventions in this guide

### Single-File Components

Vue Router is most commonly used in applications built using a bundler (e.g. Vite) and [SFCs](https://vuejs.org/guide/introduction.html#single-file-components) (i.e. `.vue` files). Most of the examples in this guide will be written in that style, but Vue Router itself doesn't require you to use build tools or SFCs.

For example, if you're using the *global builds* of [Vue](https://vuejs.org/guide/quick-start.html#using-vue-from-cdn) and [Vue Router](../installation#Direct-Download-CDN), the libraries are exposed via global objects, rather than imports:

```js
const { createApp } = Vue
const { createRouter, createWebHistory } = VueRouter
```

### Component API style

Vue Router can be used with both the Composition API and the Options API. Where relevant, the examples in this guide will show components written in both styles. Composition API examples will typically use `<script setup>`, rather than an explicit `setup` function.

If you need a refresher about the two styles, see [Vue - API Styles](https://vuejs.org/guide/introduction.html#api-styles).

### `router` and `route`

Throughout the guide, we will often refer to the router instance as `router`. This is the object returned by `createRouter()`. How you access that object in your application will depend on the context. For example, in a component using the Composition API, it can be accessed by calling `useRouter()`. With the Options API, it can be accessed using `this.$router`.

Similarly, the current route will be referred to as `route`. It can be accessed in components using `useRoute()` or `this.$route`, depending on which API the component is using.

### `RouterView` and `RouterLink`

The components `RouterView` and `RouterLink` are both [registered globally](https://vuejs.org/guide/components/registration.html#global-registration), so they don't need to be imported before using them in component templates. However, if you prefer, you can import them locally, e.g. `import { RouterLink } from 'vue-router'`.

In templates, component names can be written in either PascalCase or kebab-case. Vue's template compiler supports either format, so `<RouterView>` and `<router-view>` are usually equivalent. You should follow whatever convention is used within your project.

If you're using in-DOM templates then [the usual caveats](https://vuejs.org/guide/essentials/component-basics.html#in-dom-template-parsing-caveats) apply: component names must be written in kebab-case and self-closing tags are not supported. So rather than writing `<RouterView />`, you would need to use `<router-view></router-view>` instead.

---

---
url: /file-based-routing/hmr.md
---
# Hot Module Replacement

When using `definePage()` and `<route>` blocks, it's possible to enable Hot Module Replacement (HMR) for your routes **and avoid the need of reloading the page or the server** when you make changes to your routes.

Enabling HMR is **strongly recommended** and currently **only works with Vite**.

```ts [src/router.ts]
import { createRouter, createWebHistory } from 'vue-router'
import {
  routes,
  handleHotUpdate, // [!code ++]
} from 'vue-router/auto-routes'

export const router = createRouter({
  history: createWebHistory(),
  routes,
})

// This will update routes at runtime without reloading the page
if (import.meta.hot) { // [!code ++]
  handleHotUpdate(router) // [!code ++]
} // [!code ++]
```

## Runtime routes

If you add routes at runtime, you will have to add them within a callback to ensure they are added during development.

```ts [src/router.ts]
import { createRouter, createWebHistory } from 'vue-router'
import { routes, handleHotUpdate } from 'vue-router/auto-routes'

export const router = createRouter({
  history: createWebHistory(),
  routes,
})

function addRedirects() {
  router.addRoute({
    path: '/new-about',
    redirect: '/about?from=/new-about',
  })
}

if (import.meta.hot) {
  handleHotUpdate(router, (newRoutes) => { // [!code ++]
    addRedirects() // [!code ++]
  }) // [!code ++]
} else {
  // production
  addRedirects()
}
```

This is **optional**, you can also just reload the page.

---

---
url: /installation.md
---
# Installation

## Package managers

If you have an existing project that uses a JavaScript package manager, you can install Vue Router from the npm registry:

::: code-group

```bash [npm]
npm install vue-router@4
```

```bash [yarn]
yarn add vue-router@4
```

```bash [pnpm]
pnpm add vue-router@4
```

```bash [bun]
bun add vue-router@4
```

:::

If you're starting a new project, you might find it easier to use the [create-vue](https://github.com/vuejs/create-vue) scaffolding tool, which creates a Vite-based project with the option to include Vue Router:

::: code-group

```bash [npm]
npm create vue@latest
```

```bash [yarn]
yarn create vue
```

```bash [pnpm]
pnpm create vue
```

```bash [bun]
bun create vue
```

:::

You'll be prompted with some questions about the kind of project you want to create. If you choose to install Vue Router, the example application will also demonstrate some of Vue Router's core features.

Projects using package managers will typically use ES modules to access Vue Router, e.g. `import { createRouter } from 'vue-router'`.

## Direct Download / CDN

<https://unpkg.com/vue-router@4>

[Unpkg.com](https://unpkg.com) provides npm-based CDN links. The above link will always point to the latest release on npm. You can also use a specific version/tag via URLs like `https://unpkg.com/vue-router@4.0.15/dist/vue-router.global.js`.

This will expose Vue Router via a global `VueRouter` object, e.g. `VueRouter.createRouter(...)`.

---

---
url: /introduction.md
---
# Introduction

Watch a Free Vue Router Video Course

Vue Router is the official router for [Vue.js](https://vuejs.org). It deeply integrates with Vue.js core to make building Single Page Applications with Vue.js a breeze. Features include:

* Nested routes mapping
* Dynamic Routing
* Modular, component-based router configuration
* Route params, query, wildcards
* View transition effects powered by Vue.js' transition system
* Fine-grained navigation control
* Links with automatic active CSS classes
* HTML5 history mode or hash mode
* Customizable Scroll Behavior
* Proper encoding for URLs

[Get started](./guide/) or play with the [playground](https://github.com/vuejs/router/tree/main/packages/playground) (see [`README.md`](https://github.com/vuejs/router) to run them).

---

---
url: /guide/advanced/lazy-loading.md
---
# Lazy Loading Routes

When building apps with a bundler, the JavaScript bundle can become quite large, and thus affect the page load time. It would be more efficient if we can split each route's components into separate chunks, and only load them when the route is visited.

Vue Router supports [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) out of the box, meaning you can replace static imports with dynamic ones:

```js
// replace
// import UserDetails from './views/UserDetails.vue'
// with
const UserDetails = () => import('./views/UserDetails.vue')

const router = createRouter({
  // ...
  routes: [
    { path: '/users/:id', component: UserDetails },
    // or use it directly in the route definition
    { path: '/users/:id', component: () => import('./views/UserDetails.vue') },
  ],
})
```

The `component` (and `components`) option accepts a function that returns a Promise of a component and Vue Router **will only fetch it when entering the page for the first time**, then use the cached version. Which means you can also have more complex functions as long as they return a Promise:

```js
const UserDetails = () =>
  Promise.resolve({
    /* component definition */
  })
```

In general, it's a good idea **to always use dynamic imports** for all your routes.

When using a bundler like Vite or webpack, this will automatically benefit from [code splitting](https://webpack.js.org/guides/code-splitting/).

## Relationship to async components

Vue Router's lazy loading may appear similar to Vue's [async components](https://vuejs.org/guide/components/async.html), but they are distinct features. Do **not** use async components as route components. An async component can still be used inside a route component but the route component itself should just be a function.

## Relationship to functional components

While not common, it is possible to use a [functional component](https://vuejs.org/guide/extras/render-function.html#functional-components) as a route component. However, Vue Router needs some way to differentiate between functional components and lazy loading. To use a functional component we must give the function a `displayName`:

```ts
const AboutPage: FunctionalComponent = () => {
  return h('h1', {}, 'About')
}
AboutPage.displayName = 'AboutPage'
```

## Grouping Components in the Same Chunk

We may want to group all the components nested under the same route into the same chunk, so they can all be loaded with a single request.

### With Vite

We can define the chunks under the [`rollupOptions`](https://vite.dev/config/build-options.html#build-rollupoptions):

```js [vite.config.js]
export default defineConfig({
  build: {
    rollupOptions: {
      // https://rollupjs.org/guide/en/#outputmanualchunks
      output: {
        manualChunks: {
          'group-user': [
            './src/UserDetails',
            './src/UserDashboard',
            './src/UserProfileEdit',
          ],
        },
      },
    },
  },
})
```

### With webpack

We can specify the [chunk name](https://webpack.js.org/api/module-methods/#webpackchunkname) using a special comment syntax:

```js
const UserDetails = () =>
  import(/* webpackChunkName: "group-user" */ './UserDetails.vue')
const UserDashboard = () =>
  import(/* webpackChunkName: "group-user" */ './UserDashboard.vue')
const UserProfileEdit = () =>
  import(/* webpackChunkName: "group-user" */ './UserProfileEdit.vue')
```

webpack will group any async module with the same chunk name into the same async chunk.

---

---
url: /data-loaders/organization.md
---
# Loaders Organization

While most examples show loaders defined in the same file as the page component, it's possible to define them in separate files and import them in the page component. This flexibility allows you to control not only the codebase organization but also **how chunks are split**.

If a loader is used in multiple pages, it might be a better idea to extract it to a separate file instead of exporting it in one page and importing it in the others. This is because pages importing it will usually load the whole page component chunk in order to get the loader.

::: code-group

```ts [loaders/issues.ts]
import { defineBasicLoader } from 'vue-router/experimental'
import { getIssuesByProjectId } from '@/api'

export const useProjectIssues = defineBasicLoader('/[projectId]/issues', to =>
  getIssuesByProjectId(to.params.projectId)
)
```

```vue{2-3,7} [pages/[projectId]/issues.vue]
<script lang="ts">
import { useProjectIssues } from '@/loaders/issues'
export { useProjectIssues }
</script>

<script setup lang="ts">
const { data: issues } = useProjectIssues()
</script>
```

```vue{2,4,9} [pages/[projectId]/insights.vue]
<script lang="ts">
import { useProjectIssues } from '@/loaders/issues'
import { useProjectPullRequests } from '@/loaders/pull-requests'
export { useProjectIssues, useProjectPullRequests }
</script>

<script setup lang="ts">
const { data: issues } = useProjectIssues()
const { data: pullRequests } = useProjectPullRequests()
</script>
```

:::

In the example above, the `useProjectIssues` loader is defined in a separate file and imported in two different pages, `pages/[projectId]/issues.vue` and `pages/[projectId]/insights.vue`. They both use the same data but present it in a different way so there is no reason to create two different loaders for issues. By extracting the loader into a separate file, we ensure an optimal chunk split.

When using this pattern, remember to **export the loader** in all the page components that use it. This is what allows the router to await the loader before rendering the page.

## Usage outside of page components

Until now, we have only seen loaders used in page components. However, one of the benefits of using loaders is that they can be **reused in many parts of your application**, just like regular composables. This will not only eliminate code duplication but also ensure an optimal and performant data fetching by **deduplicating requests and sharing the data**.

To use a loader outside of a page component, you can simply **import it** and use it like any other composable, without the need to export it.

```vue
<script setup lang="ts">
// You can even import it from the page component
import { useProjectIssues } from '@/pages/[projectId]/issues.vue'

const { data: issues } = useProjectIssues()
</script>
```

::: tip

When using a loader in a non-page component, you must **export the loader** from the page components where it is used. If you only import and use the loader in a regular component, the router will not recognize it and won't trigger or await it during navigation.

:::

## Nested Routes

When defining nested routes, you don't need to worry about exporting the loader in both the parent and the child components. This will be automatically optimized for you and the loader will be shared between the parent and the child components.
Because of this, it's simpler to **always export data loaders** in the page component where **they are used**.

---

---
url: /guide/migration.md
---
# Migrating from Vue 2

Most of Vue Router API has remained unchanged during its rewrite from v3 (for Vue 2) to v4 (for Vue 3) but there are still a few breaking changes that you might encounter while migrating your application. This guide is here to help you understand why these changes happened and how to adapt your application to make it work with Vue Router 4.

## Breaking Changes

Changes are ordered by their usage. It is therefore recommended to follow this list in order.

### new Router becomes createRouter

Vue Router is no longer a class but a set of functions. Instead of writing `new Router()`, you now have to call `createRouter`:

```js
// previously was
// import Router from 'vue-router'
import { createRouter } from 'vue-router'

const router = createRouter({
  // ...
})
```

### New `history` option to replace `mode`

The `mode: 'history'` option has been replaced with a more flexible one named `history`. Depending on which mode you were using, you will have to replace it with the appropriate function:

* `"history"`: `createWebHistory()`
* `"hash"`: `createWebHashHistory()`
* `"abstract"`: `createMemoryHistory()`

Here is a full snippet:

```js
import { createRouter, createWebHistory } from 'vue-router'
// there is also createWebHashHistory and createMemoryHistory

createRouter({
  history: createWebHistory(),
  routes: [],
})
```

On SSR, you need to manually pass the appropriate history:

```js
// router.js
let history = isServer ? createMemoryHistory() : createWebHistory()
let router = createRouter({ routes, history })
// somewhere in your server-entry.js
router.push(req.url) // request url
router.isReady().then(() => {
  // resolve the request
})
```

**Reason**: enable tree shaking of non used histories as well as implementing custom histories for advanced use cases like native solutions.

### Moved the `base` option

The `base` option is now passed as the first argument to `createWebHistory` (and other histories):

```js
import { createRouter, createWebHistory } from 'vue-router'
createRouter({
  history: createWebHistory('/base-directory/'),
  routes: [],
})
```

### Removal of the `fallback` option

The `fallback` option is no longer supported when creating the router:

```diff
-new VueRouter({
+createRouter({
-  fallback: false,
// other options...
})
```

**Reason**: All browsers supported by Vue support the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API), allowing us to avoid hacks around modifying `location.hash` and directly use `history.pushState()`.

### Removed `*` (star or catch all) routes

Catch all routes (`*`, `/*`) must now be defined using a parameter with a custom regex:

```js
const routes = [
  // pathMatch is the name of the param, e.g., going to /not/found yields
  // { params: { pathMatch: ['not', 'found'] }}
  // this is thanks to the last *, meaning repeated params and it is necessary if you
  // plan on directly navigating to the not-found route using its name
  { path: '/:pathMatch(.*)*', name: 'not-found', component: NotFound },
  // if you omit the last `*`, the `/` character in params will be encoded when resolving or pushing
  { path: '/:pathMatch(.*)', name: 'bad-not-found', component: NotFound },
]
// bad example if using named routes:
router.resolve({
  name: 'bad-not-found',
  params: { pathMatch: 'not/found' },
}).href // '/not%2Ffound'
// good example:
router.resolve({
  name: 'not-found',
  params: { pathMatch: ['not', 'found'] },
}).href // '/not/found'
```

:::tip
You don't need to add the `*` for repeated params if you don't plan to directly push to the not found route using its name. If you call `router.push('/not/found/url')`, it will provide the right `pathMatch` param.
:::

**Reason**: Vue Router doesn't use `path-to-regexp` anymore, instead it implements its own parsing system that allows route ranking and enables dynamic routing. Since we usually add one single catch-all route per project, there is no big benefit in supporting a special syntax for `*`. The encoding of params is encoding across routes, without exception to make things easier to predict.

### The `currentRoute` property is now a `ref()`

Previously the properties of the [`currentRoute`](https://v3.router.vuejs.org/api/#router-currentroute) object on a router instance could be accessed directly.

With the introduction of vue-router v4, the underlying type of the `currentRoute` object on the router instance has changed to `Ref<RouteLocationNormalizedLoaded>`, which comes from the newer [reactivity fundamentals](https://vuejs.org/guide/essentials/reactivity-fundamentals.html) introduced in Vue 3.

While this doesn't change anything if you're reading the route with `useRoute()` or `this.$route`, if you're accessing it directly on the router instance, you will need to access the actual route object via `currentRoute.value`:

```ts
const { page } = router.currentRoute.query // [!code --]
const { page } = router.currentRoute.value.query // [!code ++]
```

### Replaced `onReady` with `isReady`

The existing `router.onReady()` function has been replaced with `router.isReady()` which doesn't take any argument and returns a Promise:

```js
// replace
router.onReady(onSuccess, onError)
// with
router.isReady().then(onSuccess).catch(onError)
// or use await:
try {
  await router.isReady()
  // onSuccess
} catch (err) {
  // onError
}
```

### `scrollBehavior` changes

The object returned in `scrollBehavior` is now similar to [`ScrollToOptions`](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions): `x` is renamed to `left` and `y` is renamed to `top`. See [RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0035-router-scroll-position.md).

**Reason**: making the object similar to `ScrollToOptions` to make it feel more familiar with native JS APIs and potentially enable future new options.

### `<router-view>`, `<keep-alive>`, and `<transition>`

`transition` and `keep-alive` must now be used **inside** of `RouterView` via the `v-slot` API:

```vue-html
<router-view v-slot="{ Component }">
  <transition>
    <keep-alive>
      <component :is="Component" />
    </keep-alive>
  </transition>
</router-view>
```

**Reason**: This was a necessary change. See the [related RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0034-router-view-keep-alive-transitions.md).

### Removal of `append` prop in `<router-link>`

The `append` prop has been removed from `<router-link>`. You can manually concatenate the value to an existing `path` instead:

```vue-html
replace
<router-link to="child-route" append>to relative child</router-link>
with
<router-link :to="append($route.path, 'child-route')">
  to relative child
</router-link>
```

You must define a global `append` function on your *App* instance:

```js
app.config.globalProperties.append = (path, pathToAppend) =>
  path + (path.endsWith('/') ? '' : '/') + pathToAppend
```

**Reason**: `append` wasn't used very often, is easy to replicate in user land.

### Removal of `event` and `tag` props in `<router-link>`

Both `event`, and `tag` props have been removed from `<router-link>`. You can use the [`v-slot` API](/guide/advanced/composition-api#uselink) to fully customize `<router-link>`:

```vue-html
replace
<router-link to="/about" tag="span" event="dblclick">About Us</router-link>
with
<router-link to="/about" custom v-slot="{ navigate }">
  <span @click="navigate" @keypress.enter="navigate" role="link">About Us</span>
</router-link>
```

**Reason**: These props were often used together to use something different from an `<a>` tag but were introduced before the `v-slot` API and are not used enough to justify adding to the bundle size for everybody.

### Removal of the `exact` prop in `<router-link>`

The `exact` prop has been removed because the caveat it was fixing is no longer present so you should be able to safely remove it. There are however two things you should be aware of:

* Routes are now active based on the route records they represent instead of the generated route location objects and their `path`, `query`, and `hash` properties
* Only the `path` section is matched, `query`, and `hash` aren't taken into account anymore

If you wish to customize this behavior, e.g. take into account the `hash` section, you should use the [`v-slot` API](/guide/advanced/composition-api#useLink) to extend `<router-link>`.

**Reason**: See the [RFC about active matching](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0028-router-active-link.md#summary) changes for more details.

### Navigation guards in mixins are ignored

At the moment navigation guards in mixins are not supported. You can track its support at [vue-router#454](https://github.com/vuejs/router/issues/454).

### Removal of `router.match` and changes to `router.resolve`

Both `router.match`, and `router.resolve` have been merged together into `router.resolve` with a slightly different signature. [Refer to the API](/api/interfaces/Router.md#resolve) for more details.

**Reason**: Uniting multiple methods that were used for the same purpose.

### Removal of `router.getMatchedComponents()`

The method `router.getMatchedComponents` is now removed as matched components can be retrieved from `router.currentRoute.value.matched`:

```js
router.currentRoute.value.matched.flatMap(record =>
  Object.values(record.components)
)
```

**Reason**: This method was only used during SSR and is a one liner that can be done by the user.

### Redirect records cannot use special paths

Previously, a non documented feature allowed to set a redirect record to a special path like `/events/:id` and it would reuse an existing param `id`. This is no longer possible and there are two options:

* Using the name of the route without the param: `redirect: { name: 'events' }`. Note this won't work if the param `:id` is optional
* Using a function to recreate the new location based on the target: `redirect: to => ({ name: 'events', params: to.params })`

**Reason**: This syntax was rarely used and *another way of doing things* that wasn't shorter enough compared to the versions above while introducing some complexity and making the router heavier.

### **All** navigations are now always asynchronous

All navigations, including the first one, are now asynchronous, meaning that, if you use a `transition`, you may need to wait for the router to be *ready* before mounting the app:

```js
app.use(router)
// Note: on Server Side, you need to manually push the initial location
router.isReady().then(() => app.mount('#app'))
```

Otherwise there will be an initial transition as if you provided the `appear` prop to `transition` because the router displays its initial location (nothing) and then displays the first location.

Note that **if you have navigation guards upon the initial navigation**, you might not want to block the app render until they are resolved unless you are doing Server Side Rendering. In this scenario, not waiting the router to be ready to mount the app would yield the same result as in Vue 2.

### Removal of `router.app`

`router.app` used to represent the last root component (Vue instance) that injected the router. Vue Router can now be safely used by multiple Vue applications at the same time. You can still add it when using the router:

```js
app.use(router)
router.app = app
```

You can also extend the TypeScript definition of the `Router` interface to add the `app` property.

**Reason**: Vue 3 applications do not exist in Vue 2 and now we properly support multiple applications using the same Router instance, so having an `app` property would have been misleading because it would have been the application instead of the root instance.

### Passing content to route components' `<slot>`

Before you could directly pass a template to be rendered by a route components' `<slot>` by nesting it under a `<router-view>` component:

```vue-html
<router-view>
  <p>In Vue Router 3, I render inside the route component</p>
</router-view>
```

Because of the introduction of the `v-slot` api for `<router-view>`, you must pass it to the `<component>` using the `v-slot` API:

```vue-html
<router-view v-slot="{ Component }">
  <component :is="Component">
    <p>In Vue Router 3, I render inside the route component</p>
  </component>
</router-view>
```

### Removal of `parent` from route locations

The `parent` property has been removed from normalized route locations (`this.$route` and object returned by `router.resolve`). You can still access it via the `matched` array:

```js
const parent = this.$route.matched[this.$route.matched.length - 2]
```

**Reason**: Having `parent` and `children` creates unnecessary circular references while the properties could be retrieved already through `matched`.

### Removal of `pathToRegexpOptions`

The `pathToRegexpOptions` and `caseSensitive` properties of route records have been replaced with `sensitive` and `strict` options for `createRouter()`. They can now also be directly passed when creating the router with `createRouter()`. Any other option specific to `path-to-regexp` has been removed as `path-to-regexp` is no longer used to parse paths.

### Removal of unnamed parameters

Due to the removal of `path-to-regexp`, unnamed parameters are no longer supported:

* `/foo(/foo)?/suffix` becomes `/foo/:_(foo)?/suffix`
* `/foo(foo)?` becomes `/foo:_(foo)?`
* `/foo/(.*)` becomes `/foo/:_(.*)`

:::tip
Note you can use any name instead of `_` for the param. The point is to provide one.
:::

### Usage of `history.state`

Vue Router saves information on the `history.state`. If you have any code manually calling `history.pushState()`, you should likely avoid it or refactor it with a regular `router.push()` and a `history.replaceState()`:

```js
// replace
history.pushState(myState, '', url)
// with
await router.push(url)
history.replaceState({ ...history.state, ...myState }, '')
```

Similarly, if you were calling `history.replaceState()` without preserving the current state, you will need to pass the current `history.state`:

```js
// replace
history.replaceState({}, '', url)
// with
history.replaceState(history.state, '', url)
```

**Reason**: We use the history state to save information about the navigation like the scroll position, previous location, etc.

### `routes` option is required in `options`

The property `routes` is now required in `options`.

```js
createRouter({ routes: [] })
```

**Reason**: The router is designed to be created with routes even though you can add them later on. You need at least one route in most scenarios and this is written once per app in general.

### Non existent named routes

Pushing or resolving a non existent named route throws an error:

```js
// Oops, we made a typo in name
router.push({ name: 'homee' }) // throws
router.resolve({ name: 'homee' }) // throws
```

**Reason**: Previously, the router would navigate to `/` but display nothing (instead of the home page). Throwing an error makes more sense because we cannot produce a valid URL to navigate to.

### Missing required `params` on named routes

Pushing or resolving a named route without its required params will throw an error:

```js
// given the following route:
const routes = [{ path: '/users/:id', name: 'user', component: UserDetails }]

// Missing the `id` param will fail
router.push({ name: 'user' })
router.resolve({ name: 'user' })
```

**Reason**: Same as above.

### Named children routes with an empty `path` no longer appends a slash

Given any nested named route with an empty `path`:

```js
const routes = [
  {
    path: '/dashboard',
    name: 'dashboard-parent',
    component: DashboardParent,
    children: [
      { path: '', name: 'dashboard', component: DashboardDefault },
      {
        path: 'settings',
        name: 'dashboard-settings',
        component: DashboardSettings,
      },
    ],
  },
]
```

Navigating or resolving to the named route `dashboard` will now produce a URL **without a trailing slash**:

```js
router.resolve({ name: 'dashboard' }).href // '/dashboard'
```

This has an important side effect about children `redirect` records like these:

```js
const routes = [
  {
    path: '/parent',
    component: Parent,
    children: [
      // this would now redirect to `/home` instead of `/parent/home`
      { path: '', redirect: 'home' },
      { path: 'home', component: Home },
    ],
  },
]
```

Note this will work if `path` was `/parent/` as the relative location `home` to `/parent/` is indeed `/parent/home` but the relative location of `home` to `/parent` is `/home`.

**Reason**: This is to make trailing slash behavior consistent: by default all routes allow a trailing slash. It can be disabled by using the `strict` option and manually appending (or not) a slash to the routes.

### `$route` properties Encoding

Decoded values in `params`, `query`, and `hash` are now consistent no matter where the navigation is initiated (older browsers will still produce unencoded `path` and `fullPath`). The initial navigation should yield the same results as in-app navigations.

Given any [normalized route location](/api/#RouteLocationNormalized):

* Values in `path`, `fullPath` are not decoded anymore. They will appear as provided by the browser (most browsers provide them encoded). e.g. directly writing on the address bar `https://example.com/hello world` will yield the encoded version: `https://example.com/hello%20world` and both `path` and `fullPath` will be `/hello%20world`.
* `hash` is now decoded, that way it can be copied over: `router.push({ hash: $route.hash })` and be used directly in [scrollBehavior](/api/interfaces/RouterOptions.md#scrollBehavior)'s `el` option.
* When using `push`, `resolve`, and `replace` and providing a `string` location or a `path` property in an object, **it must be encoded** (like in the previous version). On the other hand, `params`, `query` and `hash` must be provided in its unencoded version.
* The slash character (`/`) is now properly decoded inside `params` while still producing an encoded version on the URL: `%2F`.

**Reason**: This allows to easily copy existing properties of a location when calling `router.push()` and `router.resolve()`, and make the resulting route location consistent across browsers. `router.push()` is now idempotent, meaning that calling `router.push(route.fullPath)`, `router.push({ hash: route.hash })`, `router.push({ query: route.query })`, and `router.push({ params: route.params })` will not create extra encoding.

### `$router.push()` and `$router.replace()` - `onComplete` and `onAbort` callbacks

Previously, `$router.push()` and `$router.replace()` accepted two callbacks, `onComplete` and `onAbort`, as second and third arguments. They were called after a navigation based on the result. With the introduction of a Promise based API, these callbacks are redundant and have been removed. See [Navigation Failures](/guide/advanced/navigation-failures.md) for more information on how to detect successful and failed navigations.

**Reason**: Reduce library size by adapting to established JS standards (Promises).

### TypeScript changes

To make typings more consistent and expressive, some types have been renamed:

| `vue-router@3` | `vue-router@4`          |
| -------------- | ----------------------- |
| RouteConfig    | RouteRecordRaw          |
| Location       | RouteLocation           |
| Route          | RouteLocationNormalized |

## New Features

Some of new features to keep an eye on in Vue Router 4 include:

* [Dynamic Routing](../advanced/dynamic-routing.md)
* [Composition API](../advanced/composition-api.md)

---

---
url: /guide/migration/v4-to-v5.md
---
# Migrating to Vue Router 5

> \[!TIP]
> Vue Router 5 is a transition release that merges [unplugin-vue-router](https://uvr.esm.is) (file-based routing) into the core package. **If you're using Vue Router 4 without unplugin-vue-router, there are no breaking changes** - you can upgrade without any code modifications. The only exception is that the *iife* build no longer includes `@vue/devtools-api` because it has been upgraded to v8 and does not expose an IIFE build itself. You can track that change in [this issue](https://github.com/vuejs/devtools/issues/989).
>
> Vue Router 6 will be ESM-only and remove deprecated APIs. v5 gives you time to prepare for that transition.

## For Vue Router 4 Users (without file-based routing)

No breaking changes. Update your dependency and you're done:

```bash
pnpm update vue-router@5
```

## From unplugin-vue-router

If you were using unplugin-vue-router for file-based routing, migration is mostly import path changes.

### Migration Checklist (TLDR)

### 1. Update Dependencies

```bash
pnpm remove unplugin-vue-router
pnpm update vue-router@5
```

### 2. Update Imports

**Vite plugin:**

```ts
import VueRouter from 'unplugin-vue-router/vite' // [!code --]
import VueRouter from 'vue-router/vite' // [!code ++]
```

Other build tools (Webpack, Rollup, esbuild) import from `vue-router/unplugin`:

```ts
import VueRouter from 'vue-router/unplugin'

VueRouter.webpack({
  /* ... */
})
VueRouter.rollup({
  /* ... */
})
// etc.
```

**Data loaders:**

```ts
import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic' // [!code --]
import { defineColadaLoader } from 'unplugin-vue-router/data-loaders/pinia-colada' // [!code --]
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders' // [!code --]
import { defineBasicLoader, DataLoaderPlugin } from 'vue-router/experimental' // [!code ++]
import { defineColadaLoader } from 'vue-router/experimental/pinia-colada' // [!code ++]
```

**Unplugin utilities (for custom integrations):**

```ts
import {
  VueRouterAutoImports,
  EditableTreeNode,
  createTreeNodeValue,
  createRoutesContext,
  getFileBasedRouteName,
  getPascalCaseRouteName,
} from 'unplugin-vue-router' // [!code --]
} from 'vue-router/unplugin' // [!code ++]
```

**Types:**

```ts
import type { Options, EditableTreeNode } from 'unplugin-vue-router' // [!code --]
import type { Options, EditableTreeNode } from 'vue-router/unplugin' // [!code ++]
```

**Volar plugins:**

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "rootDir": ".",
  },
  "vueCompilerOptions": {
    "plugins": [
      "unplugin-vue-router/volar/sfc-typed-router", // [!code --]
      "unplugin-vue-router/volar/sfc-route-blocks", // [!code --]
    ],
  },
}
```

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "rootDir": ".",
  },
  "vueCompilerOptions": {
    "plugins": [
      "vue-router/volar/sfc-typed-router", // [!code ++]
      "vue-router/volar/sfc-route-blocks", // [!code ++]
    ],
  },
}
```

### 3. Update vite.config.ts and tsconfig.json

It's recommended to move the generated types file inside `src/` and rename it to `route-map.d.ts`, as it's automatically included by most setups:

```ts
// vite.config.ts
export default defineConfig({
  plugins: [
    VueRouter({
      dts: 'src/route-map.d.ts', // [!code ++]
    }),
    Vue(),
  ],
})
```

Remove the old client types reference. These were either added to an `env.d.ts`:

```ts
/// <reference types="unplugin-vue-router/client" /> // [!code --]
```

or to your `tsconfig.json`:

```jsonc
{
  "include": [
    "./typed-router.d.ts", // [!code --]
    "unplugin-vue-router/client", // [!code --]
    // ...
  ],
}
```

## Troubleshooting

**Types not recognized:** Restart your TypeScript server and check that your generated types file (e.g., `src/route-map.d.ts`) is included in your tsconfig.

**Routes not generating:** Verify your `routesFolder` path and check file extensions.

**Route name errors:** Use the generated names or add `definePage({ name: 'custom-name' })` to your components.

## New Exports Reference

| Export                                 | Purpose                            |
| -------------------------------------- | ---------------------------------- |
| `vue-router`                           | Main API (unchanged)               |
| `vue-router/vite`                      | Vite plugin                        |
| `vue-router/auto-routes`               | Generated routes                   |
| `vue-router/unplugin`                  | Webpack/Rollup/esbuild + utilities |
| `vue-router/experimental`              | Data loaders                       |
| `vue-router/experimental/pinia-colada` | Pinia Colada loader                |

---

---
url: /guide/essentials/named-routes.md
---
# Named Routes

When creating a route, we can optionally give the route a `name`:

```js
const routes = [
  {
    path: '/user/:username',
    name: 'profile', // [!code highlight]
    component: User,
  },
]
```

We can then use the `name` instead of the `path` when passing the `to` prop to `<router-link>`:

```vue-html
<router-link :to="{ name: 'profile', params: { username: 'erina' } }">
  User profile
</router-link>
```

The example above would create a link to `/user/erina`.

* [See it in the Playground](https://play.vuejs.org/#eNqtVVtP2zAU/itWNqlFauNNIB6iUMEQEps0NjH2tOzBtKY1JLZlO6VTlP++4+PcelnFwyRofe7fubaKCiZk/GyjJBKFVsaRiswNZ45faU1q8mRUQUbrko8yuaPwlRfK/LkV1sHXpGHeq9JxMzScGmT19t5xkMaUaR1vOb9VBe+kntgWXz2Cs06O1LbCTwvRW7knGnEm50paRwIYcrEFd1xlkpBVyCQ5lN74ZOJV0Nom5JcnCFRCM7dKyIiOJkSygsNzBZiBmivAI7l0SUipRvuhCfPge7uWHBiGZPctS0iLJv7T2/YutFFPIt+JjgUJPn7DZ32CtWg7PIZ/4BASg7txKE6gC1VKNx69gw6NTqJJ1HQK5iR1vNA52M+8Yrr6OLuD+AuCtbQpBQYK9Oy6NAZAhLI1KKuKvEc69jSp65Tqw/oh3V7f00P9MsdveOWiecE75DDNhXwhiVMXWVRttYbUWdRpE2xOZ0sHxq1v2jl/a5jQyZ042Mv/HKjvt2aGFTCXFWmnAsTcCMkAxw4SHIjG9E2AUtpUusWyFvyVUGCltBsFmJB2W/dHZCHWswdYLwJ/XiulnrNr323zcQeodthDuAHTgmm4aEqCH1zsrBHYLIISheyyqD9Nnp1FK+e0TSgtpX5ZxrBBtNe4PItP4w8Q07oBN+a2mD4a9erPzDN4bzY1iy5BiS742imV2ynT4l8h9hQvz+Pz+COU/pGCdyrkgm/Qt3ddw/5Cms7CLXsSy50k/dJDT8037QTcuq1kWZ6r1y/Ic6bkHdD5is9fDvCf7SZA/m44ZLfmg+QcM0vugvjmxx3fwLsTFmpRwlwdE95zq/LSYwxqn0q5ANgDPUT7GXsm5PLB3mwcl7ZNygPFaqA+NvL6SOo93NP4bFDF9sfh+LThtgxvkF80fyxxy/Ac7U9i/RcYNWrd).

Using a `name` has various advantages:

* No hardcoded URLs.
* Automatic encoding of `params`.
* Avoids URL typos.
* Bypassing path ranking, e.g. to display a lower-ranked route that matches the same path.

Each name **must be unique** across all routes. If you add the same name to multiple routes, the router will only keep the last one. You can read more about this [in the Dynamic Routing](../advanced/dynamic-routing#Removing-routes) section.

There are various other parts of Vue Router that can be passed a location, e.g. the methods `router.push()` and `router.replace()`. We'll go into more detail about those methods in the guide to [programmatic navigation](./navigation). Just like the `to` prop, these methods also support passing a location by `name`:

```js
router.push({ name: 'profile', params: { username: 'erina' } })
```

---

---
url: /guide/essentials/named-views.md
---
# Named Views

Sometimes you need to display multiple views at the same time instead of nesting them, e.g. creating a layout with a `sidebar` view and a `main` view. This is where named views come in handy. Instead of having one single outlet in your view, you can have multiple and give each of them a name. A `router-view` without a name will be given `default` as its name.

```vue-html
<router-view class="view left-sidebar" name="LeftSidebar" />
<router-view class="view main-content" />
<router-view class="view right-sidebar" name="RightSidebar" />
```

A view is rendered by using a component, therefore multiple views require
multiple components for the same route. Make sure to use the `components` (with
an **s**) option:

```js
const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    {
      path: '/',
      components: {
        default: Home,
        // short for LeftSidebar: LeftSidebar
        LeftSidebar,
        // they match the `name` attribute on `<router-view>`
        RightSidebar,
      },
    },
  ],
})
```

A working demo of this example can be found [here](https://codesandbox.io/s/named-views-vue-router-4-examples-rd20l).

## Nested Named Views

It is possible to create complex layouts using named views with nested views. When doing so, you will also need to give nested `router-view` a name. Let's take a Settings panel example:

```
/settings/emails                                       /settings/profile
+-----------------------------------+                  +------------------------------+
| UserSettings                      |                  | UserSettings                 |
| +-----+-------------------------+ |                  | +-----+--------------------+ |
| | Nav | UserEmailsSubscriptions | |  +------------>  | | Nav | UserProfile        | |
| |     +-------------------------+ |                  | |     +--------------------+ |
| |     |                         | |                  | |     | UserProfilePreview | |
| +-----+-------------------------+ |                  | +-----+--------------------+ |
+-----------------------------------+                  +------------------------------+
```

* `Nav` is just a regular component
* `UserSettings` is the parent view component
* `UserEmailsSubscriptions`, `UserProfile`, `UserProfilePreview` are nested view components

**Note**: *Let's forget about how the HTML/CSS should look like to represent such layout and focus on the components used.*

The `<template>` section for `UserSettings` component in the above layout would look something like this:

```vue-html [UserSettings.vue]
<div>
  <h1>User Settings</h1>
  <NavBar />
  <router-view />
  <router-view name="helper" />
</div>
```

Then you can achieve the layout above with this route configuration:

```js
{
  path: '/settings',
  // You could also have named views at the top
  component: UserSettings,
  children: [
    {
      path: 'emails',
      component: UserEmailsSubscriptions
    },
    {
      path: 'profile',
      components: {
        default: UserProfile,
        helper: UserProfilePreview
      }
    }
  ]
}
```

A working demo of this example can be found [here](https://codesandbox.io/s/nested-named-views-vue-router-4-examples-re9yl?\&initialpath=%2Fsettings%2Femails).

---

---
url: /data-loaders/navigation-aware.md
---
# Navigation aware

Since the data fetching happens within a navigation guard, it's possible to control the navigation like in regular navigation guards:

* Thrown errors (or rejected Promises) cancel the navigation (same behavior as in a regular navigation guard) and are intercepted by [Vue Router's error handling](https://router.vuejs.org/api/interfaces/router.html#onerror)
* By calling `reroute()`, you can redirect or cancel the navigation

Any other returned value is considered as the *resolved data* and will appear in the `data` property.

## Controlling the navigation with `reroute()`

`reroute()` changes the current navigation from within a data loader. It accepts the same arguments as the [return value of a navigation guard](https://router.vuejs.org/guide/advanced/navigation-guards.html#Global-Before-Guards) **as long as it changes the navigation**. It doesn't accept `true` or `undefined` as these values do not change the navigation. It **throws internally** to immediately stop the loader execution.

```ts{1,6-8,16,18}
import { reroute } from 'vue-router/experimental'
import { defineBasicLoader } from 'vue-router/experimental'

export const useUserData = defineBasicLoader(
  async (to) => {
    // cancel the navigation for invalid IDs
    if (isInvalidId(to.params.id)) {
      reroute(false)
    }

    try {
      const user = await getUserById(to.params.id)

      return user
    } catch (error) {
      if (error.status === 404) {
        reroute({ name: 'not-found' })
      } else {
        throw error // aborts the router navigation
      }
    }
  }
)
```

::: tip

Since `reroute()` throws internally (its return type is `never`), you don't need to use `return` or `else` after calling it.

:::

## Consistent updates

During a navigation, data loaders are grouped together like a *pack*. If the navigation is canceled, none of the results are used. This avoids having partial data updates in a page and inconsistencies between the URL and the page content. On the other hand, if the navigation is successful, all the data loaders are resolved together and the data is only updated **once all the loaders are resolved**. This is true even for lazy loaders. This ensures that even if you have loaders that are really fast, the old data is not displayed until all the loaders are resolved and the new data is completely ready to be displayed.

## Lazy loaders

Apart from consistent updates, lazy loaders are not navigation-aware. They cannot control the navigation with errors or `reroute()`. They still start loading as soon as the navigation is initiated.

## Loading after the navigation

It's possible to not start loading the data until the navigation is done. To do this, simply [**do not attach the loader to the page**](./defining-loaders.md#disconnecting-a-loader-from-a-page). It will eventually start loading when the page is mounted.

---

---
url: /guide/advanced/navigation-guards.md
---
# Navigation Guards

As the name suggests, the navigation guards provided by Vue router are primarily used to guard navigations either by redirecting it or canceling it. There are a number of ways to hook into the route navigation process: globally, per-route, or in-component.

## Global Before Guards

You can register global before guards using `router.beforeEach`:

```js
const router = createRouter({ ... })

router.beforeEach((to, from) => {
  // ...
  // explicitly return false to cancel the navigation
  return false
})
```

Global before guards are called in creation order, whenever a navigation is triggered. Guards may be resolved asynchronously, and the navigation is considered **pending** before all hooks have been resolved.

Every guard function receives two arguments:

* **`to`**: the target route location [in a normalized format](../../api/#RouteLocationNormalized) being navigated to.
* **`from`**: the current route location [in a normalized format](../../api/#RouteLocationNormalized) being navigated away from.

And can optionally return any of the following values:

* `false`: cancel the current navigation. If the browser URL was changed (either manually by the user or via back button), it will be reset to that of the `from` route.
* A [Route Location](../../api/#RouteLocationRaw): Redirect to a different location by passing a route location as if you were calling `router.push()`, which allows you to pass options like `replace: true` or `name: 'home'`. The current navigation is dropped and a new one is created with the same `from`.

  ```js
  router.beforeEach(async (to, from) => {
    if (
      // make sure the user is authenticated
      !isAuthenticated &&
      // ❗️ Avoid an infinite redirect
      to.name !== 'Login'
    ) {
      // redirect the user to the login page
      return { name: 'Login' }
    }
  })
  ```

It's also possible to throw an `Error` if an unexpected situation was met. This will also cancel the navigation and call any callback registered via [`router.onError()`](../../api/interfaces/Router.md#onError).

If nothing, `undefined` or `true` is returned, **the navigation is validated**, and the next navigation guard is called.

All of the things above **work the same way with `async` functions** and Promises:

```js
router.beforeEach(async (to, from) => {
  // canUserAccess() returns `true` or `false`
  const canAccess = await canUserAccess(to)
  if (!canAccess) return '/login'
})
```

### Optional third argument `next`

In previous versions of Vue Router, it was also possible to use a *third argument* `next`, this was a common source of mistakes and went through an [RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0037-router-return-guards.md#motivation) to remove it. However, it is still supported, meaning you can pass a third argument to any navigation guard. In that case, **you must call `next` exactly once** in any given pass through a navigation guard. It can appear more than once, but only if the logical paths have no overlap, otherwise the hook will never be resolved or produce errors. Here is **a bad example** of redirecting the user to `/login` if they are not authenticated:

```js
// BAD
router.beforeEach((to, from, next) => {
  if (to.name !== 'Login' && !isAuthenticated) next({ name: 'Login' })
  // if the user is not authenticated, `next` is called twice
  next()
})
```

Here is the correct version:

```js
// GOOD
router.beforeEach((to, from, next) => {
  if (to.name !== 'Login' && !isAuthenticated) next({ name: 'Login' })
  else next()
})
```

## Global Resolve Guards

You can register a global guard with `router.beforeResolve`. This is similar to `router.beforeEach` because it triggers on **every navigation**, but resolve guards are called right before the navigation is confirmed, **after all in-component guards and async route components are resolved**. Here is an example that ensures the user has given access to the Camera for routes that [have defined a custom meta](./meta.md) property `requiresCamera`:

```js
router.beforeResolve(async to => {
  if (to.meta.requiresCamera) {
    try {
      await askForCameraPermission()
    } catch (error) {
      if (error instanceof NotAllowedError) {
        // ... handle the error and then cancel the navigation
        return false
      } else {
        // unexpected error, cancel the navigation and pass the error to the global handler
        throw error
      }
    }
  }
})
```

`router.beforeResolve` is the ideal spot to fetch data or do any other operation that you want to avoid doing if the user cannot enter a page.

## Global After Hooks

You can also register global after hooks, however unlike guards, these hooks do not get a `next` function and cannot affect the navigation:

```js
router.afterEach((to, from) => {
  sendToAnalytics(to.fullPath)
})
```

They are useful for analytics, changing the title of the page, accessibility features like announcing the page and many other things.

They also reflect [navigation failures](./navigation-failures.md) as the third argument:

```js
router.afterEach((to, from, failure) => {
  if (!failure) sendToAnalytics(to.fullPath)
})
```

Learn more about navigation failures on [its guide](./navigation-failures.md).

## Global injections within guards

Since Vue 3.3, it is possible to use `inject()` within navigation guards. This is useful for injecting global properties like the [pinia stores](https://pinia.vuejs.org). Anything that is provided with `app.provide()` is also accessible within `router.beforeEach()`, `router.beforeResolve()`, `router.afterEach()`:

```ts [main.ts]
const app = createApp(App)
app.provide('global', 'hello injections')

// router.ts or main.ts
router.beforeEach((to, from) => {
  const global = inject('global') // 'hello injections'
  // a pinia store
  const userStore = useAuthStore()
  // ...
})
```

## Per-Route Guard

You can define `beforeEnter` guards directly on a route's configuration object:

```js
const routes = [
  {
    path: '/users/:id',
    component: UserDetails,
    beforeEnter: (to, from) => {
      // reject the navigation
      return false
    },
  },
]
```

`beforeEnter` guards **only trigger when entering the route**, they don't trigger when the `params`, `query` or `hash` change e.g. going from `/users/2` to `/users/3` or going from `/users/2#info` to `/users/2#projects`. They are only triggered when navigating **from a different** route.

You can also pass an array of functions to `beforeEnter`, this is useful when reusing guards for different routes:

```js
function removeQueryParams(to) {
  if (Object.keys(to.query).length)
    return { path: to.path, query: {}, hash: to.hash }
}

function removeHash(to) {
  if (to.hash) return { path: to.path, query: to.query, hash: '' }
}

const routes = [
  {
    path: '/users/:id',
    component: UserDetails,
    beforeEnter: [removeQueryParams, removeHash],
  },
  {
    path: '/about',
    component: UserDetails,
    beforeEnter: [removeQueryParams],
  },
]
```

When working with [nested routes](../essentials/nested-routes), both parent and child routes can use `beforeEnter`. When placed on a parent route, it won't be triggered when moving between children with that same parent. For example:

```js
const routes = [
  {
    path: '/user',
    beforeEnter() {
      // ...
    },
    children: [
      { path: 'list', component: UserList },
      { path: 'details', component: UserDetails },
    ],
  },
]
```

The `beforeEnter` in the example above won't be called when moving between `/user/list` and `/user/details`, as they share the same parent. If we put the `beforeEnter` guard directly on the `details` route instead, that would be called when moving between those two routes.

::: tip
It is possible to achieve similar behavior to per-route guards by using [route meta fields](./meta) and global navigation guards.
:::

## In-Component Guards

Finally, you can directly define route navigation guards inside route components (the ones passed to the router configuration)

### Using the Options API

You can add the following options to route components:

* `beforeRouteEnter`
* `beforeRouteUpdate`
* `beforeRouteLeave`

```vue
<script>
export default {
  beforeRouteEnter(to, from) {
    // called before the route that renders this component is confirmed.
    // does NOT have access to `this` component instance,
    // because it has not been created yet when this guard is called!
  },
  beforeRouteUpdate(to, from) {
    // called when the route that renders this component has changed, but this component is reused in the new route.
    // For example, given a route with params `/users/:id`, when we navigate between `/users/1` and `/users/2`,
    // the same `UserDetails` component instance will be reused, and this hook will be called when that happens.
    // Because the component is mounted while this happens, the navigation guard has access to `this` component instance.
  },
  beforeRouteLeave(to, from) {
    // called when the route that renders this component is about to be navigated away from.
    // As with `beforeRouteUpdate`, it has access to `this` component instance.
  },
}
</script>
```

The `beforeRouteEnter` guard does **NOT** have access to `this`, because the guard is called before the navigation is confirmed, thus the new entering component has not even been created yet.

However, you can access the instance by passing a callback to `next`. The callback will be called when the navigation is confirmed, and the component instance will be passed to the callback as the argument:

```js
beforeRouteEnter (to, from, next) {
  next(vm => {
    // access to component public instance via `vm`
  })
}
```

Note that `beforeRouteEnter` is the only guard that supports passing a callback to `next`. For `beforeRouteUpdate` and `beforeRouteLeave`, `this` is already available, so passing a callback is unnecessary and therefore *not supported*:

```js
beforeRouteUpdate (to, from) {
  // just use `this`
  this.name = to.params.name
}
```

The **leave guard** is usually used to prevent the user from accidentally leaving the route with unsaved edits. The navigation can be canceled by returning `false`.

```js
beforeRouteLeave (to, from) {
  const answer = window.confirm('Do you really want to leave? you have unsaved changes!')
  if (!answer) return false
}
```

### Using the Composition API

If you are writing your component using the Composition API, you can add update and leave guards through `onBeforeRouteUpdate` and `onBeforeRouteLeave` respectively. Please refer to the [Composition API section](./composition-api.md#navigation-guards) for more details.

## The Full Navigation Resolution Flow

1. Navigation triggered.
2. Call `beforeRouteLeave` guards in deactivated components.
3. Call global `beforeEach` guards.
4. Call `beforeRouteUpdate` guards in reused components.
5. Call `beforeEnter` in route configs.
6. Resolve async route components.
7. Call `beforeRouteEnter` in activated components.
8. Call global `beforeResolve` guards.
9. Navigation is confirmed.
10. Call global `afterEach` hooks.
11. DOM updates triggered.
12. Call callbacks passed to `next` in `beforeRouteEnter` guards with instantiated instances.

---

---
url: /data-loaders/nested-loaders.md
---
# Nested loaders

Sometimes, requests depend on other fetched data (e.g. fetching additional user information). For these scenarios, we can simply import the other loaders and use them **within a different loader**:

Call **and `await`** the loader inside the one that needs it, it will only be fetched once no matter how many times it is called during a navigation:

```ts twoslash
import 'vue-router/auto-routes'
import { defineBasicLoader } from 'vue-router/experimental'
// ---cut---
// import the loader for user information
import { useUserData } from './loaders/users'
import { getCommonFriends, getCurrentUser } from './api'

export const useUserCommonFriends = defineBasicLoader(async route => {
  // loaders must be awaited inside other loaders
  // .        ⤵
  const user = await useUserData()

  // fetch other data
  const me = await getCurrentUser()
  const commonFriends = await getCommonFriends(me.id, user.id)
  return { ...user, commonFriends }
})
```

You will notice here that we have two different usages for `useUserData()`:

* One that returns all the necessary information we need *synchronously* (not used here). This is the composable that we use in components
* A second version that **only returns a promise of the data**. This is the version used within data loaders that enables sequential fetching.

## Nested invalidation

Since `useUserCommonFriends()` loader calls `useUserData()`, if `useUserData()` is somehow *invalidated*, it will also automatically invalidate `useUserCommonFriends()`. This depends on the implementation of the loader and is not a requirement of the API.

::: warning
Two loaders cannot use each other as that would create a *dead lock*.
:::

This can get complex with multiple pages exposing the same loader and other pages using some of their *already exported* loaders within other loaders. But it's not an issue, **the user shouldn't need to handle anything differently**, loaders are still only called once:

```ts twoslash
import 'vue-router/auto-routes'
import { defineBasicLoader } from 'vue-router/experimental'
// ---cut---
import {
  getFriends,
  getCommonFriends,
  getUserById,
  getCurrentUser,
} from './api'

export const useUserData = defineBasicLoader('/users/[id]', async route => {
  return getUserById(route.params.id)
})

export const useCurrentUserData = defineBasicLoader(
  '/users/[id]',
  async route => {
    const me = await getCurrentUser()
    // imagine legacy APIs that cannot be grouped into one single fetch
    const friends = await getFriends(me.id)

    return { ...me, friends }
  }
)

export const useUserCommonFriends = defineBasicLoader(
  '/users/[id]',
  async route => {
    const user = await useUserData()
    const me = await useCurrentUserData()

    const friends = await getCommonFriends(user.id, me.id)
    return { ...me, commonFriends: { with: user, friends } }
  }
)
```

In the example above we are exporting multiple loaders but we don't need to care about the order in which they are called nor try optimizing them because **they are only called once and share the data**.

::: danger
**Caveat**: must call **and await** all nested loaders at the top of the parent loader (see `useUserData()` and `useCurrentUserData()`). You cannot put a different regular `await` in between. If you really need to await **anything that isn't a loader** in between, wrap the promise with `withDataContext()` to ensure the loader context is properly restored:

```ts{3}
export const useUserCommonFriends = defineBasicLoader(async (route) => {
  const user = await useUserData()
  await withContext(functionThatReturnsAPromise())
  const me = await useCurrentUserData()

  // ...
})
```

This allows nested loaders to be aware of their *parent loader*. This could probably be linted with an eslint plugin. It is similar to the problem `<script setup>` had before introducing the automatic `withAsyncContext()`. The same feature could be introduced (via a vite plugin) but will also have a performance cost. In the future, this *should* be solved with the [async-context](https://github.com/tc39/proposal-async-context) proposal (stage 2).
:::

---

---
url: /guide/essentials/nested-routes.md
---
# Nested Routes

Some applications' UIs are composed of components that are nested multiple levels deep. In this case, it is very common that the segments of a URL correspond to a certain structure of nested components, for example:

```
/user/johnny/profile                   /user/johnny/posts
┌──────────────────┐                  ┌──────────────────┐
│ User             │                  │ User             │
│ ┌──────────────┐ │                  │ ┌──────────────┐ │
│ │ Profile      │ │  ────────────>   │ │ Posts        │ │
│ │              │ │                  │ │              │ │
│ └──────────────┘ │                  │ └──────────────┘ │
└──────────────────┘                  └──────────────────┘
```

With Vue Router, you can express this relationship using nested route configurations.

Given the app we created in the last chapter:

```vue [App.vue]
<template>
  <router-view />
</template>
```

```vue [User.vue]
<template>
  <div>User {{ $route.params.id }}</div>
</template>
```

```js
import User from './User.vue'

// these are passed to `createRouter`
const routes = [{ path: '/user/:id', component: User }]
```

The `<router-view>` here is a top-level `router-view`. It renders the component matched by a top level route. Similarly, a rendered component can also contain its own, nested `<router-view>`. For example, if we add one inside the `User` component's template:

```vue [User.vue]
<template>
  <div class="user">
    <h2>User {{ $route.params.id }}</h2>
    <router-view />
  </div>
</template>
```

To render components into this nested `router-view`, we need to use the `children` option in any of the routes:

```js
const routes = [
  {
    path: '/user/:id',
    component: User,
    children: [
      {
        // UserProfile will be rendered inside User's <router-view>
        // when /user/:id/profile is matched
        path: 'profile',
        component: UserProfile,
      },
      {
        // UserPosts will be rendered inside User's <router-view>
        // when /user/:id/posts is matched
        path: 'posts',
        component: UserPosts,
      },
    ],
  },
]
```

**Note that nested paths that start with `/` will be treated as root paths. This allows you to leverage the component nesting without having to use a nested URL.**

As you can see, the `children` option is just another Array of routes like `routes` itself. Therefore, you can keep nesting views as much as you need.

At this point, with the above configuration, when you visit `/user/eduardo`, nothing will be rendered inside `User`'s `router-view`, because no nested route is matched. Maybe you do want to render something there. In such case you can provide an empty nested path:

```js
const routes = [
  {
    path: '/user/:id',
    component: User,
    children: [
      // UserHome will be rendered inside User's <router-view>
      // when /user/:id is matched
      { path: '', component: UserHome },

      // ...other sub routes
    ],
  },
]
```

A working demo of this example can be found [here](https://codesandbox.io/s/nested-views-vue-router-4-examples-hl326?initialpath=%2Fusers%2Feduardo).

## Nested Named Routes

When dealing with [Named Routes](./named-routes.md), you usually **name the children routes**:

```js
const routes = [
  {
    path: '/user/:id',
    component: User,
    // notice how only the child route has a name
    children: [{ path: '', name: 'user', component: UserHome }],
  },
]
```

This will ensure navigating to `/user/:id` will always display the nested route.

In some scenarios, you may want to navigate to a named route without navigating to the nested route. For example, if you want to navigate to `/user/:id` without displaying the nested route. In that case, you can **also** name the parent route but note **that reloading the page will always display the nested child** as it's considered a navigation to the path `/users/:id` instead of the named route:

```js
const routes = [
  {
    path: '/user/:id',
    name: 'user-parent',
    component: User,
    children: [{ path: '', name: 'user', component: UserHome }],
  },
]
```

## Omitting parent components&#x20;

We can also take advantage of the parent-child relationship between routes without needing to nest route components. This can be useful for grouping together routes with a common path prefix, or when working with more advanced features, such as [per-route navigation guards](../advanced/navigation-guards#Per-Route-Guard) or [route meta fields](../advanced/meta).

To achieve this, we omit the `component` and `components` options from the parent route:

```js
const routes = [
  {
    path: '/admin',
    children: [
      { path: '', component: AdminOverview },
      { path: 'users', component: AdminUserList },
      { path: 'users/:id', component: AdminUserDetails },
    ],
  },
]
```

As the parent doesn't specify a route component, the top-level `<router-view>` will skip over the parent and just use the component from the relevant child instead.

---

---
url: /data-loaders/nuxt.md
---
# Nuxt

To use Data Loaders in Nuxt, create a new plugin file in the `plugins` directory of your Nuxt project and setup the Data Loaders plugin like usual:

```ts
// plugins/data-loaders.ts
import { DataLoaderPlugin } from 'vue-router/experimental'

export default defineNuxtPlugin({
  name: 'data-loaders',
  dependsOn: ['nuxt:router'],
  setup(nuxtApp) {
    const appConfig = useAppConfig()

    nuxtApp.vueApp.use(DataLoaderPlugin, {
      router: nuxtApp.vueApp.config.globalProperties.$router,
      isSSR: import.meta.server,
      // other options...
    })
  },
})
```

The two required options are:

* `router`: the Vue Router instance
* `isSSR`: a boolean indicating if the app is running on the server side

## No module?

> "Why do I need to write the plugin myself instead of using a Module?"

The Data Loader plugin has options that are not serializable (e.g. `selectNavigationResult()` and `errors`). In order to support those within a module, we would have to pass them through the `app.config.ts`, splitting up the configuration and making it harder to maintain. A short plugin is easier to understand and closer to the *vanilla* version.

---

---
url: /guide/essentials/passing-props.md
---
# Passing Props to Route Components

Using `$route` or `useRoute()` in your component creates a tight coupling with the route which limits the flexibility of the component as it can only be used on certain URLs. While this is not necessarily a bad thing, we can decouple this behavior with a `props` option.

Let's return to our earlier example:

```vue [User.vue]
<template>
  <div>User {{ $route.params.id }}</div>
</template>
```

with:

```js
import User from './User.vue'

// these are passed to `createRouter`
const routes = [{ path: '/users/:id', component: User }]
```

We can remove the direct dependency on `$route` in `User.vue` by declaring a prop instead:

::: code-group

```vue [Composition API]
<!-- User.vue -->
<script setup>
defineProps({
  id: String,
})
</script>

<template>
  <div>User {{ id }}</div>
</template>
```

```vue [Options API]
<!-- User.vue -->
<script>
export default {
  props: {
    id: String,
  },
}
</script>

<template>
  <div>User {{ id }}</div>
</template>
```

:::

We can then configure the route to pass the `id` param as a prop by setting `props: true`:

```js
const routes = [{ path: '/user/:id', component: User, props: true }]
```

This allows you to use the component anywhere, which makes the component easier to reuse and test.

## Boolean mode

When `props` is set to `true`, the `route.params` will be set as the component props.

## Named views

For routes with named views, you have to define the `props` option for each named view:

```js
const routes = [
  {
    path: '/user/:id',
    components: { default: User, sidebar: Sidebar },
    props: { default: true, sidebar: false },
  },
]
```

## Object mode

When `props` is an object, this will be set as the component props as-is. Useful for when the props are static.

```js
const routes = [
  {
    path: '/promotion/from-newsletter',
    component: Promotion,
    props: { newsletterPopup: false },
  },
]
```

## Function mode

You can create a function that returns props. This allows you to cast parameters into other types, combine static values with route-based values, etc.

```js
const routes = [
  {
    path: '/search',
    component: SearchUser,
    props: route => ({ query: route.query.q }),
  },
]
```

The URL `/search?q=vue` would pass `{query: 'vue'}` as props to the `SearchUser` component.

Try to keep the `props` function stateless, as it's only evaluated on route changes. Use a wrapper component if you need state to define the props, that way Vue can react to state changes.

## Via RouterView

You can also pass any props via the [`<RouterView>` slot](../advanced/router-view-slot):

```vue-html
<RouterView v-slot="{ Component }">
  <component
    :is="Component"
    view-prop="value"
   />
</RouterView>
```

::: warning
In this case, **all view components** will receive `view-prop`. This is usually not a good idea as it means that all of the view components have declared a `view-prop` prop, which is not necessarily true. If possible, use any of the options above.
:::

---

---
url: /guide/essentials/navigation.md
---

# Programmatic Navigation

Aside from using `<router-link>` to create anchor tags for declarative navigation, we can do this programmatically using the router's instance methods.

## Navigate to a different location

**Note: The examples below refer to the router instance as `router`. Inside a component, you can access the router using the `$router` property, e.g. `this.$router.push(...)`. If you're using the Composition API, the router is accessible by calling [`useRouter()`](../advanced/composition-api).**

To navigate to a different URL, use `router.push`. This method pushes a new entry into the history stack, so when the user clicks the browser back button they will be taken to the previous URL.

This is the method called internally when you click a `<router-link>`, so clicking `<router-link :to="...">` is the equivalent of calling `router.push(...)`.

| Declarative               | Programmatic       |
| ------------------------- | ------------------ |
| `<router-link :to="...">` | `router.push(...)` |

The argument can be a string path, or a location descriptor object. Examples:

```js
// literal string path
router.push('/users/eduardo')

// object with path
router.push({ path: '/users/eduardo' })

// named route with params to let the router build the url
router.push({ name: 'user', params: { username: 'eduardo' } })

// with query, resulting in /register?plan=private
router.push({ path: '/register', query: { plan: 'private' } })

// with hash, resulting in /about#team
router.push({ path: '/about', hash: '#team' })
```

**Note**: `params` are ignored if a `path` is provided, which is not the case for `query`, as shown in the example above. Instead, you need to provide the `name` of the route or manually specify the whole `path` with any parameter:

```js
const username = 'eduardo'
// we can manually build the url but we will have to handle the encoding ourselves
router.push(`/user/${username}`) // -> /user/eduardo
// same as
router.push({ path: `/user/${username}` }) // -> /user/eduardo
// if possible use `name` and `params` to benefit from automatic URL encoding
router.push({ name: 'user', params: { username } }) // -> /user/eduardo
// `params` cannot be used alongside `path`
router.push({ path: '/user', params: { username } }) // -> /user
```

When specifying `params`, make sure to either provide a `string` or `number` (or an array of these for [repeatable params](./route-matching-syntax.md#Repeatable-params)). **Any other type (like objects, booleans, etc) will be automatically stringified**. For [optional params](./route-matching-syntax.md#Optional-parameters), you can provide an empty string (`""`) or `null` as the value to remove it.

Since the prop `to` accepts the same kind of object as `router.push`, the exact same rules apply to both of them.

`router.push` and all the other navigation methods return a *Promise* that allows us to wait till the navigation is finished and to know if it succeeded or failed. We will talk more about that in [Navigation Handling](../advanced/navigation-failures.md).

## Replace current location

It acts like `router.push`, the only difference is that it navigates without pushing a new history entry, as its name suggests - it replaces the current entry.

| Declarative                       | Programmatic          |
| --------------------------------- | --------------------- |
| `<router-link :to="..." replace>` | `router.replace(...)` |

It's also possible to directly add a property `replace: true` to the `to` argument that is passed to `router.push`:

```js
router.push({ path: '/home', replace: true })
// equivalent to
router.replace({ path: '/home' })
```

## Traverse history

This method takes a single integer as parameter that indicates by how many steps to go forward or go backward in the history stack, similar to `window.history.go(n)`.

Examples

```js
// go forward by one record, the same as router.forward()
router.go(1)

// go back by one record, the same as router.back()
router.go(-1)

// go forward by 3 records
router.go(3)

// fails silently if there aren't that many records
router.go(-100)
router.go(100)
```

## History Manipulation

You may have noticed that `router.push`, `router.replace` and `router.go` are counterparts of [`window.history.pushState`, `window.history.replaceState` and `window.history.go`](https://developer.mozilla.org/en-US/docs/Web/API/History), and they do imitate the `window.history` APIs.

Therefore, if you are already familiar with [Browser History APIs](https://developer.mozilla.org/en-US/docs/Web/API/History_API), manipulating history will feel familiar when using Vue Router.

It is worth mentioning that Vue Router navigation methods (`push`, `replace`, `go`) work consistently no matter the `history` option passed when creating the router instance.

---

---
url: /guide/essentials/redirect-and-alias.md
---
# Redirect and Alias

## Redirect

Redirecting is also done in the `routes` configuration. To redirect from `/home` to `/`:

```js
const routes = [{ path: '/home', redirect: '/' }]
```

The redirect can also be targeting a named route:

```js
const routes = [{ path: '/home', redirect: { name: 'homepage' } }]
```

Or even use a function for dynamic redirecting:

```js
const routes = [
  {
    // /search/screens -> /search?q=screens
    path: '/search/:searchText',
    redirect: to => {
      // the function receives the target route as the argument
      // we return a redirect path/location here.
      return { path: '/search', query: { q: to.params.searchText } }
    },
  },
  {
    path: '/search',
    // ...
  },
]
```

Note that **[Navigation Guards](../advanced/navigation-guards.md) are not applied on the route that redirects, only on its target**. e.g. In the above example, adding a `beforeEnter` guard to the `/home` route would not have any effect.

When writing a `redirect`, you can omit the `component` option because it is never directly reached so there is no component to render. The only exception are [nested routes](./nested-routes.md): if a route record has `children` and a `redirect` property, it should also have a `component` property.

### Relative redirecting

It's also possible to redirect to a relative location:

```js
const routes = [
  {
    // will always redirect /users/123/posts to /users/123/profile
    path: '/users/:id/posts',
    redirect: to => {
      // the function receives the target route as the argument
      return to.path.replace(/posts$/, 'profile')
    },
  },
]
```

## Alias

A redirect means when the user visits `/home`, the URL will be replaced by `/`, and then matched as `/`. But what is an alias?

**An alias of `/` as `/home` means when the user visits `/home`, the URL remains `/home`, but it will be matched as if the user is visiting `/`.**

The above can be expressed in the route configuration as:

```js
const routes = [{ path: '/', component: Homepage, alias: '/home' }]
```

An alias gives you the freedom to map a UI structure to an arbitrary URL, instead of being constrained by the configuration's nesting structure. Make the alias start with a `/` to make the path absolute in nested routes. You can even combine both and provide multiple aliases with an array:

```js
const routes = [
  {
    path: '/users',
    component: UsersLayout,
    children: [
      // this will render the UserList for these 3 URLs
      // - /users
      // - /users/list
      // - /people
      { path: '', component: UserList, alias: ['/people', 'list'] },
    ],
  },
]
```

If your route has parameters, make sure to include them in any absolute alias:

```js
const routes = [
  {
    path: '/users/:id',
    component: UsersByIdLayout,
    children: [
      // this will render the UserDetails for these 3 URLs
      // - /users/24
      // - /users/24/profile
      // - /24
      { path: 'profile', component: UserDetails, alias: ['/:id', ''] },
    ],
  },
]
```

**Note about SEO**: when using aliases, make sure to [define canonical links](https://support.google.com/webmasters/answer/139066?hl=en).

---

---
url: /data-loaders/reloading-data.md
---
# Reloading data

Very often, it is required to reload the data (e.g. fetch the latest data) without navigating. Since Vue Router considers that a duplicated navigation, we cannot just `router.push()` and expect navigation guards to run again to fetch the latest data. To overcome this, data loaders expose a convenient `reload` method that can be invoked to manually rerun the loader **without navigating**. This has some extra implications we will cover in this page.

## Navigation Unaware

When reloading data, the navigation is not involved, so not only the navigation guards will not run (`beforeRouteUpdate`, `beforeRouteLeave`, etc) but also any `NavigationResult` returned or thrown by the data loader will be ignored.

## Errors

Because we are not within a navigation, errors are actually kept in the `error` property of the loader. Similar to lazy loaders. This allows to display any errors that might have occurred during the reload.

---

---
url: /guide/advanced/meta.md
---
# Route Meta Fields

Sometimes, you might want to attach arbitrary information to routes like： transition names, or roles to control who can access the route, etc. This can be achieved through the `meta` property which accepts an object of properties and can be accessed on the route location and navigation guards. You can define `meta` properties like this:

```js
const routes = [
  {
    path: '/posts',
    component: PostsLayout,
    children: [
      {
        path: 'new',
        component: PostsNew,
        // only authenticated users can create posts
        meta: { requiresAuth: true },
      },
      {
        path: ':id',
        component: PostsDetail,
        // anybody can read a post
        meta: { requiresAuth: false },
      },
    ],
  },
]
```

So how do we access this `meta` field?

First, each route object in the `routes` configuration is called a **route record**. Route records may be nested. Therefore when a route is matched, it can potentially match more than one route record.

For example, with the above route config, the URL `/posts/new` will match both the parent route record (`path: '/posts'`) and the child route record (`path: 'new'`).

All route records matched by a route are exposed on the `route` object (and also route objects in navigation guards) as the `route.matched` Array. We could loop through that array to check all `meta` fields, but Vue Router also provides you a `route.meta` that is a non-recursive merge of **all `meta`** fields from parent to child. Meaning you can simply write:

```js
router.beforeEach((to, from) => {
  // instead of having to check every route record with
  // to.matched.some(record => record.meta.requiresAuth)
  if (to.meta.requiresAuth && !auth.isLoggedIn()) {
    // this route requires auth, check if logged in
    // if not, redirect to login page.
    return {
      path: '/login',
      // save the location we were at to come back later
      query: { redirect: to.fullPath },
    }
  }
})
```

## TypeScript

It is possible to type the meta field by extending the `RouteMeta` interface from `vue-router`:

```ts
// This can be directly added to any of your `.ts` files like `router.ts`
// It can also be added to a `.d.ts` file. Make sure it's included in
// project's tsconfig.json "files"
import 'vue-router'

// To ensure it is treated as a module, add at least one `export` statement
export {}

declare module 'vue-router' {
  interface RouteMeta {
    // is optional
    isAdmin?: boolean
    // must be declared by every route
    requiresAuth: boolean
  }
}
```

---

---
url: /guide/advanced/router-view-slot.md
---
# RouterView slot

The RouterView component exposes a slot that can be used to render the route component:

```vue-html
<router-view v-slot="{ Component }">
  <component :is="Component" />
</router-view>
```

The code above is equivalent to using `<router-view />` without the slot, but the slot provides extra flexibility when we want to work with other features.

## KeepAlive & Transition

When working with the [KeepAlive](https://vuejs.org/guide/built-ins/keep-alive.html) component, we would usually want it to keep the route components alive, not the RouterView itself. We can achieve that by putting the KeepAlive inside the slot:

```vue-html
<router-view v-slot="{ Component }">
  <keep-alive>
    <component :is="Component" />
  </keep-alive>
</router-view>
```

Similarly, the slot allows us to use a [Transition](https://vuejs.org/guide/built-ins/transition.html) component to transition between route components:

```vue-html
<router-view v-slot="{ Component }">
  <transition>
    <component :is="Component" />
  </transition>
</router-view>
```

We can also use KeepAlive inside a Transition:

```vue-html
<router-view v-slot="{ Component }">
  <transition>
    <keep-alive>
      <component :is="Component" />
    </keep-alive>
  </transition>
</router-view>
```

For more information about using RouterView with the Transition component, see the [Transitions](./transitions) guide.

## Passing props and slots

We can use the slot to pass props or slots to the route component:

```vue-html
<router-view v-slot="{ Component }">
  <component :is="Component" some-prop="a value">
    <p>Some slotted content</p>
  </component>
</router-view>
```

In practice, this usually isn't something you would want to do, as the route components would **all need to use the same props and slots**. See [Passing Props to Route Components](../essentials/passing-props) for other ways to pass props.

## Template refs

Using the slot allows us to put a [template ref](https://vuejs.org/guide/essentials/template-refs.html) directly on the route component:

```vue-html
<router-view v-slot="{ Component }">
  <component :is="Component" ref="mainContent" />
</router-view>
```

If we put the ref on the `<router-view>` instead then the ref would be populated with the RouterView instance, rather than the route component.

---

---
url: /guide/essentials/route-matching-syntax.md
---
# Routes' Matching Syntax

Most applications will use static routes like `/about` and dynamic routes like `/users/:userId` like we just saw in [Dynamic Route Matching](./dynamic-matching.md), but Vue Router has much more to offer!

:::tip
For the sake of simplicity, all route records **are omitting the `component` property** to focus on the `path` value.
:::

## Custom regex in params

When defining a param like `:userId`, we internally use the following regex `([^/]+)` (at least one character that isn't a slash `/`) to extract params from URLs. This works well unless you need to differentiate two routes based on the param content. Imagine two routes `/:orderId` and `/:productName`, both would match the exact same URLs, so we need a way to differentiate them. The easiest way would be to add a static section to the path that differentiates them:

```js
const routes = [
  // matches /o/3549
  { path: '/o/:orderId' },
  // matches /p/books
  { path: '/p/:productName' },
]
```

But in some scenarios, we don't want to add that static section `/o` or `/p`. However, `orderId` is always a number while `productName` can be anything so we can specify a custom regex for a param in parentheses:

```js
const routes = [
  // /:orderId -> matches only numbers
  { path: '/:orderId(\\d+)' },
  // /:productName -> matches anything else
  { path: '/:productName' },
]
```

Now, going to `/25` will match `/:orderId` while going to anything else will match `/:productName`. The order of the `routes` array doesn't even matter!

:::tip
Make sure to **escape backslashes (`\`)** like we did with `\d` (becomes `\\d`) to actually pass the backslash character in a string in JavaScript.
:::

Since the closing parentheses `)` is used to mark the end of a custom regex, you must escape it inside of the regexp (e.g. nested groups):

```js
const routes = [
  // note the escaped closing parentheses of the group within the regexp
  { path: '/:custom(something-(nested|other\\))' },
]
```

## Repeatable params

If you need to match routes with multiple sections like `/first/second/third`, you should mark a param as repeatable with `*` (0 or more) and `+` (1 or more):

```js
const routes = [
  // /:chapters -> matches /one, /one/two, /one/two/three, etc
  { path: '/:chapters+' },
  // /:chapters -> matches /, /one, /one/two, /one/two/three, etc
  { path: '/:chapters*' },
]
```

This will give you an array of params instead of a string and will also require you to pass an array when using named routes:

```js
// given { path: '/:chapters*', name: 'chapters' },
router.resolve({ name: 'chapters', params: { chapters: [] } }).href
// produces /
router.resolve({ name: 'chapters', params: { chapters: ['a', 'b'] } }).href
// produces /a/b

// given { path: '/:chapters+', name: 'chapters' },
router.resolve({ name: 'chapters', params: { chapters: [] } }).href
// throws an Error because `chapters` is empty
```

These can also be combined with a custom regex by adding them **after the closing parentheses**:

```js
const routes = [
  // only match numbers
  // matches /1, /1/2, etc
  { path: '/:chapters(\\d+)+' },
  // matches /, /1, /1/2, etc
  { path: '/:chapters(\\d+)*' },
]
```

## Sensitive and strict route options

By default, all routes are case-insensitive and match routes with or without a trailing slash. e.g. a route `/users` matches `/users`, `/users/`, and even `/Users/`. This behavior can be configured with the `strict` and `sensitive` options, they can be set both at a router and route level:

```js
const router = createRouter({
  history: createWebHistory(),
  routes: [
    // will match /users/posva but not:
    // - /users/posva/ because of strict: true
    // - /Users/posva because of sensitive: true
    { path: '/users/:id', sensitive: true },
    // will match /users, /Users, and /users/42 but not /users/ or /users/42/
    { path: '/users/:id?' },
  ],
  strict: true, // applies to all routes
})
```

## Optional parameters

You can also mark a parameter as optional by using the `?` modifier (0 or 1):

```js
const routes = [
  // will match /users and /users/posva
  { path: '/users/:userId?' },
  // will match /users and /users/42
  { path: '/users/:userId(\\d+)?' },
]
```

Note that `*` technically also marks a parameter as optional but `?` parameters cannot be repeated.

If the route segment contains more than **just an optional parameter**, it won't match a path **without the trailing slash**. For example:

* `/users/:uid?-:name?` won't match `/users`, only `/users/-` or even `/users/-/`
* `/users/:uid(\\d+)?:name?` won't match `/users`, only `/users/`, `/users/2`, `/users/2/`, etc

You can play around with the matching syntax [in the playground](https://paths.esm.dev/?p=AAMsIPQg4AoKzidgQFoEXAmw-IEBBRYYOE0SkABTASiz1qgBpgQA1QTsFjAb3h2onsmlAmGIFsCXjXh4AIA.\&t=/users/2/#)

## Debugging

If you need to dig how your routes are transformed into a regex to understand why a route isn't being matched or, to report a bug, you can use the [path ranker tool](https://paths.esm.dev/?p=AAMeJSyAwR4UbFDAFxAcAGAIJXMAAA..#). It supports sharing your routes through the URL.

## Avoiding slow regex

When using custom regex, make sure to avoid using slow regex patterns. For example, using `.*` will match any character and can lead to **serious performance issues** if it's combined with a repeatable modifier `*` or `+` and anything after it:

```ts
const routes = [
  // This creates a very slow regex because of the greedy `.*` followed by `*` and a static string
  { path: '/:pathMatch(.*)*/something-at-the-end' },
]
```

In practice, use these *match everything* params only **in the very end of the URL**. If you need them in the middle of the path, **do not make them repeatable**:

```ts
const routes = [
  // This is fine because the `.*` is at the end
  { path: '/:pathMatch(.*)/something-at-the-end' },
]
```

This matches the same routes but without an array of params and it's much faster.

---

---
url: /guide/advanced/scroll-behavior.md
---
# Scroll Behavior

When using client-side routing, we may want to scroll to top when navigating to a new route, or preserve the scrolling position of history entries just like real page reload does. Vue Router allows you to achieve these and even better, allows you to completely customize the scroll behavior on route navigation.

**Note: this feature only works if the browser supports `history.pushState`.**

When creating the router instance, you can provide the `scrollBehavior` function:

```js
const router = createRouter({
  history: createWebHashHistory(),
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    // return desired position
  }
})
```

The `scrollBehavior` function receives the `to` and `from` route objects, like [Navigation Guards](./navigation-guards.md). The third argument, `savedPosition`, is only available if this is a `popstate` navigation (triggered by the browser's back/forward buttons).

The function can return a [`ScrollToOptions`](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions) position object:

```js
const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    // always scroll to top
    return { top: 0 }
  },
})
```

You can also pass a CSS selector or a DOM element via `el`. In that scenario, `top` and `left` will be treated as relative offsets to that element.

```js
const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    // always scroll 10px above the element #main
    return {
      // could also be
      // el: document.getElementById('main'),
      el: '#main',
      // 10px above the element
      top: 10,
    }
  },
})
```

If a falsy value or an empty object is returned, no scrolling will happen.

Returning the `savedPosition` will result in a native-like behavior when navigating with back/forward buttons:

```js
const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    if (savedPosition) {
      return savedPosition
    } else {
      return { top: 0 }
    }
  },
})
```

If you want to simulate the "scroll to anchor" behavior:

```js
const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    if (to.hash) {
      return {
        el: to.hash,
      }
    }
  },
})
```

If your browser supports [scroll behavior](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior), you can make it smooth:

```js
const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    if (to.hash) {
      return {
        el: to.hash,
        behavior: 'smooth',
      }
    }
  },
})
```

## Delaying the scroll

Sometimes we need to wait a bit before scrolling in the page. For example, when dealing with transitions, we want to wait for the transition to finish before scrolling. To do this you can return a Promise that returns the desired position descriptor. Here is an example where we wait 500ms before scrolling:

```js
const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        resolve({ left: 0, top: 0 })
      }, 500)
    })
  },
})
```

It's possible to hook this up with events from a page-level transition component to make the scroll behavior play nicely with your page transitions, but due to the possible variance and complexity in use cases, we simply provide this primitive to enable specific userland implementations.

## Advanced offsets

If your page has a fixed navbar or similar elements, you might need an offset to ensure the target element isn't hidden behind other content.
Using a static offset value may not always work. You might try CSS-based solutions, like adding offsets with `scroll-margin` or `scroll-padding`, or using `::before` and `::after` pseudo-elements. However, these approaches can lead to unexpected behavior.

In such cases, it's better to calculate the offset manually. A simple way to do this is by combining CSS with JavaScript's `getComputedStyle()`. This lets each element define its own offset dynamically. Here's an example:

```js
const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    const mainElement = document.querySelector('#main')
    if (mainElement) {
      const marginTop = parseFloat(
        getComputedStyle(mainElement).scrollMarginTop
      )
      return {
        el: mainElement,
        top: marginTop,
      }
    } else {
      return { top: 0 }
    }
  },
})
```

---

---
url: /data-loaders/ssr.md
---
# Server side rendering

Use [Colada Loader](./colada/) to take advantage of its SSR caching capabilities. If you don't need SSR, you can use any loader implementation.

---

---
url: /guide/advanced/transitions.md
---
# Transitions

In order to use transitions on your route components and animate navigations, you need to use the [`<RouterView>` slot](./router-view-slot):

```vue-html
<router-view v-slot="{ Component }">
  <transition name="fade">
    <component :is="Component" />
  </transition>
</router-view>
```

[All transition APIs](https://vuejs.org/guide/built-ins/transition.html) work the same here.

## Per-Route Transition

The above usage will apply the same transition for all routes. If you want each route's component to have different transitions, you can instead combine [meta fields](./meta.md) and a dynamic `name` on `<transition>`:

```js
const routes = [
  {
    path: '/custom-transition',
    component: PanelLeft,
    meta: { transition: 'slide-left' },
  },
  {
    path: '/other-transition',
    component: PanelRight,
    meta: { transition: 'slide-right' },
  },
]
```

```vue-html
<router-view v-slot="{ Component, route }">
  <!-- Use a custom transition or fallback to `fade` -->
  <transition :name="route.meta.transition || 'fade'">
    <component :is="Component" />
  </transition>
</router-view>
```

## Route-Based Dynamic Transition

It is also possible to determine the transition to use dynamically based on the relationship between the target route and current route. Using a very similar snippet to the one just before:

```vue-html
<!-- use a dynamic transition name -->
<router-view v-slot="{ Component, route }">
  <transition :name="route.meta.transition">
    <component :is="Component" />
  </transition>
</router-view>
```

We can add an [after navigation hook](./navigation-guards.md#Global-After-Hooks) to dynamically add information to the `meta` field based on the depth of the route

```js
router.afterEach((to, from) => {
  const toDepth = to.path.split('/').length
  const fromDepth = from.path.split('/').length
  to.meta.transition = toDepth < fromDepth ? 'slide-right' : 'slide-left'
})
```

## Forcing a transition between reused views

Vue might automatically reuse components that look alike, avoiding any transition. Fortunately, it is possible [to add a `key` attribute](https://vuejs.org/api/built-in-special-attributes.html#key) to force transitions. This also allows you to trigger transitions while staying on the same route with different params:

```vue-html
<router-view v-slot="{ Component, route }">
  <transition name="fade">
    <component :is="Component" :key="route.path" />
  </transition>
</router-view>
```

## Initial navigation and transitions

Usually, enter animations are ignored by Vue's `<Transition>` unless we add the `appear` prop. But you'll notice that, when using it alongside `<RouterView>`, transitions are **always** applied despite the `appear` prop not being set. This is because navigations are asynchronous in Vue Router, meaning that the Vue application renders once before the initial navigation is finished. There are different ways to adapt this. The easiest one is to await the initial navigation before mounting the app with [`isReady`](https://router.vuejs.org/api/interfaces/Router.html#isReady):

```ts
const app = createApp(App)
app.use(router)

// mount after the initial navigation is ready
await router.isReady()
app.mount('#app')
```

---

---
url: /guide/advanced/typed-routes.md
---
# Typed Routes&#x20;

![RouterLink to autocomplete](https://user-images.githubusercontent.com/664177/176442066-c4e7fa31-4f06-4690-a49f-ed0fd880dfca.png)

It's possible to configure the router to have a *map* of typed routes. While this can be done manually, it is recommended to use the [built-in file-based routing plugin](/file-based-routing/) to generate the routes and the types automatically from a file based routing system.

## Manual Configuration

Here is an example of how to manually configure typed routes:

```ts
// import the `RouteRecordInfo` type from vue-router to type your routes
import type { RouteRecordInfo } from 'vue-router'

// Define an interface of routes
export interface RouteNamedMap {
  // each key is a name
  home: RouteRecordInfo<
    // here we have the same name
    'home',
    // this is the path, it will appear in autocompletion
    '/',
    // these are the raw params (what can be passed to router.push() and RouterLink's "to" prop)
    // In this case, there are no params allowed
    Record<never, never>,
    // these are the normalized params (what you get from useRoute())
    Record<never, never>,
    // this is a union of all children route names, in this case, there are none
    never
  >
  // repeat for each route...
  // Note you can name them whatever you want
  'named-param': RouteRecordInfo<
    'named-param',
    '/:name',
    { name: string | number }, // Allows string or number
    { name: string }, // but always returns a string from the URL
    'named-param-edit'
  >
  'named-param-edit': RouteRecordInfo<
    'named-param-edit',
    '/:name/edit',
    { name: string | number }, // we also include parent params
    { name: string },
    never
  >
  'article-details': RouteRecordInfo<
    'article-details',
    '/articles/:id+',
    { id: Array<number | string> },
    { id: string[] },
    never
  >
  'not-found': RouteRecordInfo<
    'not-found',
    '/:path(.*)',
    { path: string },
    { path: string },
    never
  >
}

// Last, you will need to augment the Vue Router types with this map of routes
declare module 'vue-router' {
  interface TypesConfig {
    RouteNamedMap: RouteNamedMap
  }
}
```

::: tip

This is indeed tedious and error-prone. That's why it's recommended to use the built-in [file-based routing](/file-based-routing/) to generate the routes and the types automatically.

:::

---

---
url: /guide/advanced/composition-api.md
---
# Vue Router and the Composition API

The introduction of Vue's [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html) opened up new possibilities, but to be able to get the full potential out of Vue Router, we will need to use a few new functions to replace access to `this` and in-component navigation guards.

## Accessing the Router and current Route inside `setup`

Because we don't have access to `this` inside of `setup`, we cannot directly access `this.$router` or `this.$route`. Instead, we use the `useRouter` and `useRoute` composables:

```vue
<script setup>
import { useRouter, useRoute } from 'vue-router'

const router = useRouter()
const route = useRoute()

function pushWithQuery(query) {
  router.push({
    name: 'search',
    query: {
      ...route.query,
      ...query,
    },
  })
}
</script>
```

The `route` object is a reactive object. In most scenarios, you should **avoid watching the whole `route`** object. Instead, you can directly watch the properties you are expecting to change:

```vue
<script setup>
import { useRoute } from 'vue-router'
import { ref, watch } from 'vue'

const route = useRoute()
const userData = ref()

// fetch the user information when params change
watch(
  () => route.params.id,
  async newId => {
    userData.value = await fetchUser(newId)
  }
)
</script>
```

Note we still have access to `$router` and `$route` in templates, so there's no need to use `useRouter` or `useRoute` if we only need those objects in the template.

## Navigation Guards

Vue Router exposes update and leave guards as Composition API functions:

```vue
<script setup>
import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router'
import { ref } from 'vue'

// same as beforeRouteLeave option but with no access to `this`
onBeforeRouteLeave((to, from) => {
  const answer = window.confirm(
    'Do you really want to leave? you have unsaved changes!'
  )
  // cancel the navigation and stay on the same page
  if (!answer) return false
})

const userData = ref()

// same as beforeRouteUpdate option but with no access to `this`
onBeforeRouteUpdate(async (to, from) => {
  // only fetch the user if the id changed as maybe only the query or the hash changed
  if (to.params.id !== from.params.id) {
    userData.value = await fetchUser(to.params.id)
  }
})
</script>
```

Composition API guards can also be used in any component rendered by `<router-view>`, they don't have to be used directly on the route component like in-component guards.

## `useLink`

Vue Router exposes the internal behavior of RouterLink as a composable. It accepts a reactive object like the props of `RouterLink` and exposes low-level properties to build your own `RouterLink` component or generate custom links:

```vue
<script setup>
import { RouterLink, useLink } from 'vue-router'
import { computed } from 'vue'

const props = defineProps({
  // add @ts-ignore if using TypeScript
  ...RouterLink.props,
  inactiveClass: String,
})

const {
  // the resolved route object
  route,
  // the href to use in a link
  href,
  // boolean ref indicating if the link is active
  isActive,
  // boolean ref indicating if the link is exactly active
  isExactActive,
  // function to navigate to the link
  navigate,
} = useLink(props)

const isExternalLink = computed(
  () => typeof props.to === 'string' && props.to.startsWith('http')
)
</script>
```

Note that the RouterLink's `v-slot` gives access to the same properties as the `useLink` composable.

---

---
url: /guide/advanced/navigation-failures.md
---
# Waiting for the result of a Navigation

When using `router-link`, Vue Router calls `router.push` to trigger a navigation. While the expected behavior for most links is to navigate a user to a new page, there are a few situations where users will remain on the same page:

* Users are already on the page that they are trying to navigate to.
* A [navigation guard](./navigation-guards.md) aborts the navigation by doing `return false`.
* A new navigation guard takes place while the previous one not finished.
* A [navigation guard](./navigation-guards.md) redirects somewhere else by returning a new location (e.g. `return '/login'`).
* A [navigation guard](./navigation-guards.md) throws an `Error`.

If we want to do something after a navigation is finished, we need a way to wait after calling `router.push`. Imagine we have a mobile menu that allows us to go to different pages and we only want to hide the menu once we have navigated to the new page, we might want to do something like this:

```js
router.push('/my-profile')
this.isMenuOpen = false
```

But this will close the menu right away because **navigations are asynchronous**, we need to `await` the promise returned by `router.push`:

```js
await router.push('/my-profile')
this.isMenuOpen = false
```

Now the menu will close once the navigation is finished but it will also close if the navigation was prevented. We need a way to detect if we actually changed the page we are on or not.

## Detecting Navigation Failures

If a navigation is prevented, resulting in the user staying on the same page, the resolved value of the `Promise` returned by `router.push` will be a *Navigation Failure*. Otherwise, it will be a *falsy* value (usually `undefined`). This allows us to differentiate the case where we navigated away from where we are or not:

```js
const navigationResult = await router.push('/my-profile')

if (navigationResult) {
  // navigation prevented
} else {
  // navigation succeeded (this includes the case of a redirection)
  this.isMenuOpen = false
}
```

*Navigation Failures* are `Error` instances with a few extra properties that gives us enough information to know what navigation was prevented and why. To check the nature of a navigation result, use the `isNavigationFailure` function:

```js
import { NavigationFailureType, isNavigationFailure } from 'vue-router'

// trying to leave the editing page of an article without saving
const failure = await router.push('/articles/2')

if (isNavigationFailure(failure, NavigationFailureType.aborted)) {
  // show a small notification to the user
  showToast('You have unsaved changes, discard and leave anyway?')
}
```

::: tip
If you omit the second parameter: `isNavigationFailure(failure)`, it will only check if `failure` is a *Navigation Failure*.
:::

## Global navigation failures

You can detect global navigation failures globally by using the [`router.afterEach()` navigation guard](./navigation-guards.md#Global-After-Hooks):

```ts
router.afterEach((to, from, failure) => {
  if (failure) {
    sendToAnalytics(to, from, failure)
  }
})
```

## Differentiating Navigation Failures

As we said at the beginning, there are different situations aborting a navigation, all of them resulting in different *Navigation Failures*. They can be differentiated using the `isNavigationFailure` and `NavigationFailureType`. There are three different types:

* `aborted`: `false` was returned inside of a navigation guard to the navigation.
* `cancelled`: A new navigation took place before the current navigation could finish. e.g. `router.push` was called while waiting inside of a navigation guard.
* `duplicated`: The navigation was prevented because we are already at the target location.

## *Navigation Failures*'s properties

All navigation failures expose `to` and `from` properties to reflect the current location as well as the target location for the navigation that failed:

```js
// trying to access the admin page
router.push('/admin').then(failure => {
  if (isNavigationFailure(failure, NavigationFailureType.aborted)) {
    failure.to.path // '/admin'
    failure.from.path // '/'
  }
})
```

In all cases, `to` and `from` are normalized route locations.

## Detecting Redirections

When returning a new location inside of a Navigation Guard, we are triggering a new navigation that overrides the ongoing one. Differently from other return values, a redirection doesn't prevent a navigation, **it creates a new one**. It is therefore checked differently, by reading the `redirectedFrom` property in a Route Location:

```js
await router.push('/my-profile')
if (router.currentRoute.value.redirectedFrom) {
  // redirectedFrom is resolved route location like to and from in navigation guards
}
```