You are browsing Nuxt 2 docs. Go to Nuxt 3 docs, or learn more about Nuxt 2 Long Term Support.

Nuxt Components

Nuxt comes with a few important components included out of the box, which will be helpful when building your application. The components are globally available, which means that you don't need to import them in order to use them.

In the following paragraphs, each of the included components is explained.


The Nuxt Component

The <Nuxt> component is the component you use to display your page components. Basically, this component gets replaced by what is inside your page components depending on the page that is being shown. Therefore it is important that you add the <Nuxt> component to your layouts.

layouts/default.vue
<template>
  <div>
    <div>My nav bar</div>
    <Nuxt />
    <div>My footer</div>
  </div>
</template>
The <Nuxt> component can only be used inside layouts .

The <Nuxt> component can take the prop of nuxt-child-key. This prop will be passed to <RouterView> so that your transitions will work correctly inside dynamic pages.

There are 2 ways to handle the internal key prop of <RouterView>.

  1. Use a nuxtChildKey prop on your <Nuxt> component
layouts/default.vue
<template>
  <div>
    <Nuxt :nuxt-child-key="someKey" />
  </div>
</template>
  1. Add the key option in page components as string or function
export default {
  key(route) {
    return route.fullPath
  }
}

The NuxtChild Component

This component is used for displaying the children components in a nested route.

Example:

-| pages/
---| parent/
------| child.vue
---| parent.vue

This file tree will generate these routes:

[
  {
    path: '/parent',
    component: '~/pages/parent.vue',
    name: 'parent',
    children: [
      {
        path: 'child',
        component: '~/pages/parent/child.vue',
        name: 'parent-child'
      }
    ]
  }
]

To display the child.vue component, you have to insert the <NuxtChild> component inside pages/parent.vue:

pages/parent.vue
<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtChild :foobar="123" />
  </div>
</template>

keep-alive

Both, the <Nuxt> component and the <NuxtChild/> component, accept keep-alive and keep-alive-props.

To learn more about keep-alive and keep-alive-props see the vue docs
layouts/default.vue
<template>
  <div>
    <Nuxt keep-alive :keep-alive-props="{ exclude: ['modal'] }" />
  </div>
</template>

<!-- will be converted into something like this -->
<div>
  <KeepAlive :exclude="['modal']">
    <RouterView />
  </KeepAlive>
</div>
pages/parent.vue
<template>
  <div>
    <NuxtChild keep-alive :keep-alive-props="{ exclude: ['modal'] }" />
  </div>
</template>

<!-- will be converted into something like this -->
<div>
  <KeepAlive :exclude="['modal']">
    <RouterView />
  </KeepAlive>
</div>

<NuxtChild> components can also receive properties like a regular Vue component.

<template>
  <div>
    <NuxtChild :key="$route.params.id" />
  </div>
</template>

To see an example, take a look at the nested-routes example .

To navigate between pages of your app, you should use the  <NuxtLink> component. This component is included with Nuxt and therefore you don't have to import it like you do with other components. It is similar to the HTML <a> tag except that instead of using a href="/about" you use to="/about". If you've used vue-router before, you can think of <NuxtLink> as a replacement of <RouterLink>

A simple link to the index.vue page in your pages folder:

<template>
  <NuxtLink to="/">Home page</NuxtLink>
</template>

The <NuxtLink> component should be used for all internal links. That means for all links to the pages within your site you should use <NuxtLink>. The <a> tag should be used for all external links. That means if you have links to other websites you should use the <a> tag for those.

<template>
  <div>
    <h1>Home page</h1>
    <NuxtLink to="/about"
      >About (internal link that belongs to the Nuxt App)</NuxtLink
    >
    <a href="https://v2.nuxt.com">External Link to another page</a>
  </div>
</template>
If you want to know more about <RouterLink>, feel free to read the Vue Router documentation  for more information.
<NuxtLink> also comes with smart prefetching out of the box.

Nuxt automatically includes smart prefetching. That means it detects when a link is visible, either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link. Nuxt only loads the resources when the browser isn't busy and skips prefetching if your connection is offline or if you only have 2g connection.

