docs: extending RouterLink

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
index b8dcae5cc26fd1c47c0e07aa50732905216bd96c..83b32766e0807bc691627b4544d372580efe0ae5 100644 (file)
--- 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 a686f58c42d4c6cd2ff43862048acb6a4fae2a01..6d7637f28788fb8590aacb24f899b67ea2ae88c5 100644 (file)
--- 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 (file)
index 0000000..f52de39
--- /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>
+```