API Documentation

API Documentation

Enumerations

• ErrorTypes
• NavigationFailureType

Interfaces

• HistoryState
• LocationAsRelativeRaw
• MatcherLocation
• MatcherLocationAsPath
• NavigationFailure
• NavigationGuard
• NavigationGuardNext
• NavigationGuardWithThis
• NavigationHookAfter
• NavigationRedirectError
• RouteLocationAsPathGeneric
• RouteLocationAsPathTyped
• RouteLocationAsRelativeGeneric
• RouteLocationAsRelativeTyped
• RouteLocationGeneric
• RouteLocationMatched
• RouteLocationNamedRaw
• RouteLocationNormalizedGeneric
• RouteLocationNormalizedLoadedGeneric
• RouteLocationNormalizedLoadedTyped
• RouteLocationNormalizedTyped
• RouteLocationOptions
• RouteLocationPathRaw
• RouteLocationResolvedGeneric
• RouteLocationResolvedTyped
• RouteLocationTyped
• RouteMeta
• RouteQueryAndHash
• RouteRecordInfo
• RouteRecordMultipleViews
• RouteRecordMultipleViewsWithChildren
• RouteRecordNormalized
• RouteRecordRedirect
• RouteRecordSingleView
• RouteRecordSingleViewWithChildren
• Router
• RouterHistory
• RouterLinkProps
• RouterMatcher
• RouterOptions
• RouterScrollBehavior
• RouterViewProps
• TypesConfig
• UseLinkOptions
• UseLinkReturn
• _PathParserOptions
• _RouteLocationBase
• _RouteRecordBase
• _RouterLinkI

Type Aliases

LocationQuery

Ƭ LocationQuery: Record<string, LocationQueryValue | LocationQueryValue[]>

Normalized query object that appears in RouteLocationNormalized

---

LocationQueryRaw

Ƭ LocationQueryRaw: Record<string | number, LocationQueryValueRaw | LocationQueryValueRaw[]>

Loose LocationQuery object that can be passed to functions like Router.push and Router.replace or anywhere when creating a RouteLocationRaw

---

LocationQueryValue

Ƭ LocationQueryValue: string | null

Possible values in normalized LocationQuery. null renders the query param but without an =.

Example

?isNull&isEmpty=&other=other
gives
`{ isNull: null, isEmpty: '', other: 'other' }`.

---

LocationQueryValueRaw

Ƭ LocationQueryValueRaw: LocationQueryValue | number | undefined

Possible values when defining a query.

---

NavigationGuardNextCallback

Ƭ NavigationGuardNextCallback: (vm: ComponentPublicInstance) => unknown

Callback that can be passed to next() in beforeRouteEnter() guards.

Type declaration

▸ (vm): unknown

Parameters

Name	Type
vm	ComponentPublicInstance

Returns

unknown

---

NavigationGuardReturn

Ƭ NavigationGuardReturn: void | Error | boolean | RouteLocationRaw

Return types for a Navigation Guard. Based on TypesConfig

See

TypesConfig

---

ParamValue

Ƭ ParamValue<isRaw>: true extends isRaw ? string | number : string

Utility type for raw and non raw params like :id

Type parameters

Name	Type
isRaw	extends boolean

---

ParamValueOneOrMore

Ƭ ParamValueOneOrMore<isRaw>: [ParamValue<isRaw>, ...ParamValue<isRaw>[]]

Utility type for raw and non raw params like :id+

Type parameters

Name	Type
isRaw	extends boolean

---

ParamValueZeroOrMore

Ƭ ParamValueZeroOrMore<isRaw>: true extends isRaw ? ParamValue<isRaw>[] | undefined | null : ParamValue<isRaw>[] | undefined

Utility type for raw and non raw params like :id*

Type parameters

Name	Type
isRaw	extends boolean

---

ParamValueZeroOrOne

Ƭ ParamValueZeroOrOne<isRaw>: true extends isRaw ? string | number | null | undefined : string

Utility type for raw and non raw params like :id?

Type parameters

Name	Type
isRaw	extends boolean

---

PathParserOptions

Ƭ PathParserOptions: Pick<_PathParserOptions, "end" | "sensitive" | "strict">

---

RouteComponent

Ƭ RouteComponent: Component | DefineComponent

Allowed Component in RouteLocationMatched

---

RouteLocation

Ƭ RouteLocation<Name>: RouteMapGeneric extends RouteMap ? RouteLocationGeneric : RouteLocationTypedList<RouteMap>[Name]

RouteLocationRaw resolved using the matcher

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationAsPath

Ƭ RouteLocationAsPath<Name>: RouteMapGeneric extends RouteMap ? RouteLocationAsPathGeneric : RouteLocationAsPathTypedList<RouteMap>[Name]

Route location as an object with a path property.

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationAsPathTypedList

Ƭ RouteLocationAsPathTypedList<RouteMap>: { [N in keyof RouteMap]: RouteLocationAsPathTyped<RouteMap, N> }

List of all possible RouteLocationAsPath indexed by the route name.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric

---

RouteLocationAsRelative

Ƭ RouteLocationAsRelative<Name>: RouteMapGeneric extends RouteMap ? RouteLocationAsRelativeGeneric : RouteLocationAsRelativeTypedList<RouteMap>[Name]

Route location relative to the current location. It accepts other properties than path like params, query and hash to conveniently change them.

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationAsRelativeTypedList

Ƭ RouteLocationAsRelativeTypedList<RouteMap>: { [N in keyof RouteMap]: RouteLocationAsRelativeTyped<RouteMap, N> }

List of all possible RouteLocationAsRelative indexed by the route name.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric

---

RouteLocationAsString

Ƭ RouteLocationAsString<Name>: RouteMapGeneric extends RouteMap ? string : _LiteralUnion<RouteLocationAsStringTypedList<RouteMap>[Name], string>

Same as RouteLocationAsPath but as a string literal.

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationAsStringTyped

Ƭ RouteLocationAsStringTyped<RouteMap, Name>: RouteMap[Name]["path"]

Helper to generate a type safe version of the RouteLocationAsString type.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationAsStringTypedList

Ƭ RouteLocationAsStringTypedList<RouteMap>: { [N in keyof RouteMap]: RouteLocationAsStringTyped<RouteMap, N> }

List of all possible RouteLocationAsString indexed by the route name.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric

---

RouteLocationNormalized

Ƭ RouteLocationNormalized<Name>: RouteMapGeneric extends RouteMap ? RouteLocationNormalizedGeneric : RouteLocationNormalizedTypedList<RouteMap>[Name]

Similar to RouteLocation but its matched property cannot contain redirect records

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationNormalizedLoaded

Ƭ RouteLocationNormalizedLoaded<Name>: RouteMapGeneric extends RouteMap ? RouteLocationNormalizedLoadedGeneric : RouteLocationNormalizedLoadedTypedList<RouteMap>[Name]

Similar to RouteLocationNormalized but its components do not contain any function to lazy load components. In other words, it's ready to be rendered by <RouterView>.

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationNormalizedLoadedTypedList

Ƭ RouteLocationNormalizedLoadedTypedList<RouteMap>: { [N in keyof RouteMap]: RouteLocationNormalizedLoadedTyped<RouteMap, N> }

List of all possible RouteLocationNormalizedLoaded indexed by the route name.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric

---

RouteLocationNormalizedTypedList

Ƭ RouteLocationNormalizedTypedList<RouteMap>: { [N in keyof RouteMap]: RouteLocationNormalizedTyped<RouteMap, N> }

List of all possible RouteLocationNormalized indexed by the route name.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric

---

RouteLocationRaw

Ƭ RouteLocationRaw<Name>: RouteMapGeneric extends RouteMap ? RouteLocationAsString | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric : _LiteralUnion<RouteLocationAsStringTypedList<RouteMap>[Name], string> | RouteLocationAsRelativeTypedList<RouteMap>[Name] | RouteLocationAsPathTypedList<RouteMap>[Name]

Route location that can be passed to router.push() and other user-facing APIs.

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationResolved

Ƭ RouteLocationResolved<Name>: RouteMapGeneric extends RouteMap ? RouteLocationResolvedGeneric : RouteLocationResolvedTypedList<RouteMap>[Name]

Route location resolved with router.resolve().

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteLocationResolvedTypedList

Ƭ RouteLocationResolvedTypedList<RouteMap>: { [N in keyof RouteMap]: RouteLocationResolvedTyped<RouteMap, N> }

List of all possible RouteLocationResolved indexed by the route name.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric

---

RouteLocationTypedList

Ƭ RouteLocationTypedList<RouteMap>: { [N in keyof RouteMap]: RouteLocationTyped<RouteMap, N> }

List of all possible RouteLocation indexed by the route name.

Type parameters

Name	Type
RouteMap	extends RouteMapGeneric = RouteMapGeneric

---

RouteMap

Ƭ RouteMap: TypesConfig extends Record<"RouteNamedMap", infer RouteNamedMap> ? RouteNamedMap : RouteMapGeneric

Convenience type to get the typed RouteMap or a generic one if not provided. It is extracted from the TypesConfig if it exists, it becomes RouteMapGeneric otherwise.

---

RouteMapGeneric

Ƭ RouteMapGeneric: Record<string | symbol, RouteRecordInfo>

Generic version of the RouteMap.

---

RouteParamValue

Ƭ RouteParamValue: string

---

RouteParamValueRaw

Ƭ RouteParamValueRaw: RouteParamValue | number | null | undefined