However sometimes you may want to disable prefetching on some links if your page has a lot of JavaScript or you have a lot of different pages that would be prefetched or you have a lot of third party scripts that need to be loaded. To disable the prefetching on a specific link, you can use the no-prefetch prop. Since Nuxt v2.10.0, you can also use the prefetch prop set to false

<NuxtLink to="/about" no-prefetch>About page not pre-fetched</NuxtLink>
<NuxtLink to="/about" :prefetch="false">About page not pre-fetched</NuxtLink>

Disable prefetching globally

To disable the prefetching on all links, set the prefetchLinks to false:

nuxt.config.js
export default {
  router: {
    prefetchLinks: false
  }
}

Since Nuxt v2.10.0, if you have set prefetchLinks to false but you want to prefetch a specific link, you can use the prefetch prop:

<NuxtLink to="/about" prefetch>About page pre-fetched</NuxtLink>

linkActiveClass

The linkActiveClass works the same as the vue-router class for active links. If we want to show which links are active all you have to do is create some css for the class nuxt-link-active .

.nuxt-link-active {
  color: red;
}
This css can be added to the navigation component or for a specific page or layout or in your main.css file.

If you want to you can also configure the class name to be something else. You can do this by modifying the linkActiveClass in the router property in your nuxt.config.js file.

export default {
  router: {
    linkActiveClass: 'my-custom-active-link'
  }
}
This option is given directly to the vue-router linkActiveClass. See the vue-router docs for more info.

linkExactActiveClass

The linkExactActiveClass works the same as the vue-router class for exact active links. If we want to show which links are active with an exact match all you have to do is create some css for the class nuxt-link-exact-active .

.nuxt-link-exact-active {
  color: green;
}
This css can be added to the navigation component or for a specific page or layout or in your main.css file.

If you want to you can also configure the class name to be something else. You con do this by modifying the linkExactActiveClass in the router property in your nuxt.config.js file.

nuxt.config.js
export default {
  router: {
    linkExactActiveClass: 'my-custom-exact-active-link'
  }
}
This option is given directly to the vue-router linkExactActiveClass. See the vue-router docs for more info

linkPrefetchedClass

The linkPrefetchedClass will allow you to add styles for all links that have been prefetched. This is great for testing which links are being prefetched after modifying the default behavior. The linkPrefetchedClass is disabled by default. If you want to enable it you need to add it to the router property in your nuxt-config.js file.

nuxt.config.js
export default {
  router: {
    linkPrefetchedClass: 'nuxt-link-prefetched'
  }
}

Then you can add the styles for that class.

.nuxt-link-prefetched {
  color: orangeRed;
}
In this example we have used the class nuxt-link-prefetched but you can name it anything you like

The client-only Component

This component is used to purposely render a component only on client-side. To import a component only on the client, register the component in a client-side only plugin.

pages/example.vue
<template>
  <div>
    <sidebar />
    <client-only placeholder="Loading...">
      <!-- this component will only be rendered on client-side -->
      <comments />
    </client-only>
  </div>
</template>

Use a slot as placeholder until <client-only /> is mounted on client-side.

pages/example.vue
<template>
  <div>
    <sidebar />
    <client-only>
      <!-- this component will only be rendered on client-side -->
      <comments />

      <!-- loading indicator, rendered on server-side -->
      <template #placeholder>
        <comments-placeholder />        
      </template>
    </client-only>
  </div>
</template>
Sometimes in server rendered pages $refs inside <client-only> might not be ready even with $nextTick, the trick might be to call $nextTick a couple of times:
page.vue
mounted(){
  this.initClientOnlyComp()
},
methods: {
  initClientOnlyComp(count = 10) {
    this.$nextTick(() => {
      if (this.$refs.myComp) {
        //...
      } else if (count > 0) {
        this.initClientOnlyComp(count - 1);
      }
    });
  },
}
If you are using a version of Nuxt < v2.9.0, use <no-ssr> instead of <client-only>