API Reference

<router-link> Props

to

• Type: RouteLocationRaw

• Details:

  Denotes the target route of the link. When clicked, the value of the to prop will be passed to router.push() internally, so it can either be a string or a route location object.

<!-- literal string -->
<router-link to="/home">Home</router-link>
<!-- renders to -->
<a href="/home">Home</a>
<!-- javascript expression using `v-bind` -->
<router-link :to="'/home'">Home</router-link>
<!-- same as above -->
<router-link :to="{ path: '/home' }">Home</router-link>
<!-- named route -->
<router-link :to="{ name: 'user', params: { userId: '123' }}">User</router-link>
<!-- with query, resulting in `/register?plan=private` -->
<router-link :to="{ path: '/register', query: { plan: 'private' }}">
  Register
</router-link>

replace

• Type: boolean

• Default: false

• Details:

  Setting replace prop will call router.replace() instead of router.push() when clicked, so the navigation will not leave a history record.

<router-link to="/abc" replace></router-link>

active-class

• Type: string

• Default: "router-link-active" (or global linkActiveClass)

• Details:

  Class to apply on the rendered <a> when the link is active.

aria-current-value

• Type: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false' (string)

• Default: "page"

• Details:

  Value passed to the attribute aria-current when the link is exactly active.

custom

• Type: boolean

• Default: false

• Details:

  Whether <router-link> should not wrap its content in an <a> element. Useful when using v-slot to create a custom RouterLink. By default, <router-link> will render its content wrapped in an <a> element, even when using v-slot. Passing the custom prop, removes that behavior.

• Examples:

  <router-link to="/home" custom v-slot="{ navigate, href, route }">
    <a :href="href" @click="navigate">{{ route.fullPath }}</a>
  </router-link>

  Renders <a href="/home">/home</a>.

  <router-link to="/home" v-slot="{ route }">
    <span>{{ route.fullPath }}</span>
  </router-link>

  Renders <a href="/home"><span>/home</span></a>.

exact-active-class

• Type: string

• Default: "router-link-exact-active" (or global linkExactActiveClass)

• Details:

  Class to apply on the rendered <a> when the link is exact active.

<router-link>‘s v-slot

<router-link> exposes a low level customization through a scoped slot. This is a more advanced API that primarily targets library authors but can come in handy for developers as well, to build a custom component like a NavLink or other.

TIP

Remember to pass the custom option to <router-link> to prevent it from wrapping its content inside of an <a> element.

<router-link
  to="/about"
  custom
  v-slot="{ href, route, navigate, isActive, isExactActive }"
>
  <NavLink :active="isActive" :href="href" @click="navigate">
    {{ route.fullPath }}
  </NavLink>
</router-link>

• href: resolved url. This would be the href attribute of an <a> element. It contains the base if any was provided.
• route: resolved normalized location.
• navigate: function to trigger the navigation. It will automatically prevent events when necessary, the same way router-link does, e.g. ctrl or cmd + click will still be ignored by navigate.
• isActive: true if the active class should be applied. Allows to apply an arbitrary class.
• isExactActive: true if the exact active class should be applied. Allows to apply an arbitrary class.

Example: Applying Active Class to Outer Element

Sometimes we may want the active class to be applied to an outer element rather than the <a> element itself, in that case, you can wrap that element inside a router-link and use the v-slot properties to create your link:

<router-link
  to="/foo"
  custom
  v-slot="{ href, route, navigate, isActive, isExactActive }"
>
  <li
    :class="[isActive && 'router-link-active', isExactActive && 'router-link-exact-active']"
  >
    <a :href="href" @click="navigate">{{ route.fullPath }}</a>
  </li>
</router-link>

TIP

If you add a target="_blank" to your a element, you must omit the @click="navigate" handler.

<router-view> Props

name

• Type: string

• Default: "default"

• Details:

  When a <router-view> has a name, it will render the component with the corresponding name in the matched route record’s components option.

• See Also: Named Views

route

• Type: RouteLocationNormalized

• Details:

  A route location that has all of its component resolved (if any was lazy loaded) so it can be displayed.

<router-view>‘s v-slot

<router-view> exposes a v-slot API mainly to wrap your route components with <transition> and <keep-alive> components.