---

RouteParams

Ƭ RouteParams<Name>: RouteMap[Name]["params"]

Generate a type safe params for a route location. Requires the name of the route to be passed as a generic.

See

RouteParamsGeneric

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteParamsGeneric

Ƭ RouteParamsGeneric: Record<string, RouteParamValue | RouteParamValue[]>

---

RouteParamsRaw

Ƭ RouteParamsRaw<Name>: RouteMap[Name]["paramsRaw"]

Generate a type safe raw params for a route location. Requires the name of the route to be passed as a generic.

See

RouteParamsRaw

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

---

RouteParamsRawGeneric

Ƭ RouteParamsRawGeneric: Record<string, RouteParamValueRaw | Exclude<RouteParamValueRaw, null | undefined>[]>

---

RouteRecord

Ƭ RouteRecord: RouteRecordNormalized

Normalized version of a route record.

---

RouteRecordName

Ƭ RouteRecordName: RouteMapGeneric extends RouteMap ? RouteRecordNameGeneric : keyof RouteMap

Possible values for a route record after normalization

NOTE: since RouteRecordName is a type, it evaluates too early and it's often the generic version RouteRecordNameGeneric. If you need a typed version of all of the names of routes, use keyof RouteMap

---

RouteRecordNameGeneric

Ƭ RouteRecordNameGeneric: string | symbol | undefined

Generic version of RouteRecordName.

---

RouteRecordRaw

Ƭ RouteRecordRaw: RouteRecordSingleView | RouteRecordSingleViewWithChildren | RouteRecordMultipleViews | RouteRecordMultipleViewsWithChildren | RouteRecordRedirect

---

RouteRecordRedirectOption

Ƭ RouteRecordRedirectOption: RouteLocationRaw | (to: RouteLocation) => RouteLocationRaw

---

_Awaitable

Ƭ _Awaitable<T>: T | PromiseLike<T>

Maybe a promise maybe not

Type parameters

Name
T

---

_RouteRecordProps

Ƭ _RouteRecordProps<Name>: boolean | Record<string, any> | (to: RouteLocationNormalized<Name>) => Record<string, any>

Type parameters

Name	Type
Name	extends keyof RouteMap = keyof RouteMap

Variables

RouterLink

• Const RouterLink: _RouterLinkI

Component to render a link that triggers a navigation on click.

---

RouterView

• Const RouterView: () => { $props: AllowedComponentProps & ComponentCustomProps & VNodeProps & RouterViewProps ; $slots: { default?: (__namedParameters: { Component: VNode<RendererNode, RendererElement, { [key: string]: any; }> ; route: RouteLocationNormalizedLoadedGeneric }) => VNode<RendererNode, RendererElement, { [key: string]: any; }>[] } }

Component to display the current route the user is at.

Type declaration

• new RouterView(): Object

Component to display the current route the user is at.

Returns

Object

Name	Type
$props	AllowedComponentProps & ComponentCustomProps & VNodeProps & RouterViewProps
$slots	{ default?: (__namedParameters: { Component: VNode<RendererNode, RendererElement, { [key: string]: any; }> ; route: RouteLocationNormalizedLoadedGeneric }) => VNode<RendererNode, RendererElement, { [key: string]: any; }>[] }
$slots.default?	(__namedParameters: { Component: VNode<RendererNode, RendererElement, { [key: string]: any; }> ; route: RouteLocationNormalizedLoadedGeneric }) => VNode<RendererNode, RendererElement, { [key: string]: any; }>[]

---

START_LOCATION

• Const START_LOCATION: RouteLocationNormalizedLoaded

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

Example

import { START_LOCATION } from 'vue-router'

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

---

matchedRouteKey

• Const matchedRouteKey: InjectionKey<ComputedRef<undefined | RouteRecordNormalized>>

RouteRecord being rendered by the closest ancestor Router View. Used for onBeforeRouteUpdate and onBeforeRouteLeave. rvlm stands for Router View Location Matched

---

routeLocationKey

• Const routeLocationKey: InjectionKey<RouteLocationNormalizedLoadedGeneric>

Allows overriding the current route returned by useRoute in tests. rl stands for route location

---

routerKey

• Const routerKey: InjectionKey<Router>

Allows overriding the router instance returned by useRouter in tests. r stands for router

---

routerViewLocationKey

• Const routerViewLocationKey: InjectionKey<Ref<RouteLocationNormalizedLoadedGeneric>>

Allows overriding the current route used by router-view. Internally this is used when the route prop is passed.

---

viewDepthKey

• Const viewDepthKey: InjectionKey<number | Ref<number>>

Allows overriding the router view depth to control which component in matched is rendered. rvd stands for Router View Depth

Functions

createMemoryHistory

▸ createMemoryHistory(base?): RouterHistory

