* `to`: `Location` object, or `path`/`fullPath` of the `Location` object, or an absolute URL.
* `action`: `String`. `push`, `replace`, or `dispatch`. Defaults to `push`.
* `tag`: `String`. The HTML tag name. Defaults to `a`.

`` will have `active` class if it equals to the current path.

## Location object
A location object is used for changing the current address.
It can be used in ``, `router.start(location)`, `router.push(location)`, `router.replace(location)`, `router.dispatch(location)`, etc.

A string URL can be converted to a location object by [router.normalize()](#routernormalize).
And a location object can be converted to a URL string by [router.url()](#routerurl).

```js
{
path,
external,
query,
hash,
fullPath,
url,
state,
hidden,
appearPath
}
```

### path
`String`

Router internal path, which has stripped the protocol, host, and base path.

### external
`Boolean`

If `path` is started with protocal, or `external` is `true`,
`path` is treated as an external path, and will be converted to an internal path.

### query
`Object` | `String` | `Array` | `URLSearchParams` | `StringCaster`

`query` accepts the same parameter types as [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams)
constructor. Or it can be a [StringCaster](https://github.com/jiangfengming/cast-string#stringcaster) object that wraps a `URLSearchParams` object.

### hash
`String`

A string containing a `#` followed by the fragment identifier of the URL.
If `HashRouter` is used, the fragment identifier is followed by the second `#` mark.

### fullPath
`String`. Read-only.

path + query string + hash

### url
`String`. Read-only.

* `PathRouter`: base + path + query string + hash
* `HashRouter`: # + path + query string + hash

### state
`Object`

The state object is a JavaScript object which is associated with the history entry.
See `state` parameter of [history.pushState()](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) for details.

### hidden
`Boolean`

Indicate whether it is a hidden history entry. see [router.push()](#routerpush) for detail.

### appearPath
`String`

If `hidden` is `true` and `appearPath` is set, the location bar will show this address instead.

## Matched route object
A matched route object contains the information of the matched route.
It contains some same properties as the `Location` object, and some extra properties.
It's provided by the hook functions as the `to` and `from` parameter.

```js
{
path,
query,
hash,
fullPath,
url,
state,
params,
meta
}
```

### path
`String`

Same as `location.path`.

### query
`StringCaster`

A [StringCaster](https://github.com/jiangfengming/cast-string#stringcaster) object that wraps a `URLSearchParams` object.

### hash
`String`

Same as `location.hash`.

### fullPath
`String`

Same as `location.fullPath`.

### url
`String`

Same as `location.url`.

### params
`StringCaster`

A [StringCaster](https://github.com/jiangfengming/cast-string#stringcaster) object that wraps a plain object.
The plain object is collected from the path segments.
See [Routes definition](#routes-definition) below for details.

### meta
`Object`

A object collected from the route definiton. See [Routes definition](#routes-definition) below for details.

## Routes definition

```js
const routes = [
{
name: 'aside', // will be mounted into
component: { /* component definition */ }
},

{
path: '/basic',

// Definition without `name`.
// The component will be mounted into
component: { /* component definition */ }
},

// Return promise to define async components
{ path: '/async', component: () => import('./Component.vue') },

{
path: '/prop',

// Pass some props to the component
props: { foo: 'hello' },

component: {
props: ['foo'],
// ...
}
},

{
// Use `:paramName` to define params
// More pattern syntax, see https://github.com/jiangfengming/url-router
path: '/article/:id',

// props can be a factory function, it receives the current route object as the first argument.
props: route => ({
articleId: route.params.int('id'),
foo: route.query.string('foo'),
bar: route.state.bar
}),

component: {
props: ['articleId', 'foo', 'bar'],
// ...
},

// Setting key attribute of the .
// It will re-create the component instead of reusing it when key changes.
// So you needn't to watch the prop changes.
// See https://vuejs.org/v2/api/#key
// If key is a function, the returned value will be the key
key: route => route.params.int('id')
},

{
// param with regex
path: '/date/:year(\\d+)-:month(\\d+)',
component: VFoo,
props: route => ({ foo: route.params.int('year'), bar: route.params.int('month') })
},

// Define hooks
{
path: '/login',

// beforeEnter hook will be called before confirming the navigation.
// See global `beforeChange` event for details.
// Function | Array
// `this` refers to the router instance.
beforeEnter(to, from, action, router) {

},

component: {
// in-component beforeRouteLeave hook.
// Will be called before route leave.
// See global `beforeChange` event for details.
// Function | Array
// `this` refers to the vue component instance.
beforeRouteLeave(to, from, action, router) {

},

// ...
}
},

// Use array to group definitions
// Router view definitions in array will override outer definitions which has the same name.
[
{
name: 'aside',
component: { /* ... */}
},

{
// In this layout, the default will mount a component that has nested s
component: {
props: ['activeTab'],

// Define two child s
template: `


`
},

// Define some meta
meta: { activeTab: 'main' },

// route.meta.activeTab is "foo" when path is "/foo"
props: route => ({ activeTab: route.meta.activeTab })

// Define child s
children: [
{
name: 'footer',
component: { /* ... */ }
},

{
path: '/foo',
component: { /* ... */ },

// Parent route meta and child route meta will be merged together.
// If child route meta has same keys as parent, it will override parent ones.
meta: { activeTab: 'foo' }
},

[
// Override footer
{
name: 'footer',
component: { /* ... */ }
},

{
path: '/bar',
component: { /* ... */},

// meta can be a factory function
meta: route => ({ activeTab: route.query.string('active') })
}
],

// Define a catch-all route
{
path: '(.*)',
component: {
template: '

404 Not Found

## APIs
Most of the APIs are proxied to [spa-history](https://github.com/jiangfengming/spa-history).

In the vue instance, you can get the router object from `this.$router`.

### router.current
The current [matched route object](#matched-route-object).

### router.start()

```js
router.start(URL string | location)
```

Starts the router.

In browser, if URL/location is not given, the default value is the current address.

### router.normalize()

```js
router.normalize(URL string | location)
```

converts the URL string or unnormalized location object to a normalized object.

if URL/location.path is started with protocal, or `location.external` is `true`, `location.path` is treated as an external path, and will be converted to an internal path.

```js
// PathRouter with base '/foo/bar/'
router.normalize('http://www.example.com/foo/bar/home?a=1#b')
/*
{
path: '/home',
query: new StringCaster(new URLSearchParams('a=1')),
hash: '#b',
fullPath: '/home?a=1#b',
state: {}
}
*/

// same result as above
router.normalize({
path: '/foo/bar/home?a=1#b',
external: true
})

// same result as above
router.normalize('/home?a=1#b')

// same result as above
router.normalize({
path: '/home',
query: {
a: 1
},
hash: '#b'
})

// HashRouter
// same result as above
router.normalize('http://www.example.com/app/#/home?a=1#b')
```

The `query` property can be of type `Object`, `String` or `Array`. see [URLSearchParams()](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams) for detail.

### router.url()

```js
router.url(URL string | location)
```

```js
router.url({
path: '/home',
query: {
a: 1
},
hash: '#b'
})

// or
router.url('/home?a=1#b')

/*
result:
HashRouter: #/home?a=1#b
PathRouter(with base: '/foo/bar/'): /foo/bar/home?a=1#b
*/
```

### router.push()

```js
router.push(URL string | location)
```

Pushs the location onto the history stack. `beforeChange` event will be fired.

```js
router.push('/home?a=1#b')

router.push({
path: '/home',
query: {
a: 1
},
hash: '#b'
})

// PathRouter, complete URL
router.push('http://www.example.com/foo/bar/home?a=1#b')

// HashRouter, complete URL
router.push('http://www.example.com/#/home?a=1#b')
```

You can push a location with state.

```js
router.push({
path: '/home',
state: {
foo: 1,
bar: 2
}
})
```

And you can push a hidden location, which will not change the value of browser's address bar. the hidden location is stored in `window.history.state`

```js
router.push({
path: '/login',
state: {
foo: 1
},

// '/login' won't show in the location bar
hidden: true,

// optional. if set, the location bar will show this address instead
appearPath: '/buy'
})
```

### router.replace()

```js
router.replace(URL string | location)
```

Replaces the current history entry with the location specified.

### router.dispatch()

```js
router.dispatch(URL string | location)
```

Dispatchs the route without changing the history. That is, the location of browser's address bar won't be changed.

### router.setState()

```js
router.setState(state)
```

Sets state of the current route. the state will be merged into `router.current.state`

### router.go()

```js
router.go(position, { silent = false, state = null } = {})
```

Counterpart of `window.history.go()`. Returns a promise which will be resolved when `popstate` event fired.

`silent`: if true, `beforeChange` event won't be fired.

`state`: if set, the state object will be merged into the state object of the destination location.

### router.back()

```js
router.back(options)
```

Alias of `router.go(-1, options)`

### router.forward()

```js
router.forward(options)
```

Alias of `router.go(1, options)`

### router.captureLinkClickEvent()

```js
router.captureLinkClickEvent(event)
```

```html