mirror of https://github.com/nuxt/nuxt.git
210 lines
8.8 KiB
Markdown
210 lines
8.8 KiB
Markdown
---
|
|
title: "<NuxtLink>"
|
|
description: "Nuxt provides <NuxtLink> component to handle any kind of links within your application."
|
|
links:
|
|
- label: Source
|
|
icon: i-simple-icons-github
|
|
to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-link.ts
|
|
size: xs
|
|
---
|
|
|
|
::note
|
|
`<NuxtLink>` is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.)
|
|
::
|
|
|
|
## Internal Routing
|
|
|
|
In this example, we use `<NuxtLink>` component to link to another page of the application.
|
|
|
|
```vue [pages/index.vue]
|
|
<template>
|
|
<NuxtLink to="/about">
|
|
About page
|
|
</NuxtLink>
|
|
<!-- <a href="/about">...</a> (+Vue Router & prefetching) -->
|
|
</template>
|
|
```
|
|
|
|
### Passing Params to Dynamic Routes
|
|
|
|
In this example, we pass the `id` param to link to the route `~/pages/posts/[id].vue`.
|
|
|
|
```vue [pages/index.vue]
|
|
<template>
|
|
<NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
|
|
Post 123
|
|
</NuxtLink>
|
|
</template>
|
|
```
|
|
|
|
::tip
|
|
Check out the Pages panel in Nuxt DevTools to see the route name and the params it might take.
|
|
::
|
|
|
|
### Handling 404s
|
|
|
|
When using `<NuxtLink>` for `/public` directory files or when pointing to a different app on the same domain, you should use the `external` prop.
|
|
|
|
Using `external` forces the link to be rendered as an `a` tag instead of a Vue Router `RouterLink`.
|
|
|
|
```vue [pages/index.vue]
|
|
<template>
|
|
<NuxtLink to="/the-important-report.pdf" external>
|
|
Download Report
|
|
</NuxtLink>
|
|
<!-- <a href="/the-important-report.pdf"></a> -->
|
|
</template>
|
|
```
|
|
|
|
The external logic is applied by default when using absolute URLs and when providing a `target` prop.
|
|
|
|
## External Routing
|
|
|
|
In this example, we use `<NuxtLink>` component to link to a website.
|
|
|
|
```vue [app.vue]
|
|
<template>
|
|
<NuxtLink to="https://nuxtjs.org">
|
|
Nuxt website
|
|
</NuxtLink>
|
|
<!-- <a href="https://nuxtjs.org" rel="noopener noreferrer">...</a> -->
|
|
</template>
|
|
```
|
|
|
|
## `target` and `rel` Attributes
|
|
|
|
A `rel` attribute of `noopener noreferrer` is applied by default to absolute links and links that open in new tabs.
|
|
- `noopener` solves a [security bug](https://mathiasbynens.github.io/rel-noopener/) in older browsers.
|
|
- `noreferrer` improves privacy for your users by not sending the `Referer` header to the linked site.
|
|
|
|
These defaults have no negative impact on SEO and are considered [best practice](https://developer.chrome.com/docs/lighthouse/best-practices/external-anchors-use-rel-noopener).
|
|
|
|
When you need to overwrite this behavior you can use the `rel` and `noRel` props.
|
|
|
|
```vue [app.vue]
|
|
<template>
|
|
<NuxtLink to="https://twitter.com/nuxt_js" target="_blank">
|
|
Nuxt Twitter
|
|
</NuxtLink>
|
|
<!-- <a href="https://twitter.com/nuxt_js" target="_blank" rel="noopener noreferrer">...</a> -->
|
|
|
|
<NuxtLink to="https://discord.nuxtjs.org" target="_blank" rel="noopener">
|
|
Nuxt Discord
|
|
</NuxtLink>
|
|
<!-- <a href="https://discord.nuxtjs.org" target="_blank" rel="noopener">...</a> -->
|
|
|
|
<NuxtLink to="https://github.com/nuxt" no-rel>
|
|
Nuxt GitHub
|
|
</NuxtLink>
|
|
<!-- <a href="https://github.com/nuxt">...</a> -->
|
|
|
|
<NuxtLink to="/contact" target="_blank">
|
|
Contact page opens in another tab
|
|
</NuxtLink>
|
|
<!-- <a href="/contact" target="_blank" rel="noopener noreferrer">...</a> -->
|
|
</template>
|
|
```
|
|
|
|
## Props
|
|
|
|
### RouterLink
|
|
|
|
When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink` props](https://router.vuejs.org/api/interfaces/RouterLinkProps.html)
|
|
|
|
- `to`: Any URL or a [route location object](https://router.vuejs.org/api/#RouteLocation) from Vue Router
|
|
- `custom`: Whether `<NuxtLink>` should wrap its content in an `<a>` element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as [Vue Router's `custom` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-custom)
|
|
- `exactActiveClass`: A class to apply on exact active links. Works the same as [Vue Router's `exact-active-class` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-exactActiveClass) on internal links. Defaults to Vue Router's default `"router-link-exact-active"`)
|
|
- `replace`: Works the same as [Vue Router's `replace` prop](https://router.vuejs.org/api/interfaces/RouteLocationOptions.html#Properties-replace) on internal links
|
|
- `ariaCurrentValue`: An `aria-current` attribute value to apply on exact active links. Works the same as [Vue Router's `aria-current-value` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-ariaCurrentValue) on internal links
|
|
- `activeClass`: A class to apply on active links. Works the same as [Vue Router's `active-class` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-activeClass) on internal links. Defaults to Vue Router's default (`"router-link-active"`)
|
|
|
|
### NuxtLink
|
|
|
|
- `href`: An alias for `to`. If used with `to`, `href` will be ignored
|
|
- `noRel`: If set to `true`, no `rel` attribute will be added to the link
|
|
- `external`: Forces the link to be rendered as an `a` tag instead of a Vue Router `RouterLink`.
|
|
- `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/api/nuxt-config#crossoriginprefetch)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/api/nuxt-config#crossoriginprefetch) config.
|
|
- `prefetchOn`: Allows custom control of when to prefetch links. Possible options are `interaction` and `visibility` (default). You can also pass an object for full control, for example: `{ interaction: true, visibility: true }`. This prop is only used when `prefetch` is enabled (default) and `noPrefetch` is not set.
|
|
- `noPrefetch`: Disables prefetching.
|
|
- `prefetchedClass`: A class to apply to links that have been prefetched.
|
|
|
|
### Anchor
|
|
|
|
- `target`: A `target` attribute value to apply on the link
|
|
- `rel`: A `rel` attribute value to apply on the link. Defaults to `"noopener noreferrer"` for external links.
|
|
|
|
::tip
|
|
Defaults can be overwritten, see [overwriting defaults](#overwriting-defaults) if you want to change them.
|
|
::
|
|
|
|
## Overwriting Defaults
|
|
|
|
### In Nuxt Config
|
|
|
|
You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/api/nuxt-config#defaults)
|
|
|
|
::important
|
|
These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
|
|
::
|
|
|
|
```ts [nuxt.config.ts]
|
|
export default defineNuxtConfig({
|
|
experimental: {
|
|
defaults: {
|
|
nuxtLink: {
|
|
// default values
|
|
componentName: 'NuxtLink',
|
|
externalRelAttribute: 'noopener noreferrer',
|
|
activeClass: 'router-link-active',
|
|
exactActiveClass: 'router-link-exact-active',
|
|
prefetchedClass: undefined, // can be any valid string class name
|
|
trailingSlash: undefined // can be 'append' or 'remove'
|
|
}
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### Custom Link Component
|
|
|
|
You can overwrite `<NuxtLink>` defaults by creating your own link component using `defineNuxtLink`.
|
|
|
|
```js [components/MyNuxtLink.ts]
|
|
export default defineNuxtLink({
|
|
componentName: 'MyNuxtLink',
|
|
/* see signature below for more */
|
|
})
|
|
```
|
|
|
|
You can then use `<MyNuxtLink />` component as usual with your new defaults.
|
|
|
|
### `defineNuxtLink` Signature
|
|
|
|
```ts
|
|
interface NuxtLinkOptions {
|
|
componentName?: string;
|
|
externalRelAttribute?: string;
|
|
activeClass?: string;
|
|
exactActiveClass?: string;
|
|
trailingSlash?: 'append' | 'remove'
|
|
prefetch?: boolean
|
|
prefetchedClass?: string
|
|
prefetchOn?: Partial<{
|
|
visibility: boolean
|
|
interaction: boolean
|
|
}>
|
|
}
|
|
function defineNuxtLink(options: NuxtLinkOptions): Component {}
|
|
```
|
|
|
|
- `componentName`: A name for the component. Default is `NuxtLink`.
|
|
- `externalRelAttribute`: A default `rel` attribute value applied on external links. Defaults to `"noopener noreferrer"`. Set it to `""` to disable
|
|
- `activeClass`: A default class to apply on active links. Works the same as [Vue Router's `linkActiveClass` option](https://router.vuejs.org/api/interfaces/RouterOptions.html#Properties-linkActiveClass). Defaults to Vue Router's default (`"router-link-active"`)
|
|
- `exactActiveClass`: A default class to apply on exact active links. Works the same as [Vue Router's `linkExactActiveClass` option](https://router.vuejs.org/api/interfaces/RouterOptions.html#Properties-linkExactActiveClass). Defaults to Vue Router's default (`"router-link-exact-active"`)
|
|
- `trailingSlash`: An option to either add or remove trailing slashes in the `href`. If unset or not matching the valid values `append` or `remove`, it will be ignored.
|
|
- `prefetch`: Whether or not to prefetch links by default.
|
|
- `prefetchOn`: Granular control of which prefetch strategies to apply by default.
|
|
- `prefetchedClass`: A default class to apply to links that have been prefetched.
|
|
|
|
:link-example{to="/docs/examples/routing/pages"}
|