vue-router
Version:
> - This is the repository for Vue Router 4 (for Vue 3) > - For Vue Router 3 (for Vue 2) see [vuejs/vue-router](https://github.com/vuejs/vue-router). > To see what versions are currently supported, please refer to the [Security Policy](./packages/router
1,413 lines (1,408 loc) • 90.4 kB
TypeScript
/*!
* vue-router v5.0.6
* (c) 2026 Eduardo San Martin Morote
* @license MIT
*/
import { AllowedComponentProps, AnchorHTMLAttributes, App, Component as Component$1, ComponentCustomProps, ComponentPublicInstance, ComputedRef, DefineComponent, InjectionKey, MaybeRef, Ref, ShallowRef, UnwrapRef, VNode, VNodeProps } from "vue";
//#region src/config.d.ts
/**
* Allows customizing existing types of the router that are used globally like `$router`, `<RouterLink>`, etc. **ONLY FOR INTERNAL USAGE**.
*
* - `$router` - the router instance
* - `$route` - the current route location
* - `beforeRouteEnter` - Page component option
* - `beforeRouteUpdate` - Page component option
* - `beforeRouteLeave` - Page component option
* - `RouterLink` - RouterLink Component
* - `RouterView` - RouterView Component
*
* @internal
*/
interface TypesConfig {}
//#endregion
//#region src/query.d.ts
/**
* Possible values in normalized {@link LocationQuery}. `null` renders the query
* param but without an `=`.
*
* @example
* ```
* ?isNull&isEmpty=&other=other
* gives
* `{ isNull: null, isEmpty: '', other: 'other' }`.
* ```
*
* @internal
*/
type LocationQueryValue = string | null;
/**
* Possible values when defining a query. `undefined` allows to remove a value.
*
* @internal
*/
type LocationQueryValueRaw = LocationQueryValue | number | undefined;
/**
* Normalized query object that appears in {@link RouteLocationNormalized}
*
* @public
*/
type LocationQuery = Record<string, LocationQueryValue | LocationQueryValue[]>;
/**
* Loose {@link LocationQuery} object that can be passed to functions like
* {@link Router.push} and {@link Router.replace} or anywhere when creating a
* {@link RouteLocationRaw}
*
* @public
*/
type LocationQueryRaw = Record<string | number, LocationQueryValueRaw | LocationQueryValueRaw[]>;
/**
* Transforms a queryString into a {@link LocationQuery} object. Accept both, a
* version with the leading `?` and without Should work as URLSearchParams
* @internal
*
* @param search - search string to parse
* @returns a query object
*/
declare function parseQuery(search: string): LocationQuery;
/**
* Stringifies a {@link LocationQueryRaw} object. Like `URLSearchParams`, it
* doesn't prepend a `?`
*
* @internal
*
* @param query - query object to stringify
* @returns string version of the query without the leading `?`
*/
declare function stringifyQuery(query: LocationQueryRaw | undefined): string;
//#endregion
//#region src/matcher/types.d.ts
/**
* Normalized version of a {@link RouteRecord | route record}.
*/
interface RouteRecordNormalized {
/**
* {@inheritDoc _RouteRecordBase.path}
*/
path: _RouteRecordBase['path'];
/**
* {@inheritDoc _RouteRecordBase.redirect}
*/
redirect: _RouteRecordBase['redirect'] | undefined;
/**
* {@inheritDoc _RouteRecordBase.name}
*/
name: _RouteRecordBase['name'];
/**
* {@inheritDoc RouteRecordMultipleViews.components}
*/
components: RouteRecordMultipleViews['components'] | null | undefined;
/**
* Contains the original modules for lazy loaded components.
* @internal
*/
mods: Record<string, unknown>;
/**
* Nested route records.
*/
children: RouteRecordRaw[];
/**
* {@inheritDoc _RouteRecordBase.meta}
*/
meta: Exclude<_RouteRecordBase['meta'], void>;
/**
* {@inheritDoc RouteRecordMultipleViews.props}
*/
props: Record<string, _RouteRecordProps>;
/**
* Registered beforeEnter guards
*/
beforeEnter: _RouteRecordBase['beforeEnter'];
/**
* Registered leave guards
*
* @internal
*/
leaveGuards: Set<NavigationGuard>;
/**
* Registered update guards
*
* @internal
*/
updateGuards: Set<NavigationGuard>;
/**
* Registered beforeRouteEnter callbacks passed to `next` or returned in guards
*
* @internal
*/
enterCallbacks: Record<string, NavigationGuardNextCallback[]>;
/**
* Mounted route component instances
* Having the instances on the record mean beforeRouteUpdate and
* beforeRouteLeave guards can only be invoked with the latest mounted app
* instance if there are multiple application instances rendering the same
* view, basically duplicating the content on the page, which shouldn't happen
* in practice. It will work if multiple apps are rendering different named
* views.
*/
instances: Record<string, ComponentPublicInstance | undefined | null>;
/**
* Defines if this record is the alias of another one. This property is
* `undefined` if the record is the original one.
*/
aliasOf: RouteRecordNormalized | undefined;
}
/**
* {@inheritDoc RouteRecordNormalized}
*/
type RouteRecord = RouteRecordNormalized;
//#endregion
//#region src/matcher/pathParserRanker.d.ts
type PathParams = Record<string, string | string[]>;
/**
* A param in a url like `/users/:id`
*/
interface PathParserParamKey {
name: string;
repeatable: boolean;
optional: boolean;
}
interface PathParser {
/**
* The regexp used to match a url
*/
re: RegExp;
/**
* The score of the parser
*/
score: Array<number[]>;
/**
* Keys that appeared in the path
*/
keys: PathParserParamKey[];
/**
* Parses a url and returns the matched params or null if it doesn't match. An
* optional param that isn't preset will be an empty string. A repeatable
* param will be an array if there is at least one value.
*
* @param path - url to parse
* @returns a Params object, empty if there are no params. `null` if there is
* no match
*/
parse(path: string): PathParams | null;
/**
* Creates a string version of the url
*
* @param params - object of params
* @returns a url
*/
stringify(params: PathParams): string;
}
/**
* @internal
*/
interface _PathParserOptions {
/**
* Makes the RegExp case-sensitive.
*
* @defaultValue `false`
*/
sensitive?: boolean;
/**
* Whether to disallow a trailing slash or not.
*
* @defaultValue `false`
*/
strict?: boolean;
/**
* Should the RegExp match from the beginning by prepending a `^` to it.
* @internal
*
* @defaultValue `true`
*/
start?: boolean;
/**
* Should the RegExp match until the end by appending a `$` to it.
*
* @deprecated this option will alsways be `true` in the future. Open a discussion in vuejs/router if you need this to be `false`
*
* @defaultValue `true`
*/
end?: boolean;
}
type PathParserOptions = Pick<_PathParserOptions, 'end' | 'sensitive' | 'strict'>;
//#endregion
//#region src/matcher/pathMatcher.d.ts
interface RouteRecordMatcher extends PathParser {
record: RouteRecord;
parent: RouteRecordMatcher | undefined;
children: RouteRecordMatcher[];
alias: RouteRecordMatcher[];
}
//#endregion
//#region src/matcher/index.d.ts
/**
* Internal RouterMatcher
*
* @internal
*/
interface RouterMatcher {
addRoute: (record: RouteRecordRaw, parent?: RouteRecordMatcher) => () => void;
removeRoute(matcher: RouteRecordMatcher): void;
removeRoute(name: NonNullable<RouteRecordNameGeneric>): void;
clearRoutes: () => void;
getRoutes: () => RouteRecordMatcher[];
getRecordMatcher: (name: NonNullable<RouteRecordNameGeneric>) => RouteRecordMatcher | undefined;
/**
* Resolves a location. Gives access to the route record that corresponds to the actual path as well as filling the corresponding params objects
*
* @param location - MatcherLocationRaw to resolve to a url
* @param currentLocation - MatcherLocation of the current location
*/
resolve: (location: MatcherLocationRaw, currentLocation: MatcherLocation) => MatcherLocation;
}
/**
* Creates a Router Matcher.
*
* @internal
* @param routes - array of initial routes
* @param globalOptions - global route options
*/
declare function createRouterMatcher(routes: Readonly<RouteRecordRaw[]>, globalOptions: PathParserOptions): RouterMatcher;
//#endregion
//#region src/history/common.d.ts
type HistoryLocation = string;
/**
* Allowed variables in HTML5 history state. Note that pushState clones the state
* passed and does not accept everything: e.g.: it doesn't accept symbols, nor
* functions as values. It also ignores Symbols as keys.
*
* @internal
*/
type HistoryStateValue = string | number | boolean | null | undefined | HistoryState | HistoryStateArray;
/**
* Allowed HTML history.state
*/
interface HistoryState {
[x: number]: HistoryStateValue;
[x: string]: HistoryStateValue;
}
/**
* Allowed arrays for history.state.
*
* @internal
*/
interface HistoryStateArray extends Array<HistoryStateValue> {}
declare enum NavigationType {
pop = "pop",
push = "push"
}
declare enum NavigationDirection {
back = "back",
forward = "forward",
unknown = ""
}
interface NavigationInformation {
type: NavigationType;
direction: NavigationDirection;
delta: number;
}
interface NavigationCallback {
(to: HistoryLocation, from: HistoryLocation, information: NavigationInformation): void;
}
/**
* Interface implemented by History implementations that can be passed to the
* router as {@link Router.history}
*
* @alpha
*/
interface RouterHistory {
/**
* Base path that is prepended to every url. This allows hosting an SPA at a
* sub-folder of a domain like `example.com/sub-folder` by having a `base` of
* `/sub-folder`
*/
readonly base: string;
/**
* Current History location
*/
readonly location: HistoryLocation;
/**
* Current History state
*/
readonly state: HistoryState;
/**
* Navigates to a location. In the case of an HTML5 History implementation,
* this will call `history.pushState` to effectively change the URL.
*
* @param to - location to push
* @param data - optional {@link HistoryState} to be associated with the
* navigation entry
*/
push(to: HistoryLocation, data?: HistoryState): void;
/**
* Same as {@link RouterHistory.push} but performs a `history.replaceState`
* instead of `history.pushState`
*
* @param to - location to set
* @param data - optional {@link HistoryState} to be associated with the
* navigation entry
*/
replace(to: HistoryLocation, data?: HistoryState): void;
/**
* Traverses history in a given direction.
*
* @example
* ```js
* myHistory.go(-1) // equivalent to window.history.back()
* myHistory.go(1) // equivalent to window.history.forward()
* ```
*
* @param delta - distance to travel. If delta is \< 0, it will go back,
* if it's \> 0, it will go forward by that amount of entries.
* @param triggerListeners - whether this should trigger listeners attached to
* the history
*/
go(delta: number, triggerListeners?: boolean): void;
/**
* Attach a listener to the History implementation that is triggered when the
* navigation is triggered from outside (like the Browser back and forward
* buttons) or when passing `true` to {@link RouterHistory.back} and
* {@link RouterHistory.forward}
*
* @param callback - listener to attach
* @returns a callback to remove the listener
*/
listen(callback: NavigationCallback): () => void;
/**
* Generates the corresponding href to be used in an anchor tag.
*
* @param location - history location that should create an href
*/
createHref(location: HistoryLocation): string;
/**
* Clears any event listener attached by the history implementation.
*/
destroy(): void;
}
//#endregion
//#region src/types/index.d.ts
type Lazy<T> = () => Promise<T>;
/**
* @internal
*/
type RouteParamValue = string;
/**
* @internal
*/
type RouteParamValueRaw = RouteParamValue | number | null | undefined;
type RouteParamsGeneric = Record<string, RouteParamValue | RouteParamValue[]>;
type RouteParamsRawGeneric = Record<string, RouteParamValueRaw | Exclude<RouteParamValueRaw, null | undefined>[]>;
/**
* @internal
*/
interface RouteQueryAndHash {
query?: LocationQueryRaw;
hash?: string;
}
/**
* @internal
*/
interface MatcherLocationAsPath {
path: string;
}
/**
* @internal
*/
interface MatcherLocationAsName {
name: RouteRecordNameGeneric;
/**
* Ignored path property since we are dealing with a relative location. Only `undefined` is allowed.
*/
path?: undefined;
params?: RouteParamsGeneric;
}
/**
* @internal
*/
interface MatcherLocationAsRelative {
/**
* Ignored path property since we are dealing with a relative location. Only `undefined` is allowed.
*/
path?: undefined;
params?: RouteParamsGeneric;
}
/**
* @internal
*/
interface LocationAsRelativeRaw {
name?: RouteRecordNameGeneric;
/**
* Ignored path property since we are dealing with a relative location. Only `undefined` is allowed.
*/
path?: undefined;
params?: RouteParamsRawGeneric;
}
/**
* Common options for all navigation methods.
*/
interface RouteLocationOptions {
/**
* Replace the entry in the history instead of pushing a new entry
*/
replace?: boolean;
/**
* Triggers the navigation even if the location is the same as the current one.
* Note this will also add a new entry to the history unless `replace: true`
* is passed.
*/
force?: boolean;
/**
* State to save using the History API. This cannot contain any reactive
* values and some primitives like Symbols are forbidden. More info at
* https://developer.mozilla.org/en-US/docs/Web/API/History/state
*/
state?: HistoryState;
}
/**
* Route Location that can infer the necessary params based on the name.
*
* @internal
*/
interface RouteLocationNamedRaw extends RouteQueryAndHash, LocationAsRelativeRaw, RouteLocationOptions {}
/**
* Route Location that can infer the possible paths.
*
* @internal
*/
interface RouteLocationPathRaw extends RouteQueryAndHash, MatcherLocationAsPath, RouteLocationOptions {}
interface RouteLocationMatched extends RouteRecordNormalized {
components: Record<string, RouteComponent> | null | undefined;
}
/**
* Base properties for a normalized route location.
*
* @internal
*/
interface _RouteLocationBase extends Pick<MatcherLocation, 'name' | 'path' | 'params' | 'meta'> {
/**
* The whole location including the `search` and `hash`. This string is
* percentage encoded.
*/
fullPath: string;
/**
* Object representation of the `search` property of the current location.
*/
query: LocationQuery;
/**
* Hash of the current location. If present, starts with a `#`.
*/
hash: string;
/**
* Contains the location we were initially trying to access before ending up
* on the current location.
*/
redirectedFrom: RouteLocation | undefined;
}
/**
* Allowed Component in {@link RouteLocationMatched}
*/
type RouteComponent = Component$1 | DefineComponent;
/**
* Allowed Component definitions in route records provided by the user
*/
type RawRouteComponent = RouteComponent | Lazy<RouteComponent>;
/**
* Internal type for common properties among all kind of {@link RouteRecordRaw}.
*/
interface _RouteRecordBase extends PathParserOptions {
/**
* Path of the record. Should start with `/` unless the record is the child of
* another record.
*
* @example `/users/:id` matches `/users/1` as well as `/users/posva`.
*/
path: string;
/**
* 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.
*/
redirect?: RouteRecordRedirectOption;
/**
* Aliases for the record. Allows defining extra paths that will behave like a
* copy of the record. Allows having paths shorthands like `/users/:id` and
* `/u/:id`. All `alias` and `path` values must share the same params.
*/
alias?: string | string[];
/**
* Name for the route record. Must be unique.
*/
name?: RouteRecordNameGeneric;
/**
* Before Enter guard specific to this record. Note `beforeEnter` has no
* effect if the record has a `redirect` property.
*/
beforeEnter?: NavigationGuardWithThis<undefined> | NavigationGuardWithThis<undefined>[];
/**
* Arbitrary data attached to the record.
*/
meta?: RouteMeta;
/**
* Array of nested routes.
*/
children?: RouteRecordRaw[];
/**
* Allow passing down params as props to the component rendered by `router-view`.
*/
props?: _RouteRecordProps | Record<string, _RouteRecordProps>;
}
/**
* Interface to type `meta` fields in route records.
*
* @example
*
* ```ts
* // typings.d.ts or router.ts
* import 'vue-router';
*
* declare module 'vue-router' {
* interface RouteMeta {
* requiresAuth?: boolean
* }
* }
* ```
*/
interface RouteMeta extends Record<PropertyKey, unknown> {}
/**
* Route Record defining one single component with the `component` option.
*/
interface RouteRecordSingleView extends _RouteRecordBase {
/**
* Component to display when the URL matches this route.
*/
component: RawRouteComponent;
components?: never;
children?: never;
redirect?: never;
/**
* Allow passing down params as props to the component rendered by `router-view`.
*/
props?: _RouteRecordProps;
}
/**
* Route Record defining one single component with a nested view. Differently
* from {@link RouteRecordSingleView}, this record has children and allows a
* `redirect` option.
*/
interface RouteRecordSingleViewWithChildren extends _RouteRecordBase {
/**
* Component to display when the URL matches this route.
*/
component?: RawRouteComponent | null | undefined;
components?: never;
children: RouteRecordRaw[];
/**
* Allow passing down params as props to the component rendered by `router-view`.
*/
props?: _RouteRecordProps;
}
/**
* Route Record defining multiple named components with the `components` option.
*/
interface RouteRecordMultipleViews extends _RouteRecordBase {
/**
* Components to display when the URL matches this route. Allow using named views.
*/
components: Record<string, RawRouteComponent>;
component?: never;
children?: never;
redirect?: never;
/**
* Allow passing down params as props to the component rendered by
* `router-view`. Should be an object with the same keys as `components` or a
* boolean to be applied to every component.
*/
props?: Record<string, _RouteRecordProps> | boolean;
}
/**
* Route Record defining multiple named components with the `components` option and children.
*/
interface RouteRecordMultipleViewsWithChildren extends _RouteRecordBase {
/**
* Components to display when the URL matches this route. Allow using named views.
*/
components?: Record<string, RawRouteComponent> | null | undefined;
component?: never;
children: RouteRecordRaw[];
/**
* Allow passing down params as props to the component rendered by
* `router-view`. Should be an object with the same keys as `components` or a
* boolean to be applied to every component.
*/
props?: Record<string, _RouteRecordProps> | boolean;
}
/**
* Route Record that defines a redirect. Cannot have `component` or `components`
* as it is never rendered.
*/
interface RouteRecordRedirect extends _RouteRecordBase {
redirect: RouteRecordRedirectOption;
component?: never;
components?: never;
props?: never;
}
type RouteRecordRaw = RouteRecordSingleView | RouteRecordSingleViewWithChildren | RouteRecordMultipleViews | RouteRecordMultipleViewsWithChildren | RouteRecordRedirect;
/**
* Route location that can be passed to the matcher.
*/
type MatcherLocationRaw = MatcherLocationAsPath | MatcherLocationAsName | MatcherLocationAsRelative;
/**
* Normalized/resolved Route location that returned by the matcher.
*/
interface MatcherLocation {
/**
* Name of the matched record
*/
name: RouteRecordNameGeneric | null | undefined;
/**
* Percentage encoded pathname section of the URL.
*/
path: string;
/**
* Object of decoded params extracted from the `path`.
*/
params: RouteParamsGeneric;
/**
* Merged `meta` properties from all the matched route records.
*/
meta: RouteMeta;
/**
* Array of {@link RouteRecord} containing components as they were
* passed when adding records. It can also contain redirect records. This
* can't be used directly
*/
matched: RouteRecord[];
}
//#endregion
//#region src/typed-routes/route-map.d.ts
/**
* Helper type to define a Typed `RouteRecord`
* @see {@link RouteRecord}
*/
interface RouteRecordInfo<Name extends string | symbol = string, Path extends string = string, ParamsRaw extends RouteParamsRawGeneric = RouteParamsRawGeneric, Params extends RouteParamsGeneric = RouteParamsGeneric, ChildrenNames extends string | symbol = never> {
name: Name;
path: Path;
paramsRaw: ParamsRaw;
params: Params;
childrenNames: ChildrenNames;
}
type RouteRecordInfoGeneric = RouteRecordInfo<string | symbol, string, RouteParamsRawGeneric, RouteParamsGeneric, string | symbol>;
/**
* Convenience type to get the typed RouteMap or a generic one if not provided.
* It is extracted from the {@link TypesConfig} if it exists, it becomes
* {@link RouteMapGeneric} otherwise.
*/
type RouteMap = TypesConfig extends Record<'RouteNamedMap', infer RouteNamedMap> ? RouteNamedMap : RouteMapGeneric;
/**
* Generic version of the `RouteMap`.
*/
type RouteMapGeneric = Record<string | symbol, RouteRecordInfoGeneric>;
//#endregion
//#region src/typed-routes/params.d.ts
/**
* Utility type for raw and non raw params like :id+
*
*/
type ParamValueOneOrMore<isRaw extends boolean> = [ParamValue<isRaw>, ...ParamValue<isRaw>[]];
/**
* Utility type for raw and non raw params like :id*
*
*/
type ParamValueZeroOrMore<isRaw extends boolean> = true extends isRaw ? ParamValue<isRaw>[] | undefined | null : ParamValue<isRaw>[] | undefined;
/**
* Utility type for raw and non raw params like :id?
*
*/
type ParamValueZeroOrOne<isRaw extends boolean> = true extends isRaw ? string | number | null | undefined : string;
/**
* Utility type for raw and non raw params like :id
*
*/
type ParamValue<isRaw extends boolean> = true extends isRaw ? string | number : string;
/**
* Generate a type safe params for a route location. Requires the name of the route to be passed as a generic.
* @see {@link RouteParamsGeneric}
*/
type RouteParams<Name extends keyof RouteMap = keyof RouteMap> = RouteMap[Name]['params'];
/**
* Generate a type safe raw params for a route location. Requires the name of the route to be passed as a generic.
* @see {@link RouteParamsRaw}
*/
type RouteParamsRaw<Name extends keyof RouteMap = keyof RouteMap> = RouteMap[Name]['paramsRaw'];
//#endregion
//#region src/types/utils.d.ts
/**
* Creates a union type that still allows autocompletion for strings.
* @internal
*/
type _LiteralUnion<LiteralType, BaseType extends string = string> = LiteralType | (BaseType & Record<never, never>);
/**
* Maybe a promise maybe not
* @internal
*/
type _Awaitable<T> = T | PromiseLike<T>;
/**
* @internal
*/
type Simplify<T> = { [K in keyof T]: T[K] } & {};
//#endregion
//#region src/typed-routes/route-records.d.ts
/**
* @internal
*/
type RouteRecordRedirectOption = RouteLocationRaw | ((to: RouteLocation, from: RouteLocationNormalizedLoaded) => RouteLocationRaw);
/**
* Generic version of {@link RouteRecordName}.
*/
type RouteRecordNameGeneric = string | symbol | undefined;
/**
* 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 {@link RouteRecordNameGeneric}. If you need a typed version of all of the names of routes, use {@link RouteMap | `keyof RouteMap`}
*/
type RouteRecordName = RouteMapGeneric extends RouteMap ? RouteRecordNameGeneric : keyof RouteMap;
/**
* @internal
*/
type _RouteRecordProps<Name extends keyof RouteMap = keyof RouteMap> = boolean | Record<string, any> | ((to: RouteLocationNormalized<Name>) => Record<string, any>);
//#endregion
//#region src/typed-routes/route-location.d.ts
/**
* Generic version of {@link RouteLocation}. It is used when no {@link RouteMap} is provided.
*/
interface RouteLocationGeneric extends _RouteLocationBase, RouteLocationOptions {
/**
* Array of {@link RouteRecord} containing components as they were
* passed when adding records. It can also contain redirect records. This
* can't be used directly. **This property is non-enumerable**.
*/
matched: RouteRecord[];
}
/**
* Helper to generate a type safe version of the {@link RouteLocation} type.
*/
interface RouteLocationTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric }, Name extends keyof RouteMap> extends RouteLocationGeneric {
name: Extract<Name, string | symbol>;
params: RouteMap[Name]['params'];
}
/**
* List of all possible {@link RouteLocation} indexed by the route name.
* @internal
*/
type RouteLocationTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationTyped<RouteMap, N> };
/**
* Generic version of {@link RouteLocationNormalized} that is used when no {@link RouteMap} is provided.
*/
interface RouteLocationNormalizedGeneric extends _RouteLocationBase {
name: RouteRecordNameGeneric;
/**
* Array of {@link RouteRecordNormalized}
*/
matched: RouteRecordNormalized[];
}
/**
* Helper to generate a type safe version of the {@link RouteLocationNormalized} type.
*/
interface RouteLocationNormalizedTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationNormalizedGeneric {
name: Extract<Name, string | symbol>;
params: RouteMap[Name]['params'];
/**
* Array of {@link RouteRecordNormalized}
*/
matched: RouteRecordNormalized[];
}
/**
* List of all possible {@link RouteLocationNormalized} indexed by the route name.
* @internal
*/
type RouteLocationNormalizedTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationNormalizedTyped<RouteMap, N> };
/**
* Generic version of {@link RouteLocationNormalizedLoaded} that is used when no {@link RouteMap} is provided.
*/
interface RouteLocationNormalizedLoadedGeneric extends RouteLocationNormalizedGeneric {
/**
* Array of {@link RouteLocationMatched} containing only plain components (any
* lazy-loaded components have been loaded and were replaced inside the
* `components` object) so it can be directly used to display routes. It
* cannot contain redirect records either. **This property is non-enumerable**.
*/
matched: RouteLocationMatched[];
}
/**
* Helper to generate a type safe version of the {@link RouteLocationNormalizedLoaded} type.
*/
interface RouteLocationNormalizedLoadedTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationNormalizedLoadedGeneric {
name: Extract<Name, string | symbol>;
params: RouteMap[Name]['params'];
}
/**
* List of all possible {@link RouteLocationNormalizedLoaded} indexed by the route name.
* @internal
*/
type RouteLocationNormalizedLoadedTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationNormalizedLoadedTyped<RouteMap, N> };
/**
* Generic version of {@link RouteLocationAsRelative}. It is used when no {@link RouteMap} is provided.
*/
interface RouteLocationAsRelativeGeneric extends RouteQueryAndHash, RouteLocationOptions {
name?: RouteRecordNameGeneric;
params?: RouteParamsRawGeneric;
/**
* A relative path to the current location. This property should be removed
*/
path?: undefined;
}
/**
* Helper to generate a type safe version of the {@link RouteLocationAsRelative} type.
*/
interface RouteLocationAsRelativeTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationAsRelativeGeneric {
name?: Extract<Name, string | symbol>;
params?: RouteMap[Name]['paramsRaw'];
}
/**
* List of all possible {@link RouteLocationAsRelative} indexed by the route name.
* @internal
*/
type RouteLocationAsRelativeTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationAsRelativeTyped<RouteMap, N> };
/**
* Generic version of {@link RouteLocationAsPath}. It is used when no {@link RouteMap} is provided.
*/
interface RouteLocationAsPathGeneric extends RouteQueryAndHash, RouteLocationOptions {
/**
* Percentage encoded pathname section of the URL.
*/
path: string;
}
/**
* Helper to generate a type safe version of the {@link RouteLocationAsPath} type.
*/
interface RouteLocationAsPathTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationAsPathGeneric {
path: _LiteralUnion<RouteMap[Name]['path']>;
}
/**
* List of all possible {@link RouteLocationAsPath} indexed by the route name.
* @internal
*/
type RouteLocationAsPathTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationAsPathTyped<RouteMap, N> };
/**
* Helper to generate a type safe version of the {@link RouteLocationAsString} type.
*/
type RouteLocationAsStringTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> = RouteMap[Name]['path'];
/**
* List of all possible {@link RouteLocationAsString} indexed by the route name.
* @internal
*/
type RouteLocationAsStringTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationAsStringTyped<RouteMap, N> };
/**
* Generic version of {@link RouteLocationResolved}. It is used when no {@link RouteMap} is provided.
*/
interface RouteLocationResolvedGeneric extends RouteLocationGeneric {
/**
* Resolved `href` for the route location that will be set on the `<a href="...">`.
*/
href: string;
}
/**
* Helper to generate a type safe version of the {@link RouteLocationResolved} type.
*/
interface RouteLocationResolvedTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric }, Name extends keyof RouteMap> extends RouteLocationTyped<RouteMap, Name> {
/**
* Resolved `href` for the route location that will be set on the `<a href="...">`.
*/
href: string;
}
/**
* List of all possible {@link RouteLocationResolved} indexed by the route name.
* @internal
*/
type RouteLocationResolvedTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationResolvedTyped<RouteMap, N> };
/**
* Type safe versions of types that are exposed by vue-router. We have to use a generic check to allow for names to be `undefined` when no `RouteMap` is provided.
*/
/**
* {@link RouteLocationRaw} resolved using the matcher
*/
type RouteLocation<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationGeneric : RouteLocationTypedList<RouteMap>[Name];
/**
* Similar to {@link RouteLocation} but its
* {@link RouteLocationNormalizedTyped.matched | `matched` property} cannot contain redirect records
*/
type RouteLocationNormalized<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationNormalizedGeneric : RouteLocationNormalizedTypedList<RouteMap>[Name];
/**
* Similar to {@link 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 RouteLocationNormalizedLoaded<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationNormalizedLoadedGeneric : RouteLocationNormalizedLoadedTypedList<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 RouteLocationAsRelative<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationAsRelativeGeneric : RouteLocationAsRelativeTypedList<RouteMap>[Name];
/**
* Route location resolved with {@link Router | `router.resolve()`}.
*/
type RouteLocationResolved<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationResolvedGeneric : RouteLocationResolvedTypedList<RouteMap>[Name];
/**
* Same as {@link RouteLocationAsPath} but as a string literal.
*/
type RouteLocationAsString<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? string : _LiteralUnion<RouteLocationAsStringTypedList<RouteMap>[Name], string>;
/**
* Route location as an object with a `path` property.
*/
type RouteLocationAsPath<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationAsPathGeneric : RouteLocationAsPathTypedList<RouteMap>[Name];
/**
* Route location that can be passed to `router.push()` and other user-facing APIs.
*/
type RouteLocationRaw<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationAsString | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric : _LiteralUnion<RouteLocationAsStringTypedList<RouteMap>[Name], string> | RouteLocationAsRelativeTypedList<RouteMap>[Name] | RouteLocationAsPathTypedList<RouteMap>[Name];
//#endregion
//#region src/errors.d.ts
/**
* Flags so we can combine them when checking for multiple errors. This is the internal version of
* {@link NavigationFailureType}.
*
* @internal
*/
declare const enum ErrorTypes {
MATCHER_NOT_FOUND = 1,
NAVIGATION_GUARD_REDIRECT = 2,
NAVIGATION_ABORTED = 4,
NAVIGATION_CANCELLED = 8,
NAVIGATION_DUPLICATED = 16
}
/**
* Enumeration with all possible types for navigation failures. Can be passed to
* {@link isNavigationFailure} to check for specific failures.
*/
declare enum NavigationFailureType {
/**
* An aborted navigation is a navigation that failed because a navigation
* guard returned `false` or called `next(false)`
*/
aborted = 4,
/**
* A cancelled navigation is a navigation that failed because a more recent
* navigation finished started (not necessarily finished).
*/
cancelled = 8,
/**
* A duplicated navigation is a navigation that failed because it was
* initiated while already being at the exact same location.
*/
duplicated = 16
}
/**
* Extended Error that contains extra information regarding a failed navigation.
*/
interface NavigationFailure extends Error {
/**
* Type of the navigation. One of {@link NavigationFailureType}
*/
type: ErrorTypes.NAVIGATION_CANCELLED | ErrorTypes.NAVIGATION_ABORTED | ErrorTypes.NAVIGATION_DUPLICATED;
/**
* Route location we were navigating from
*/
from: RouteLocationNormalized;
/**
* Route location we were navigating to
*/
to: RouteLocationNormalized;
}
/**
* Internal error used to detect a redirection.
*
* @internal
*/
interface NavigationRedirectError extends Omit<NavigationFailure, 'to' | 'type'> {
type: ErrorTypes.NAVIGATION_GUARD_REDIRECT;
to: RouteLocationRaw;
}
/**
* Check if an object is a {@link NavigationFailure}.
*
* @param error - possible {@link NavigationFailure}
* @param type - optional types to check for
*
* @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.cancelled )) {
* // ...
* }
* })
* ```
*/
declare function isNavigationFailure(error: any, type?: ErrorTypes.NAVIGATION_GUARD_REDIRECT): error is NavigationRedirectError;
declare function isNavigationFailure(error: any, type?: ErrorTypes | NavigationFailureType): error is NavigationFailure;
/**
* Internal type to define an ErrorHandler
*
* @param error - error thrown
* @param to - location we were navigating to when the error happened
* @param from - location we were navigating from when the error happened
* @internal
*/
interface _ErrorListener {
(error: any, to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded): any;
}
//#endregion
//#region src/typed-routes/navigation-guards.d.ts
/**
* Return types for a Navigation Guard. Based on `TypesConfig`
*
* @see {@link TypesConfig}
*/
type NavigationGuardReturn = void | Error | boolean | RouteLocationRaw;
/**
* Navigation Guard with a type parameter for `this`.
* @see {@link TypesConfig}
*/
interface NavigationGuardWithThis<T> {
(this: T, to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded,
/**
* @deprecated Return a value from the guard instead of calling `next(value)`.
* The callback will be removed in a future version of Vue Router.
*/
next: NavigationGuardNext): _Awaitable<NavigationGuardReturn>;
}
/**
* In `router.beforeResolve((to) => {})`, the `to` is typed as `RouteLocationNormalizedLoaded`, not
* `RouteLocationNormalized` like in `router.beforeEach()`. In practice it doesn't change much as users do not rely on
* the difference between them but if we update the type in vue-router, we will have to update this type too.
* @internal
*/
interface _NavigationGuardResolved {
(this: undefined, to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded,
/**
* @deprecated Return a value from the guard instead of calling `next(value)`.
* The callback will be removed in a future version of Vue Router.
*/
next: NavigationGuardNext): _Awaitable<NavigationGuardReturn>;
}
/**
* Navigation Guard.
*/
interface NavigationGuard {
(to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded,
/**
* @deprecated Return a value from the guard instead of calling `next(value)`.
* The callback will be removed in a future version of Vue Router.
*/
next: NavigationGuardNext): _Awaitable<NavigationGuardReturn>;
}
/**
* Navigation hook triggered after a navigation is settled.
*/
interface NavigationHookAfter {
(to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded, failure?: NavigationFailure | void): unknown;
}
/**
* Callback passed to navigation guards to continue or abort the navigation.
*
* @deprecated Prefer returning a value from the guard instead of calling
* `next(value)`. The callback will be removed in a future version of Vue Router.
*/
interface NavigationGuardNext {
(): void;
(error: Error): void;
(location: RouteLocationRaw): void;
(valid: boolean | undefined): void;
(cb: NavigationGuardNextCallback): void;
}
/**
* Callback that can be passed to `next()` in `beforeRouteEnter()` guards.
*/
type NavigationGuardNextCallback = (vm: ComponentPublicInstance) => unknown;
//#endregion
//#region src/history/html5.d.ts
/**
* Creates an HTML5 history. Most common history for single page applications.
*
* @param base -
*/
declare function createWebHistory(base?: string): RouterHistory;
//#endregion
//#region src/history/memory.d.ts
/**
* 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`.
*
* @param base - Base applied to all urls, defaults to '/'
* @returns a history object that can be passed to the router constructor
*/
declare function createMemoryHistory(base?: string): RouterHistory;
//#endregion
//#region src/history/hash.d.ts
/**
* 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.
*
* @param base - 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 `#`).
*
* @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#`
* ```
*/
declare function createWebHashHistory(base?: string): RouterHistory;
//#endregion
//#region src/scrollBehavior.d.ts
/**
* Scroll position similar to
* {@link https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions | `ScrollToOptions`}.
* Note that not all browsers support `behavior`.
*/
type ScrollPositionCoordinates = {
behavior?: ScrollOptions['behavior'];
left?: number;
top?: number;
};
/**
* Internal normalized version of {@link ScrollPositionCoordinates} that always
* has `left` and `top` coordinates. Must be a type to be assignable to HistoryStateValue.
*
* @internal
*/
type _ScrollPositionNormalized = {
behavior?: ScrollOptions['behavior'];
left: number;
top: number;
};
/**
* Type of the `scrollBehavior` option that can be passed to `createRouter`.
*/
interface RouterScrollBehavior {
/**
* @param to - Route location where we are navigating to
* @param from - Route location where we are navigating from
* @param savedPosition - saved position if it exists, `null` otherwise
*/
(to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded, savedPosition: _ScrollPositionNormalized | null): Awaitable<ScrollPosition | false | void>;
}
interface ScrollPositionElement extends ScrollToOptions {
/**
* A valid CSS selector. Note some characters must be escaped in id selectors (https://mathiasbynens.be/notes/css-escapes).
* @example
* Here are a few examples:
*
* - `.title`
* - `.content:first-child`
* - `#marker`
* - `#marker\~with\~symbols`
* - `#marker.with.dot`: selects `class="with dot" id="marker"`, not `id="marker.with.dot"`
*
*/
el: string | Element;
}
type ScrollPosition = ScrollPositionCoordinates | ScrollPositionElement;
type Awaitable<T> = T | PromiseLike<T>;
//#endregion
//#region src/experimental/route-resolver/matchers/param-parsers/types.d.ts
/**
* Defines a parser that can read a param from the url (string-based) and
* transform it into a more complex type, or vice versa.
*
* @see MatcherPattern
*/
interface ParamParser<TParam = MatcherQueryParamsValue, TUrlParam = MatcherQueryParamsValue, TParamRaw = TParam> {
get?: (value: NoInfer<TUrlParam>) => TParam;
set?: (value: TParamRaw) => TUrlParam;
}
//#endregion
//#region src/experimental/route-resolver/matchers/matcher-pattern.d.ts
/**
* Base interface for matcher patterns that extract params from a URL.
*
* @template TIn - type of the input value to match against the pattern
* @template TParams - type of the output value after matching
* @template TParamsRaw - type of the input value to build the input from
*
* In the case of the `path`, the `TIn` is a `string`, but in the case of the
* query, it's the object of query params. `TParamsRaw` allows for a more permissive
* type when building the value, for example allowing numbers and strings like
* the old params.
*
* @internal this is the base interface for all matcher patterns, it shouldn't
* be used directly
*/
interface MatcherPattern<TIn = string, TParams extends MatcherParamsFormatted = MatcherParamsFormatted, TParamsRaw extends MatcherParamsFormatted = TParams> {
/**
* Matches a serialized params value against the pattern.
*
* @param value - params value to parse
* @throws {MatchMiss} if the value doesn't match
* @returns parsed params object
*/
match(value: TIn): TParams;
/**
* Build a serializable value from parsed params. Should apply encoding if the
* returned value is a string (e.g path and hash should be encoded but query
* shouldn't).
*
* @param value - params value to parse
* @returns serialized params value
*/
build(params: TParamsRaw): TIn;
}
/**
* Handles the `path` part of a URL. It can transform a path string into an
* object of params and vice versa.
*/
interface MatcherPatternPath<TParams extends MatcherParamsFormatted = MatcherParamsFormatted, // | null // | undefined // | void // so it might be a bit more convenient
TParamsRaw extends MatcherParamsFormatted = TParams> extends MatcherPattern<string, TParams, TParamsRaw> {}
/**
* Allows matching a static path.
*
* @example
* ```ts
* const matcher = new MatcherPatternPathStatic('/team')
* matcher.match('/team') // {}
* matcher.match('/team/123') // throws MatchMiss
* matcher.build() // '/team'
* ```
*/
declare class MatcherPatternPathStatic implements MatcherPatternPath<EmptyParams> {
readonly path: string;
/**
* lowercase version of the path to match against.
* This is used to make the matching case insensitive.
*/
private pathi;
constructor(path: string);
match(path: string): EmptyParams;
build(): string;
}
/**
* Options for param parsers in {@link MatcherPatternPathDynamic}.
*/
type MatcherPatternPathDynamic_ParamOptions<TUrlParam extends string | string[] | null = string | string[] | null, TParam = string | string[] | null, TParamRaw = TParam> = readonly [
/**
* Param parser to use for this param.
*/
parser?: ParamParser<TParam, TUrlParam, TParamRaw>,
/**
* Is tha param a repeatable param and should be converted to an array
*/
repeatable?: boolean,
/**
* Can this parameter be omitted or empty (for repeatable params, an empty array).
*/
optional?: boolean];
/**
* Helper type to extract the params from the options object.
*
* @internal
*/
type ExtractParamTypeFromOptions<TParamsOptions> = { [K in keyof TParamsOptions]: TParamsOptions[K] extends MatcherPatternPathDynamic_ParamOptions<any, infer TParam, any> ? TParam : never };
/**
* Helper type to extract the raw params from the options object.
*
* @internal
*/
type ExtractLocationParamTypeFromOptions<TParamsOptions> = { [K in keyof TParamsOptions]: TParamsOptions[K] extends MatcherPatternPathDynamic_ParamOptions<any, any, infer TParamRaw> ? TParamRaw : never };
/**
* Handles the `path` part of a URL with dynamic parameters.
*/
declare class MatcherPatternPathDynamic<TParamsOptions> implements MatcherPatternPath<ExtractParamTypeFromOptions<TParamsOptions>, ExtractLocationParamTypeFromOptions<TParamsOptions>> {
readonly re: RegExp;
readonly params: TParamsOptions & Record<string, MatcherPatternPathDynamic_ParamOptions<any, any>>;
readonly pathParts: Array<string | number | Array<string | number>>;
readonly trailingSlash: boolean | null;
/**
* Cached keys of the {@link params} object.
*/
private paramsKeys;
/**
* Creates a new dynamic path matcher.
*
* @param re - regex to match the path against
* @param params - object of param parsers as {@link MatcherPatternPathDynamic_ParamOptions}
* @param pathParts - array of path parts, where strings are static parts, 1 are regular params, and 0 are splat params (not encode slash)
* @param trailingSlash - whether the path should end with a trailing slash, null means "do not care" (for trailing splat params)
*/
constructor(re: RegExp, params: TParamsOptions & Record<string, MatcherPatternPathDynamic_ParamOptions<any, any>>, pathParts: Array<string | number | Array<string | number>>, trailingSlash?: boolean | null);
match(path: string): Simplify<ExtractParamTypeFromOptions<TParamsOptions>>;
build(params: Simplify<ExtractLocationParamTypeFromOptions<TParamsOptions>>): string;
}
/**
* Handles the `hash` part of a URL. It can transform a hash string into an
* object of params and vice versa.
*/
interface MatcherPatternHash<TParams extends MatcherParamsFormatted = MatcherParamsFormatted> extends MatcherPattern<string, TParams> {}
/**
* Generic object of params that can be passed to a matcher.
*/
type MatcherParamsFormatted = Record<string, unknown>;
/**
* Empty object in TS.
*/
type EmptyParams = Record<PropertyKey, never>;
/**
* Possible values for query params in a matcher.
*/
type MatcherQueryParamsValue = string | null | undefined | Array<string | null>;
type MatcherQueryParams = Record<string, MatcherQueryParamsValue>;
//#endregion
//#region src/location.d.ts
/**
* Location object returned by {@link `parseURL`}.
* @internal
*/
interface LocationNormalized {
path: string;
fullPath: string;
hash: string;
query: LocationQuery;
}
/**
* 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
* }
* })
* ```
*/
declare const START_LOCATION_NORMALIZED: RouteLocationNormalizedLoaded;
//#endregion
//#region src/experimental/route-resolver/resolver-abstract.d.ts
/**
* Allow