<Suspense>
  <template #default>
    <router-view v-slot="{ Component, route }">
      <transition :name="route.meta.transition || 'fade'" mode="out-in">
        <keep-alive>
          <component
            :is="Component"
            :key="route.meta.usePathKey ? route.path : undefined"
          />
        </keep-alive>
      </transition>
    </router-view>
  </template>
  <template #fallback> Loading... </template>
</Suspense>

• Component: VNodes to be passed to a <component>‘s is prop.
• route: resolved normalized route location.

createRouter

Creates a Router instance that can be used by a Vue app. Check the RouterOptions for a list of all the properties that can be passed.

Signature:

export declare function createRouter(options: RouterOptions): Router

Parameters

createWebHistory

Creates an HTML5 history. Most common history for single page applications. The application must be served through the http protocol.

Signature:

export declare function createWebHistory(base?: string): RouterHistory

Parameters

Examples

createWebHistory() // No base, the app is hosted at the root of the domain `https://example.com`
createWebHistory('/folder/') // gives a url of `https://example.com/folder/`

createWebHashHistory

Creates a hash history. Useful for web applications with no host (e.g. file://) or when configuring a server to handle any URL isn’t an option. Note you should use createWebHistory if SEO matters to you.

Signature:

export declare function createWebHashHistory(base?: string): RouterHistory

Parameters

Examples

// at https://example.com/folder
createWebHashHistory() // gives a url of `https://example.com/folder#`
createWebHashHistory('/folder/') // gives a url of `https://example.com/folder/#`
// if the `#` is provided in the base, it won't be added by `createWebHashHistory`
createWebHashHistory('/folder/#/app/') // gives a url of `https://example.com/folder/#/app/`
// you should avoid doing this because it changes the original url and breaks copying urls
createWebHashHistory('/other-folder/') // gives a url of `https://example.com/other-folder/#`
// at file:///usr/etc/folder/index.html
// for locations with no `host`, the base is ignored
createWebHashHistory('/iAmIgnored') // gives a url of `file:///usr/etc/folder/index.html#`

createMemoryHistory

Creates a in-memory based history. The main purpose of this history is to handle SSR. It starts in a special location that is nowhere. If the user is not on a browser context, it’s up to them to replace that location with the starter location by either calling router.push() or router.replace().

Signature:

export declare function createMemoryHistory(base?: string): RouterHistory

Parameters

Returns

A history object that can be passed to the router constructor

NavigationFailureType

Enumeration with all possible types for navigation failures. Can be passed to isNavigationFailure to check for specific failures. Never use any of the numerical values, always use the variables like NavigationFailureType.aborted.

Signature:

export declare enum NavigationFailureType

Members

START_LOCATION

• Type: RouteLocationNormalized

• Details:

  Initial route location where the router is. Can be used in navigation guards to differentiate the initial navigation.

  import { START_LOCATION } from 'vue-router'
  router.beforeEach((to, from) => {
    if (from === START_LOCATION) {
      // initial navigation
    }
  })

Composition API

onBeforeRouteLeave

Add a navigation guard that triggers whenever the component for the current location is about to be left. Similar to beforeRouteLeave but can be used in any component. The guard is removed when the component is unmounted.

Signature:

export declare function onBeforeRouteLeave(leaveGuard: NavigationGuard): void

Parameters

onBeforeRouteUpdate

Add a navigation guard that triggers whenever the current location is about to be updated. Similar to beforeRouteUpdate but can be used in any component. The guard is removed when the component is unmounted.

Signature:

export declare function onBeforeRouteUpdate(updateGuard: NavigationGuard): void

Parameters

useLink

Returns everything exposed by the v-slot API.

Signature:

export declare function useLink(props: RouterLinkOptions): {
  route: ComputedRef<RouteLocationNormalized & { href: string }>,
  href: ComputedRef<string>,
  isActive: ComputedRef<boolean>,
  isExactActive: ComputedRef<boolean>,
  navigate: (event?: MouseEvent) => Promise(NavigationFailure | void),
}

Parameters

useRoute

Returns the current route location. Equivalent to using $route inside templates. Must be called inside of setup().

Signature:

export declare function useRoute(): RouteLocationNormalized

useRouter

Returns the router instance. Equivalent to using $router inside templates. Must be called inside of setup().

Signature:

export declare function useRouter(): Router

TypeScript

Here are some of the interfaces and types used by Vue Router. The documentation references them to give you an idea of the existing properties in objects.

Router Properties

currentRoute

• Type: Ref<RouteLocationNormalized>

• Details:

  Current route location. Readonly.

options

• Type: RouterOptions

• Details:

  Original options object passed to create the Router. Readonly.

Router Methods

addRoute

Add a new Route Record as the child of an existing route. If the route has a name and there is already an existing one with the same one, it removes it first.

Signature:

addRoute(parentName: string | symbol, route: RouteRecordRaw): () => void

Parameters

addRoute

Add a new route record to the router. If the route has a name and there is already an existing one with the same one, it removes it first.

Signature:

addRoute(route: RouteRecordRaw): () => void

Parameters

TIP

Note adding routes does not trigger a new navigation, meaning that the added route will not be displayed unless a new navigation is triggered.

afterEach

Add a navigation hook that is executed after every navigation. Returns a function that removes the registered hook.

Signature:

afterEach(guard: NavigationHookAfter): () => void

Parameters

Examples

router.afterEach((to, from, failure) => {
  if (isNavigationFailure(failure)) {
    console.log('failed navigation', failure)
  }
})

back

Go back in history if possible by calling history.back(). Equivalent to router.go(-1).

Signature:

back(): void

beforeEach

Add a navigation guard that executes before any navigation. Returns a function that removes the registered guard.

Signature:

beforeEach(guard: NavigationGuard): () => void

Parameters

beforeResolve

Add a navigation guard that executes before navigation is about to be resolved. At this state all component have been fetched and other navigation guards have been successful. Returns a function that removes the registered guard.

Signature:

beforeResolve(guard: NavigationGuard): () => void

Parameters

Examples

router.beforeResolve(to => {
  if (to.meta.requiresAuth && !isAuthenticated) return false
})

forward

Go forward in history if possible by calling history.forward(). Equivalent to router.go(1).

Signature:

forward(): void

getRoutes

Get a full list of all the route records.

Signature:

getRoutes(): RouteRecord[]

go

Allows you to move forward or backward through the history.

Signature:

go(delta: number): void

Parameters

hasRoute

Checks if a route with a given name exists

Signature:

hasRoute(name: string | symbol): boolean

Parameters

isReady

Returns a Promise that resolves when the router has completed the initial navigation, which means it has resolved all async enter hooks and async components that are associated with the initial route. If the initial navigation already happened, the promise resolves immediately.This is useful in server-side rendering to ensure consistent output on both the server and the client. Note that on server side, you need to manually push the initial location while on client side, the router automatically picks it up from the URL.

Signature:

isReady(): Promise<void>

onError

Adds an error handler that is called every time a non caught error happens during navigation. This includes errors thrown synchronously and asynchronously, errors returned or passed to next in any navigation guard, and errors occurred when trying to resolve an async component that is required to render a route.

Signature:

onError(handler: (error: any, to: RouteLocationNormalized, from: RouteLocationNormalized) => any): () => void

Parameters

push

Programmatically navigate to a new URL by pushing an entry in the history stack.

Signature:

push(to: RouteLocationRaw): Promise<NavigationFailure | void | undefined>

Parameters

removeRoute

Remove an existing route by its name.

Signature:

removeRoute(name: string | symbol): void

Parameters

replace

Programmatically navigate to a new URL by replacing the current entry in the history stack.

Signature:

replace(to: RouteLocationRaw): Promise<NavigationFailure | void | undefined>

Parameters

resolve

Returns the normalized version of a route location. Also includes an href property that includes any existing base.

Signature:

resolve(to: RouteLocationRaw): RouteLocation & {
  href: string
}

Parameters

RouterOptions

history

History implementation used by the router. Most web applications should use createWebHistory but it requires the server to be properly configured. You can also use a hash based history with createWebHashHistory that does not require any configuration on the server but isn’t handled at all by search engines and does poorly on SEO.

Signature:

history: RouterHistory

Examples

createRouter({
  history: createWebHistory(),
  // other options...
})

linkActiveClass

Default class applied to active RouterLink. If none is provided, router-link-active will be applied.

Signature:

linkActiveClass?: string

linkExactActiveClass

Default class applied to exact active RouterLink. If none is provided, router-link-exact-active will be applied.

Signature:

linkExactActiveClass?: string

parseQuery

Custom implementation to parse a query. Must decode query keys and values. See its counterpart, stringifyQuery.

Signature:

parseQuery?: (searchQuery: string) => Record<string, (string | null)[] | string | null>

Examples

Let’s say you want to use the package qs to parse queries, you can provide both parseQuery and stringifyQuery:

import qs from 'qs'
createRouter({
  // other options...
  parseQuery: qs.parse,
  stringifyQuery: qs.stringify,
})

routes

Initial list of routes that should be added to the router.

Signature:

routes: RouteRecordRaw[]

scrollBehavior

Function to control scrolling when navigating between pages. Can return a Promise to delay when the scrolling happens. See Scroll Behaviour for more details.

Signature:

scrollBehavior?: RouterScrollBehavior

Examples

function scrollBehavior(to, from, savedPosition) {
  // `to` and `from` are both route locations
  // `savedPosition` can be null if there isn't one
}

stringifyQuery

Custom implementation to stringify a query object. Should not prepend a leading ?. Should properly encode query keys and values. parseQuery counterpart to handle query parsing.

Signature:

stringifyQuery?: (
  query: Record<
    string | number,
    string | number | null | undefined | (string | number | null | undefined)[]
  >
) => string

RouteRecordRaw

Route record that can be provided by the user when adding routes via the routes option or via router.addRoute(). There are three different kind of route records:

• Single views records: have a component option
• Multiple views records (named views): have a components option
• Redirect records: cannot have component or components option because a redirect record is never reached.

path

• Type: string

• Details:

  Path of the record. Should start with / unless the record is the child of another record. Can define parameters: /users/:id matches /users/1 as well as /users/posva.

• See Also: Dynamic Route Matching

redirect

• Type: RouteLocationRaw | (to: RouteLocationNormalized) => RouteLocationRaw (Optional)

• Details:

  Where to redirect if the route is directly matched. The redirection happens before any navigation guard and triggers a new navigation with the new target location. Can also be a function that receives the target route location and returns the location we should redirect to.

children

• Type: Array of RouteRecordRaw (Optional)

• Details:

  Nested routes of the current record.

• See Also: Nested Routes

alias

• Type: string | string[] (Optional)

• Details:

  Aliases for the route. Allows defining extra paths that will behave like a copy of the record. This enables paths shorthands like /users/:id and /u/:id. All alias and path values must share the same params.

name

• Type: string | symbol (Optional)

• Details:

  Unique name for the route record.

beforeEnter

• Type: NavigationGuard | NavigationGuard[] (Optional)

• Details:

  Before enter guard specific to this record. Note beforeEnter has no effect if the record has a redirect property.

props

• Type: boolean | Record<string, any> | (to: RouteLocationNormalized) => Record<string, any> (Optional)

• Details:

  Allows passing down params as props to the component rendered by router-view. When passed to a multiple views record, it should be an object with the same keys as components or a boolean to be applied to each component. target location.

• See Also: Passing props to Route Components

meta

• Type: RouteMeta (Optional)

• Details:

  Custom data attached to the record.

• See Also: Meta fields

TIP

If you want to use a functional component, make sure to add a displayName to it.

For example:

const HomeView = () => h('div', 'HomePage')
// in TypeScript, you will need to use the FunctionalComponent type
HomeView.displayName = 'HomeView'
const routes = [{ path: '/', component: HomeView }]

RouteRecordNormalized

Normalized version of a Route Record

aliasOf

• Type: RouteRecordNormalized | undefined

• Details:

  Defines if this record is the alias of another one. This property is undefined if the record is the original one.

beforeEnter

• Type: NavigationGuard

• Details:

  Navigation guard applied when entering this record from somewhere else.

• See Also: Navigation guards

children

• Type: Array of normalized route records

• Details:

  Children route records of the current route. Empty array if none.

components

• Type: Record<string, Component>

• Details:

  Dictionary of named views, if none, contains an object with the key default.

meta

• Type: RouteMeta

• Details:

  Arbitrary data attached to the record.

• See also: Meta fields

name

• Type: string | symbol | undefined

• Details:

  Name for the route record. undefined if none was provided.

path

• Type: string

• Details:

  Normalized path of the record. Includes any parent’s path.

props

• Type: Record<string, boolean | Function | Record<string, any>>

• Details:

  Dictionary of the props option for each named view. If none, it will contain only one property named default.

redirect

• Type: RouteLocationRaw

• Details:

  Where to redirect if the route is directly matched. The redirection happens before any navigation guard and triggers a new navigation with the new target location.

RouteLocationRaw

User-level route location that can be passed to router.push(), redirect, and returned in Navigation Guards.

A raw location can either be a string like /users/posva#bio or an object:

// these three forms are equivalent
router.push('/users/posva#bio')
router.push({ path: '/users/posva', hash: '#bio' })
router.push({ name: 'users', params: { username: 'posva' }, hash: '#bio' })
// only change the hash
router.push({ hash: '#bio' })
// only change query
router.push({ query: { page: '2' } })
// change one param
router.push({ params: { username: 'jolyne' } })

Note path must be provided encoded (e.g. phantom blood becomes phantom%20blood) while params, query and hash must not, they are encoded by the router.

Raw route locations also support an extra option replace to call router.replace() instead of router.push() in navigation guards. Note this also internally calls router.replace() even when calling router.push():

router.push({ hash: '#bio', replace: true })
// equivalent to
router.replace({ hash: '#bio' })

RouteLocation

Resolved RouteLocationRaw that can contain redirect records. Apart from that it has the same properties as RouteLocationNormalized.

RouteLocationNormalized

Normalized route location. Does not have any redirect records. In navigation guards, to and from are always of this type.

fullPath

• Type: string

• Details:

  Encoded URL associated to the route location. Contains path, query and hash.

hash

• Type: string

• Details:

  Decoded hash section of the URL. Always starts with a #. Empty string if there is no hash in the URL.

query

• Type: Record<string, string | string[]>

• Details:

  Dictionary of decoded query params extracted from the search section of the URL.

matched

• Type: RouteRecordNormalized[]

• Details:

  Array of normalized route records that were matched with the given route location.

meta

• Type: RouteMeta

• Details:

  Arbitrary data attached to all matched records merged (non recursively) from parent to child.

• See also: Meta fields

name

• Type: string | symbol | undefined | null

• Details:

  Name for the route record. undefined if none was provided.

params

• Type: Record<string, string | string[]>

• Details:

  Dictionary of decoded params extracted from path.

path

• Type: string

• Details:

  Encoded pathname section of the URL associated to the route location.

redirectedFrom

• Type: RouteLocation

• Details:

  Route location we were initially trying to access before ending up on the current location when a redirect option was found or a navigation guard called next() with a route location. undefined if there was no redirection.

NavigationFailure

from

• Type: RouteLocationNormalized

• Details:

  Route location we were navigating from

to

• Type: RouteLocationNormalized

• Details:

  Route location we were navigating to

type

• Type: NavigationFailureType

• Details:

  Type of the navigation failure.

• See Also: Navigation Failures

NavigationGuard

• Arguments:

  • RouteLocationNormalized to - Route location we are navigating to
  • RouteLocationNormalized from - Route location we are navigating from
  • Function next (Optional) - Callback to validate the navigation

• Details:

  Function that can be passed to control a router navigation. The next callback can be omitted if you return a value (or a Promise) instead, which is encouraged. Possible return values (and parameters for next) are:

  • undefined | void | true: validates the navigation
  • false: cancels the navigation
  • RouteLocationRaw: redirects to a different location
  • (vm: ComponentPublicInstance) => any only for beforeRouteEnter: A callback to be executed once the navigation completes. Receives the route component instance as the parameter.
• See Also: Navigation Guards

Component Injections

Component Injected Properties

These properties are injected into every child component by calling app.use(router).

• this.$router

  The router instance.

• this.$route

  The current active route location. This property is read-only and its properties are immutable, but it can be watched.

Component Enabled Options

• beforeRouteEnter
• beforeRouteUpdate
• beforeRouteLeave

See In Component Guards.