From: Eduardo San Martin Morote <posva13@gmail.com>
Date: Sat, 5 Sep 2020 14:29:40 +0000 (+0200)
Subject: docs: extending RouterLink
X-Git-Tag: v4.0.0-beta.10~61
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cb768bbbca8b742ddfa749a278f054a2ff7f1eae;p=thirdparty%2Fvuejs%2Frouter.git

docs: extending RouterLink
---

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
index b8dcae5c..83b32766 100644
--- a/docs/.vitepress/config.js
+++ b/docs/.vitepress/config.js
@@ -118,6 +118,10 @@ const config = {
                 link: '/guide/advanced/lazy-loading',
                 text: 'Lazy Loading Routes',
               },
+              {
+                link: '/guide/advanced/extending-router-link',
+                text: 'Extending RouterLink',
+              },
               {
                 link: '/guide/advanced/navigation-failures',
                 text: 'Navigation Failures',
diff --git a/docs/guide/advanced/composition-api.md b/docs/guide/advanced/composition-api.md
index a686f58c..6d7637f2 100644
--- a/docs/guide/advanced/composition-api.md
+++ b/docs/guide/advanced/composition-api.md
@@ -76,4 +76,32 @@ export default {
 }
 ```
 
-<!-- TODO: useLink -->
+Composition API guards can also be used anywhere, they don't have to be used directly on the route component as in-component guards.
+
+## `useLink`
+
+Vue Router exposes the internal behavior of RouterLink as a Composition API function. It gives access the same properties as the [`v-slot` API](#TODO):
+
+```js
+import { RouterLink, useLink } from 'vue-router'
+
+export default {
+  name: 'AppLink',
+
+  props: {
+    // add @ts-ignore if using TypeScript
+    ...RouterLink.props,
+    inactiveClass: String,
+  },
+
+  setup(props) {
+    const { route, href, isActive, isExactActive, navigate } = useLink(props)
+
+    const isExternalLink = computed(
+      () => typeof props.to === 'string' && props.to.startsWith('http')
+    )
+
+    return { isExternalLink, href, navigate, isActive }
+  },
+}
+```
diff --git a/docs/guide/advanced/extending-router-link.md b/docs/guide/advanced/extending-router-link.md
new file mode 100644
index 00000000..f52de393
--- /dev/null
+++ b/docs/guide/advanced/extending-router-link.md
@@ -0,0 +1,81 @@
+# Extending RouterLink
+
+The RouterLink component exposes enough `props` to suffice most basic applications but it doesn't try to cover every possible use case and you will likely find yourself using `v-slot` for some advanced cases. In most medium to large sized applications, it's worth creating one if not multiple custom RouterLink components to reuse them across your application. Some examples are Links in a Navigation Menu, handling external links, adding an `inactive-class`, etc.
+
+Let's extend RouterLink to handle external links as well and adding a custom `inactive-class` in an `AppLink.vue` file:
+
+```vue
+<template>
+  <a v-if="isExternalLink" v-bind="$attrs" :href="to" target="_blank">
+    <slot />
+  </a>
+  <router-link v-else v-bind="$props" v-slot="{ isActive, href, navigate }">
+    <a
+      v-bind="$attrs"
+      :href="href"
+      @click="navigate"
+      :class="isActive ? activeClass : inactiveClass"
+    >
+      <slot />
+    </a>
+  </router-link>
+</template>
+
+<script>
+import { RouterLink } from 'vue-router'
+
+export default {
+  name: 'AppLink',
+
+  props: {
+    // add @ts-ignore if using TypeScript
+    ...RouterLink.props,
+    inactiveClass: String,
+  },
+
+  computed: {
+    isExternalLink() {
+      return typeof this.to === 'string' && this.to.startsWith('http')
+    },
+  },
+}
+</script>
+```
+
+If you prefer using a render function or create `computed` properties, you can use the `useLink` from the [Composition API](./composition-api.md):
+
+```js
+import { RouterLink, useLink } from 'vue-router'
+
+export default {
+  name: 'AppLink',
+
+  props: {
+    // add @ts-ignore if using TypeScript
+    ...RouterLink.props,
+    inactiveClass: String,
+  },
+
+  setup(props) {
+    const useLink
+    const isExternalLink = computed(() => typeof props.to === 'string' && props.to.startsWith('http'))
+
+    return { isExternalLink }
+  }
+}
+```
+
+In practice, you might want to use your `AppLink` component for different parts of your application. e.g. using [Tailwind CSS](https://tailwindcss.com), you could create a `NavLink.vue` component with all the classes:
+
+```vue
+<template>
+  <AppLink
+    v-bind="$attrs"
+    class="inline-flex items-center px-1 pt-1 border-b-2 border-transparent text-sm font-medium leading-5 text-gray-500 focus:outline-none transition duration-150 ease-in-out hover:text-gray-700 hover:border-gray-300 focus:outline-none focus:text-gray-700 focus:border-gray-300 transition duration-150 ease-in-out"
+    active-class="border-indigo-500 text-gray-900 focus:border-indigo-700"
+    inactive-class="text-gray-500 hover:text-gray-700 hover:border-gray-300 focus:text-gray-700 focus:border-gray-300"
+  >
+    <slot />
+  </AppLink>
+</template>
+```