How to use Nuxt layouts

31 January 2021
4 min read

Layouts are the backbone of your pages and components, you can use to create multiple different layouts in your application. Layouts can be used to insert sidebar and different content layouts across your application. You could even use them to provide different layouts for web and mobile.

Default Layout

When generating a new nuxt application, as we discussed in Getting started with Nuxt, and inspecting the basic nuxt project structure, you'll notice there is a file in the layouts called default.vue generated automatically. It is possible to modify the default layout or create your own custom ones.

The default layout is always used for pages that don't have a specific layout file set. If you open the layouts/default.vue there are only three nine in the template.

<template>
  <div>
    <Nuxt />
  </div>
</template>

The key component in this file is the <Nuxt />, the nuxt framework will inject your pages into this component, so when creating layout files it is important to remember to ensure that this component is present.

You can place and add any number of additional components and markup in your layout file with your nuxt component. For instance, you may want to create a simple three column layout for your app. In the example below you may have already created some reusable Nuxt components you would want to use in your layout.

<template>
  <div class="container">
    <site-header />
    <div class="3-columns">
      <div class="col-1"></div>
      <div class="col-2"> <Nuxt /></div>
      <div class="col-3"></div>
    </div>
   <site-footer />
  </div>
</template>

Creating custom layouts

Any files created or placed files in the top-level layout directory will create a custom layout that can be accessed by setting the layout in your page components.

You may be creating a more custom application that will have several sections, requiring a slightly different layout in each, with a different set of components etc. In a situation such as that creating custom layouts for each site section could help.

You can easily create custom layouts with .vue files and just put them in the layouts directory. For instance, we could create a Blog.vue component in the layout folder

// layouts/blog.vue
<template>
  <div>
    <div>This is my awesome blog page</div>
    <nuxt/>
  </div>
</template>

Then you can use the layout property in the page component to assign this custom layout to the page

// pages/blog.vue
export default {
  layout: 'blog'
}

Nuxt now will use this /layouts/blog.vue file as the base layout for this page component.

Create Custom error pages in Nuxt

Nuxt provides default error pages, which are found in the @nuxt package in the node_modules directory. Nuxt uses these pages to serve error pages for 404, 500 etc. These may be helpful, but you may want to customise these pages to make them more attractive in your production instance.

To start creating a custom error page simply create a new error.vue component in your layout directory and place the following code

<template>
  <div class="container">
    <h2 v-if="error.statusCode === 404">Page not found</h2>
    <h2 v-else>An error occurred</h2>
    <nuxt-link to="/">Home page</nuxt-link>
  </div>
</template>
<script>
export default {
  props: {
    error: {
      type: Object,
      required: true,
    },
  },
}
</script>

Initially this may seem counter-intuitive and confusing as it is placed inside the layouts directory instead of the pages directory, also notice that the <nuxt> component has been omitted from the page even though the component has been created in the layout folder. This is due to the special nature of the error page, you should also note that the error page that will be displayed will also include whatever markup defined in the layouts/defaul.vue.

You can edit and style the page however you want, add additional messaging etc. The error world is basically your oyster at this point.

It is possible to create a layout page for your error layout page, if you would like to drill down to a granular level

As an example you could create

// layouts/layout-error.vue
<template>
  <div>
    <h1>Error!</h1>
    <nuxt/>
  </div>
</template>

Then create and error page to use it

// layouts/error.vue
<script>
export default {
  layout: 'layout-error'
}
</script>

Conclusion

That is all basics you need to start working with layouts in Nuxt. The next inward layer in the Nuxt view is pages, and you will learn how to create custom ones for your application in the next section