Creates an in-memory based history. The main purpose of this history is to handle SSR. It starts in a special location that is nowhere. It's up to the user to replace that location with the starter location by either calling router.push or router.replace.

Parameters

Name	Type	Default value	Description
base	string	''	Base applied to all urls, defaults to '/'

Returns

RouterHistory

a history object that can be passed to the router constructor

---

createRouter

▸ createRouter(options): Router

Creates a Router instance that can be used by a Vue app.

Parameters

Name	Type	Description
options	RouterOptions	RouterOptions

Returns

Router

---

createRouterMatcher

▸ createRouterMatcher(routes, globalOptions): RouterMatcher

Creates a Router Matcher.

Parameters

Name	Type	Description
routes	readonly RouteRecordRaw[]	array of initial routes
globalOptions	PathParserOptions	global route options

Returns

RouterMatcher

---

createWebHashHistory

▸ createWebHashHistory(base?): RouterHistory

Creates a hash history. Useful for web applications with no host (e.g. file://) or when configuring a server to handle any URL is not possible.

Parameters

Name	Type	Description
base?	string	optional base to provide. Defaults to location.pathname + location.search If there is a <base> tag in the head, its value will be ignored in favor of this parameter but note it affects all the history.pushState() calls, meaning that if you use a <base> tag, it's href value has to match this parameter (ignoring anything after the #).

Returns

RouterHistory

Example

// 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#`

---

createWebHistory

▸ createWebHistory(base?): RouterHistory

Creates an HTML5 history. Most common history for single page applications.

Parameters

Name	Type
base?	string

Returns

RouterHistory

---

isNavigationFailure

▸ isNavigationFailure(error, type?): error is NavigationRedirectError

Check if an object is a NavigationFailure.

Parameters

Name	Type	Description
error	any	possible NavigationFailure
type?	NAVIGATION_GUARD_REDIRECT	optional types to check for

Returns

error is NavigationRedirectError

Example

import { isNavigationFailure, NavigationFailureType } from 'vue-router'

router.afterEach((to, from, failure) => {
  // Any kind of navigation failure
  if (isNavigationFailure(failure)) {
    // ...
  }
  // Only duplicated navigations
  if (isNavigationFailure(failure, NavigationFailureType.duplicated)) {
    // ...
  }
  // Aborted or canceled navigations
  if (isNavigationFailure(failure, NavigationFailureType.aborted | NavigationFailureType.canceled)) {
    // ...
  }
})

▸ isNavigationFailure(error, type?): error is NavigationFailure

Parameters

Name	Type
error	any
type?	ErrorTypes | NavigationFailureType

Returns

error is NavigationFailure

---

loadRouteLocation

▸ loadRouteLocation(route): Promise<RouteLocationNormalizedLoaded>

Ensures a route is loaded, so it can be passed as o prop to <RouterView>.

Parameters

Name	Type	Description
route	RouteLocationNormalizedGeneric | RouteLocationGeneric	resolved route to load

Returns

Promise<RouteLocationNormalizedLoaded>

---

onBeforeRouteLeave

▸ onBeforeRouteLeave(leaveGuard): void

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.

Parameters

Name	Type	Description
leaveGuard	NavigationGuard	NavigationGuard

Returns

void

---

onBeforeRouteUpdate

▸ onBeforeRouteUpdate(updateGuard): void

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.

Parameters

Name	Type	Description
updateGuard	NavigationGuard	NavigationGuard

Returns

void

---

parseQuery

▸ parseQuery(search): LocationQuery

Transforms a queryString into a LocationQuery object. Accept both, a version with the leading ? and without Should work as URLSearchParams

Parameters

Name	Type	Description
search	string	search string to parse

Returns

LocationQuery

a query object

---

stringifyQuery

▸ stringifyQuery(query): string

Stringifies a LocationQueryRaw object. Like URLSearchParams, it doesn't prepend a ?

Parameters

Name	Type	Description
query	LocationQueryRaw	query object to stringify

Returns

string

string version of the query without the leading ?

---

useLink

▸ useLink<Name>(props): UseLinkReturn<Name>

Returns the internal behavior of a RouterLink without the rendering part.

Type parameters

Name	Type
Name	extends string | symbol = string | symbol

Parameters

Name	Type	Description
props	UseLinkOptions<Name>	a to location and an optional replace flag

Returns

UseLinkReturn<Name>

---

useRoute

▸ useRoute<Name>(_name?): RouteLocationNormalizedLoaded<Name>

Returns the current route location. Equivalent to using $route inside templates.

Type parameters

Name	Type
Name	extends string | symbol = string | symbol

Parameters

Name	Type
_name?	Name

Returns

RouteLocationNormalizedLoaded<Name>

---

useRouter

▸ useRouter(): Router

Returns the router instance. Equivalent to using $router inside templates.

Returns

Router