Skip to content

Commit 242a6aa

Browse files
posvaposva
committed
docs(api): add router-link
1 parent 28b4074 commit 242a6aa

File tree

3 files changed

+264
-187
lines changed

3 files changed

+264
-187
lines changed

‎docs/api/index.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,131 @@
1+
---
2+
sidebar: auto
3+
---
4+
15
# API Reference
26

37
- [Components](./vue-router-variable.md)
48
- [Enumerations](./vue-router-enum.md)
59
- [Functions](./vue-router-function.md)
610
- [Interfaces](./vue-router-interface.md)
711
- [Types](./vue-router-typealias.md)
12+
13+
## `<router-link>` props
14+
15+
### to
16+
17+
- type: [`RouteLocationRaw`](#routelocationraw)
18+
- required
19+
20+
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 [route ___location object](#routelocationraw).
21+
22+
```html
23+
<!-- literal string -->
24+
<router-link to="/home">Home</router-link>
25+
<!-- renders to -->
26+
<a href="/home">Home</a>
27+
28+
<!-- javascript expression using `v-bind` -->
29+
<router-link :to="'/home'">Home</router-link>
30+
31+
<!-- same as above -->
32+
<router-link :to="{ path: '/home' }">Home</router-link>
33+
34+
<!-- named route -->
35+
<router-link :to="{ name: 'user', params: { userId: '123' }}">User</router-link>
36+
37+
<!-- with query, resulting in `/register?plan=private` -->
38+
<router-link :to="{ path: '/register', query: { plan: 'private' }}">
39+
Register
40+
</router-link>
41+
```
42+
43+
### replace
44+
45+
- type: `boolean`
46+
- default: `false`
47+
48+
Setting `replace` prop will call `router.replace()` instead of `router.push()` when clicked, so the navigation will not leave a history record.
49+
50+
```html
51+
<router-link to="/abc" replace></router-link>
52+
```
53+
54+
### active-class
55+
56+
- type: `string`
57+
- default: `'router-link-active'` (or global [`routerLinkActiveClass`](#TODO))
58+
59+
Class to apply on the rendered `a` when the link is active.
60+
61+
### aria-current-value
62+
63+
- type: `'page' | 'step' | '___location' | 'date' | 'time' | 'true' | 'false'` (`string`)
64+
- default: `'page'`
65+
66+
Value passed to the attribute `aria-current` when the link is exactly active.
67+
68+
### custom
69+
70+
- type: `boolean`
71+
- default: `false`
72+
73+
Whether `<router-link>` should not wrap its content in an `<a>` element. Useful when using `v-slot` to create a custom RouterLink.
74+
75+
```html
76+
<router-link to="/home" custom v-slot="{ navigate, href, route }">
77+
<a :href="href" @click="navigate">{{ route.fullPath }}</a>
78+
</router-link>
79+
```
80+
81+
### exact-active-class
82+
83+
- type: `string`
84+
- default: `'router-link-exact-active'` (or global [`routerLinkExactActiveClass`](#TODO))
85+
86+
Class to apply when the link is exact active.
87+
88+
## `<router-link>`'s `v-slot`
89+
90+
`<router-link>` exposes a low level customization through a [scoped slot](https://v3.vuejs.org/guide/component-slots.html#scoped-slots). This is a more advanced API that primarily targets library authors but can come in handy for developers as well, to build a custom component like a _NavLink_ or other.
91+
92+
\*\*Remember to pass the `custom` option to `<router-link>` to prevent it from wrapping its content inside of an `<a>` element.
93+
94+
```html
95+
<router-link
96+
to="/about"
97+
custom
98+
v-slot="{ href, route, navigate, isActive, isExactActive }"
99+
>
100+
<NavLink :active="isActive" :href="href" @click="navigate">
101+
{{ route.fullPath }}
102+
</NavLink>
103+
</router-link>
104+
```
105+
106+
- `href`: resolved url. This would be the `href` attribute of an `<a>` element. It contains the `base` if any was provided.
107+
- `route`: resolved normalized ___location.
108+
- `navigate`: function to trigger the navigation. **It will automatically prevent events when necessary**, the same way `router-link` does, e.g. `ctrl` or `cmd` + click will still be ignored by `navigate`.
109+
- `isActive`: `true` if the [active class](#active-class) should be applied. Allows to apply an arbitrary class.
110+
- `isExactActive`: `true` if the [exact active class](#exact-active-class) should be applied. Allows to apply an arbitrary class.
111+
112+
### Example: Applying Active Class to Outer Element
113+
114+
Sometimes we may want the active class to be applied to an outer element rather than the `<a>` element itself, in that case, you can wrap that element inside a `router-link` and use the `v-slot` properties to create your link:
115+
116+
```html
117+
<router-link
118+
to="/foo"
119+
v-slot="{ href, route, navigate, isActive, isExactActive }"
120+
>
121+
<li
122+
:class="[isActive && 'router-link-active', isExactActive && 'router-link-exact-active']"
123+
>
124+
<a :href="href" @click="navigate">{{ route.fullPath }}</a>
125+
</li>
126+
</router-link>
127+
```
128+
129+
:::tip
130+
If you add a `target="_blank"` to your `a` element, you must omit the `@click="navigate"` handler.
131+
:::

‎docs/api/vue-router-enum.md

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
1+
---
2+
sidebar: auto
3+
---
4+
15
# Enum
26

37
## NavigationFailureType
48

5-
Enumeration with all possible types for navigation failures. Can be passed to to check for specific failures.
9+
Enumeration with all possible types for navigation failures. Can be passed to to check for specific failures.
610

711
**Signature:**
12+
813
```typescript
9-
export declare enum NavigationFailureType
14+
export declare enum NavigationFailureType
1015
```
1116

1217
### Members
1318

14-
| Member | Value| Description |
15-
| --- | --- | --- |
16-
| aborted | 4 | An aborted navigation is a navigation that failed because a navigation guard returned `false` or called `next(false)` |
17-
| cancelled | 8 | A cancelled navigation is a navigation that failed because a more recent navigation finished started (not necessarily finished). |
18-
| duplicated | 16 | A duplicated navigation is a navigation that failed because it was initiated while already being at the exact same ___location. |
19-
19+
| Member | Value | Description |
20+
| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------------- |
21+
| aborted | 4 | An aborted navigation is a navigation that failed because a navigation guard returned `false` or called `next(false)` |
22+
| cancelled | 8 | A cancelled navigation is a navigation that failed because a more recent navigation finished started (not necessarily finished). |
23+
| duplicated | 16 | A duplicated navigation is a navigation that failed because it was initiated while already being at the exact same ___location. |

0 commit comments

Comments
 (0)