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