API Reference | Vue Router (original) (raw)

# <router-link>

<router-link> is the component for enabling user navigation in a router-enabled app. The target location is specified with the to prop. It renders as an <a> tag with correct href by default, but can be configured with the tag prop. In addition, the link automatically gets an active CSS class when the target route is active.

<router-link> is preferred over hard-coded <a href="..."> for the following reasons:

• It works the same way in both HTML5 history mode and hash mode, so if you ever decide to switch mode, or when the router falls back to hash mode in IE9, nothing needs to be changed.
• In HTML5 history mode, router-link will intercept the click event so that the browser doesn't try to reload the page.
• When you are using the base option in HTML5 history mode, you don't need to include it in to prop's URLs.

# v-slot API (3.1.0+)

router-link exposes a low level customization through a scoped slot (opens new window). This is a more advanced API that primarily targets library authors but can come in handy for developers as well, most of the time in a custom component like a NavLink or other.

When using the v-slot API, it is required to pass one single child to router-link. If you don't, router-link will wrap its children in a span element.

• href: resolved url. This would be the href attribute of an a element
• route: resolved normalized location
• navigate: function to trigger the navigation. It will automatically prevent events when necessary, the same way router-link does
• 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> tag itself, in that case, you can wrap that element inside a router-link and use the v-slot properties to create your link:

TIP

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

# <router-link> Props

# to

• type: string | Location
• required
  Denotes the target route of the link. When clicked, the value of the to prop will be passed to router.push() internally, so the value can be either a string or a location descriptor object.

# replace

• type: boolean
• default: false
  Setting replace prop will call router.replace() instead of router.push() when clicked, so the navigation will not leave a history record.

# append

• type: boolean
• default: false
  Setting append prop always appends the relative path to the current path. For example, assuming we are navigating from /a to a relative link b, without append we will end up at /b, but with append we will end up at /a/b.

# tag

• type: string
• default: "a"
  Sometimes we want <router-link> to render as another tag, e.g <li>. Then we can use tag prop to specify which tag to render to, and it will still listen to click events for navigation.

# active-class

• type: string
• default: "router-link-active"
  Configure the active CSS class applied when the link is active. Note the default value can also be configured globally via the linkActiveClass router constructor option.

# exact

• type: boolean
• default: false
  The default active class matching behavior is inclusive match. For example, <router-link to="/a"> will get this class applied as long as the current path starts with /a/ or is /a.
  One consequence of this is that <router-link to="/"> will be active for every route! To force the link into "exact match mode", use the exact prop:
  Check out more examples explaining active link class live (opens new window).

# exact-path

New in 3.5.0

• type: boolean
• default: false
  Allows matching only using the path section of the url, effectively ignoring the query and the hash sections.

# exact-path-active-class

• type: string
• default: "router-link-exact-path-active"
  Configure the active CSS class applied when the link is active with exact path match. Note the default value can also be configured globally via the linkExactPathActiveClass router constructor option.

# event

• type: string | Array<string>
• default: 'click'
  Specify the event(s) that can trigger the link navigation.

# exact-active-class

• type: string
• default: "router-link-exact-active"
  Configure the active CSS class applied when the link is active with exact match. Note the default value can also be configured globally via the linkExactActiveClass router constructor option.

# aria-current-value

• type: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'
• default: "page"
  Configure the value of aria-current when the link is active with exact match. It must be one of the allowed values for aria-current (opens new window) in the ARIA spec. In most cases, the default of page should be the best fit.

# <router-view>

The <router-view> component is a functional component that renders the matched component for the given path. Components rendered in <router-view> can also contain their own <router-view>, which will render components for nested paths.

Any non-name props will be passed along to the rendered component, however most of the time the per-route data is contained in the route's params.

Since it's just a component, it works with <transition> and <keep-alive>. When using them both together, make sure to use <keep-alive> inside:

# <router-view> Props

# name

• type: string
• default: "default"
  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 Named Views for an example.

# Router Construction Options

# routes

• type: Array<RouteConfig>
  Type declaration for RouteConfig:

# mode

• type: string
• default: "hash" (in browser) | "abstract" (in Node.js)
• available values: "hash" | "history" | "abstract"
  Configure the router mode.
  • hash: uses the URL hash for routing. Works in all Vue-supported browsers, including those that do not support HTML5 History API.
  • history: requires HTML5 History API and server config. See HTML5 History Mode.
  • abstract: works in all JavaScript environments, e.g. server-side with Node.js. The router will automatically be forced into this mode if no browser API is present.

# base

• type: string
• default: "/"
  The base URL of the app. For example, if the entire single page application is served under /app/, then base should use the value "/app/".

# linkActiveClass

• type: string
• default: "router-link-active"
  Globally configure <router-link> default active class. Also see router-link.

# linkExactActiveClass

