v2.0.0-beta.2

Breaking Changes from beta.1

• beforeEach and afterEach are reverted as router instance methods (options removed). This makes it more convenient for plugins/modules to add hooks after the router instance has been created.

• scrollBehavior change:

  Instead of returning { hash: true } to scroll to an anchor, return { selector: route.hash } instead. This also means you can return any CSS selectors to scroll to the element that matches the selector.

  In addition, you can do return { selector: '...', x: 0, y: 0 }. Here the router will first attempt to scroll to the matching element. If no matching element is found, it will fallback to the x and y positions.

  See update example.

v2.0.0-beta.1

[email protected] only works with vue@^2.0.0-beta.4

This is a major release with numerous breaking changes, the following describes some most important changes from 0.7.x, but may not be fully exhaustive.

Generic API Change

• The old router.go() is now router.push().
• The new router.go is similar to window.history.go(): it accepts a number for navigating in the history stack.
• New methods:
  • router.back()
  • router.forward()

Router Configuration

All router configurations are now passed to the Router constructor in a single object. For available options, see the configuration object's type declaration.

The routes option replaces router.map(). In addition, route configuration now uses Arrays instead of Object hashes. This ensures consistent route matching precedence. (Object key enumeration order is browser-dependent)

See here for an example of the new configuration syntax.

The following router instantiation options are deprecated:

• history (replaced by mode)
• abstract (replaced by mode)
• root (replaced by base)
• saveScrollPosition (replaced by scrollBehavior with much more flexibility, see below)
• hashbang (removed since the hashbang is no longer required for Google to crawl the URL)
• transitionOnLoad (removed because Vue 2.0 has explicit appear transition control)
• suppressTransitionError (removed due to hooks simplification)

The new mode option should be one of the following (defaults to "hash"):

• "abstract"
• "hash"
• "history"

In browsers that do not support history.pushState, the router will automatically fallback to hash mode.

The following methods are deprecated:

• router.map (replaced by the routes option)
• router.beforeEach (replaced by the beforeEach option)
• router.afterEach (replaced by the afterEach option)
• router.redirect (now declared in routes, see Example)
• router.alias (now declared in routes, see Example)

Navigation Hooks

The hooks system has been drastically simplified. All 0.7 transition hooks are deprecated. Here's how to achieve similar functionalities:

• Use component's own lifecycle hooks to replace activate and deactivate.
• Use a watcher on $route to react to route changes (e.g. fetch new data based on new route params - Example)
• canActivate is replaced by beforeEnter guards declared in route configurations. Example
• canDeactivate is replaced by beforeRouteLeave, which is defined at the root level of a component's definition. This hook is called with the component instance as its this context. Example
• canReuse is removed because it is confusing and rarely useful.

In addition, all route hook functions in 2.0 share the same simplified signature:

guard (toRoute, redirect, next) {
  // call redirect to redirect to another route
  // call next to confirm current route
  // or do nothing to cancel the navigation
}

They no longer support returning Promises.

Links

The v-link directive has been replaced by the <router-link> component. The component accepts the following props:

• to: a string path, or an object location descriptor.
• tag: the element to render. Defaults to a.
• exact: for active class matching behavior.
• append: for relative link appending behavior
• replace: replace instead of push history entry
• activeClass: the CSS class to add when the link is active

See a comprehensive example of <router-link> usage.

Named Views

A single route can now map to multiple named components. These components will be rendered into multiple <router-view>s with corresponding names. Example

Scroll Behavior

The scrollBehavior option expects a function that returns instructions on how the page should scroll on route navigations. You can programmatically determine whether to scroll to top, scroll to hash anchor, or scroll to the saved position from popstate. Example

v0.7.13

Fixed compatibility with Vue <1.0.9.

v0.7.12

New

• router.stringifyPath is now exposed as a public method. (@tejitak)
• v-link active class can now contain multiple classes, e.g. class-a class-b.
• Now supports multiple nested v-link-active elements for the same v-link.

Fixed

• #377 & #383 Fix v-link-active not working if v-link is on an element with v-if, v-for or a custom component.
• #378 Fix query parameters being double-encoded (@byrdkm17, @dragantl)
• #379 Fix error when root option is set to /
• #390 ensure v-on is bound before v-link so that it can properly receive click events
• #406 Fix delegate v-link when router has root configuration. (@lepture)
• #424 Should no longer crash on malformed encoded queries

v0.7.11

Fixed

• Refactored hook error handling so that uncaught errors inside Promises are properly thrown instead of silently swallowed.
• #359 fix history.replaceState() with base and null url in Safari. (@decademoon)
• #370 fix this.handler teardown in v-link. (@simplesmiler)

v0.7.10

Fixed

• #339 fix destroyed hook not called when component is toggled with vue-router override
• #340 fix v-link error with target="_blank"
• #342 properly handle history mode fallback in IE9 on initial render with deep URL
• #343 fix path generation not correctly generating 0
• #344 fix incorrect child view caching when using keep-alive
• #347 properly encode URI when generating paths
• #348 fix activate/data hook call order for subRoutes

v0.7.9

• Fixed regression: href not set correctly for named routes.

v0.7.8

New

• Route components can now directly access the router as this.$router.

• Route components now emit a route-data-loaded event when the data hook is resolved. (@lepture)

• You can now use the v-link-active directive to specify a different element where v-link active classes should be applied on. Example:

  <ul>
    <li v-link-active>
      <a v-link="{ path: '/xxx' }">Go</a>
    </li>
  </ul>

  v-link will locate the closest parent element that has v-link-active and apply the active classes on that element instead.

• When using v-link to navigate to a named route, the router will now automatically inherit params from the current parent route. For example:

  • you are at /user/123
  • you are trying to navigate to a named route post with the path /user/:id/post/:post_id using v-link="{ name: 'post', params: { post_id: 234 }}".

  Previously the user id would become undefined. Now it automatically inherits 123.

• router.map, router.on, router.redirect, router.alias, router.beforeEach and router.afterEach now returns the router instance so that they can be chained.

Fixed

• Fix override causing new Vue() without options to fail. (@decademoon)
• #293 fix error when <router-view> is placed inside v-if.

v0.7.7

Fixed

• #241 v-link now respects target="_blank" on the element.
• #243 properly handle query string in both original url and the hash fragment
• respect params and query in transition.redirect
• fix active class matching (follow up on #209)
• #246 fixed build usage via System.js

v0.7.6

New build setup - 15% smaller file size for both CommonJS-based builds and standalone files!

Fixed

• v-link and router.go() should now respect the query option when using the path format:

  router.go({
    path: '/foo',
    query: { id: 123 }
  })

• router.replace() and transition.redirect() should now properly support the same object-based syntax used by router.go() in addition to just string paths.

• #209 fixed active class matching for URLs with query string.