Skip to content

API Documentation

API Documentation

Enumerations

Interfaces

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: (vm: ComponentPublicInstance) => unknown

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

Type declaration

▸ (vm): unknown

Parameters
NameType
vmComponentPublicInstance
Returns

unknown


Ƭ 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

NameType
isRawextends boolean

ParamValueOneOrMore

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

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

Type parameters

NameType
isRawextends 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

NameType
isRawextends boolean

ParamValueZeroOrOne

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

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

Type parameters

NameType
isRawextends 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

NameType
Nameextends 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

NameType
Nameextends 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

NameType
RouteMapextends 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

NameType
Nameextends 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

NameType
RouteMapextends RouteMapGeneric = RouteMapGeneric

RouteLocationAsString

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

Same as RouteLocationAsPath but as a string literal.

Type parameters

NameType
Nameextends keyof RouteMap = keyof RouteMap

RouteLocationAsStringTyped

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

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

Type parameters

NameType
RouteMapextends RouteMapGeneric = RouteMapGeneric
Nameextends 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

NameType
RouteMapextends 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

NameType
Nameextends 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

NameType
Nameextends 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

NameType
RouteMapextends RouteMapGeneric = RouteMapGeneric

RouteLocationNormalizedTypedList

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

List of all possible RouteLocationNormalized indexed by the route name.

Type parameters

NameType
RouteMapextends 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

NameType
Nameextends keyof RouteMap = keyof RouteMap

RouteLocationResolved

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

Route location resolved with router.resolve().

Type parameters

NameType
Nameextends 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

NameType
RouteMapextends RouteMapGeneric = RouteMapGeneric

RouteLocationTypedList

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

List of all possible RouteLocation indexed by the route name.

Type parameters

NameType
RouteMapextends 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

NameType
Nameextends 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

NameType
Nameextends 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

NameType
Nameextends keyof RouteMap = keyof RouteMap

Variables

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

NameType
$propsAllowedComponentProps & 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

js
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

NameTypeDefault valueDescription
basestring''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

NameTypeDescription
optionsRouterOptionsRouterOptions

Returns

Router


createRouterMatcher

createRouterMatcher(routes, globalOptions): RouterMatcher

Creates a Router Matcher.

Parameters

NameTypeDescription
routesreadonly RouteRecordRaw[]array of initial routes
globalOptionsPathParserOptionsglobal 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

NameTypeDescription
base?stringoptional 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

js
// 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

NameType
base?string

Returns

RouterHistory


isNavigationFailure

isNavigationFailure(error, type?): error is NavigationRedirectError

Check if an object is a NavigationFailure.

Parameters

NameTypeDescription
erroranypossible NavigationFailure
type?NAVIGATION_GUARD_REDIRECToptional types to check for

Returns

error is NavigationRedirectError

Example

js
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

NameType
errorany
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

NameTypeDescription
routeRouteLocationNormalizedGeneric | RouteLocationGenericresolved 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

NameTypeDescription
leaveGuardNavigationGuardNavigationGuard

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

NameTypeDescription
updateGuardNavigationGuardNavigationGuard

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

NameTypeDescription
searchstringsearch string to parse

Returns

LocationQuery

a query object


stringifyQuery

stringifyQuery(query): string

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

Parameters

NameTypeDescription
queryLocationQueryRawquery object to stringify

Returns

string

string version of the query without the leading ?


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

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

Type parameters

NameType
Nameextends string | symbol = string | symbol

Parameters

NameTypeDescription
propsUseLinkOptions<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

NameType
Nameextends string | symbol = string | symbol

Parameters

NameType
_name?Name

Returns

RouteLocationNormalizedLoaded<Name>


useRouter

useRouter(): Router

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

Returns

Router

Released under the MIT License.