• type: string
• default: "router-link-exact-active"
  Globally configure <router-link> default active class for exact matches. Also see router-link.

# scrollBehavior

• type: Function
  Signature:
  For more details see Scroll Behavior.

# parseQuery / stringifyQuery

• type: Function
  Provide custom query string parse / stringify functions. Overrides the default.

# fallback

• type: boolean
• default: true
  Controls whether the router should fallback to hash mode when the browser does not support history.pushState but mode is set to history.
  Setting this to false essentially makes every router-link navigation a full page refresh in IE9. This is useful when the app is server-rendered and needs to work in IE9, because a hash mode URL does not work with SSR.

# Router Instance Properties

# router.app

• type: Vue instance
  The root Vue instance the router was injected into.

# router.mode

• type: string
  The mode the router is using.

# router.currentRoute

• type: Route
  The current route represented as a Route Object.

# router.START_LOCATION (3.5.0+)

• type: Route
  Initial route location represented as a Route Object where the router starts at. Can be used in navigation guards to differentiate the initial navigation.

# Router Instance Methods

# router.beforeEach

# router.beforeResolve

# router.afterEach

Signatures:

Add global navigation guards. See Navigation Guards for more details.

All three methods return a function that removes the registered guard/hook.

# router.push

# router.replace

# router.go

# router.back

# router.forward

Signatures:

Programmatically navigate to a new URL. See Programmatic Navigation for more details.

These functions can only be called after installing the Router plugin and passing it to the root Vue instance as shown in the Getting Started.

# router.getMatchedComponents

Signature:

Returns an Array of the components (definition/constructor, not instances) matched by the provided location or the current route. This is mostly used during server-side rendering to perform data prefetching.

# router.resolve

Signature:

Reverse URL resolving. Given location in form same as used in <router-link/>.

• current is the current Route by default (most of the time you don't need to change this)
• append allows you to append the path to the current route (as with router-link)

# router.addRoutes

DEPRECATED: use router.addRoute() instead.

Signature:

Dynamically add more routes to the router. The argument must be an Array using the same route config format with the routes constructor option.

# router.addRoute

New in 3.5.0

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

Signature:

# router.addRoute

New in 3.5.0

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 overwrites it.

Signature:

# router.getRoutes

New in 3.5.0

Get the list of all the active route records. Note only documented properties are considered Public API, avoid using any other property e.g. regex as it doesn't exist on Vue Router 4.

Signature:

# router.onReady

Signature:

This method queues a callback to be called 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.

This is useful in server-side rendering to ensure consistent output on both the server and the client.

The second argument errorCallback is only supported in 2.4+. It will be called when the initial route resolution runs into an error (e.g. failed to resolve an async component).

# router.onError

Signature:

Register a callback which will be called when an error is caught during a route navigation. Note for an error to be called, it must be one of the following scenarios:

• The error is thrown synchronously inside a route guard function;
• The error is caught and asynchronously handled by calling next(err) inside a route guard function;
• An error occurred when trying to resolve an async component that is required to render a route.

# The Route Object

A route object represents the state of the current active route. It contains parsed information of the current URL and the route records matched by the URL.

The route object is immutable. Every successful navigation will result in a fresh route object.

The route object can be found in multiple places:

• Inside components as this.$route
• Inside $route watcher callbacks
• As the return value of calling router.match(location)
• Inside navigation guards as the first two arguments:
• Inside the scrollBehavior function as the first two arguments:

# Route Object Properties

• $route.path
  • type: string
    A string that equals the path of the current route, always resolved as an absolute path. e.g. "/foo/bar".
• $route.params
  • type: Object
    An object that contains key/value pairs of dynamic segments and star segments. If there are no params the value will be an empty object.
• $route.query
  • type: Object
    An object that contains key/value pairs of the query string. For example, for a path /foo?user=1, we get $route.query.user == 1. If there is no query the value will be an empty object.
• $route.meta
  • type: Object
    An object that contains key/value pairs of the route meta object. If there are no meta properties the value will be an empty object.
• $route.hash
  • type: string
    The hash of the current route (with the #), if it has one. If no hash is present the value will be an empty string.
• $route.fullPath
  • type: string
    The full resolved URL including query and hash.
• $route.matched
  • type: Array<RouteRecord>
    An Array containing route records for all nested path segments of the current route. Route records are the copies of the objects in the routes configuration Array (and in children Arrays):
    When the URL is /foo/bar, $route.matched will be an Array containing both objects (cloned), in parent to child order.
• $route.name
  The name of the current route, if it has one. (See Named Routes)
• $route.redirectedFrom
  The name of the route being redirected from, if there were one. (See Redirect and Alias)

# Component Injections

# Component Injected Properties

These properties are injected into every child component by passing the router instance to the root instance as the router option.

• this.$router
  The router instance.
• this.$route
  The current active Route. 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.