v3.17
Nuxt on GitHub

Layout

Source
Nuxt Kit provides a set of utilities to help you work with layouts.

Layouts is used to be a wrapper around your pages. It can be used to wrap your pages with common components, for example, a header and a footer. Layouts can be registered using addLayout utility.

addLayout

Register template as layout and add it to the layouts.

In Nuxt 2 error layout can also be registered using this utility. In Nuxt 3+ error layout replaced with error.vue page in project root.

Usage

import { addLayout, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addLayout({
      src: resolve('templates/custom-layout.ts'),
      filename: 'custom-layout.ts',
    }, 'custom')
  },
})

Type

function addLayout(layout: NuxtTemplate | string, name: string): void

Parameters

layout: A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with src set to the string value. If a template object is provided, it must have the following properties:

PropertyTypeRequiredDescription
srcstringfalsePath to the template. If src is not provided, getContents must be provided instead.
filenamestringfalseFilename of the template. If filename is not provided, it will be generated from the src path. In this case, the src option is required.
dststringfalsePath to the destination file. If dst is not provided, it will be generated from the filename path and nuxt buildDir option.
optionsRecord<string, any>falseOptions to pass to the template.
getContents(data) => string | Promise<string>falseA function that will be called with the options object. It should return a string or a promise that resolves to a string. If src is provided, this function will be ignored.
writebooleanfalseIf set to true, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.

name: The name to register the layout under (e.g., default, custom, etc.).

Example

This will register a layout named custom that wraps pages with a header and footer.

import { addLayout, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addLayout({
      write: true,
      filename: 'my-layout.vue',
      getContents: () => `<template>
  <div>
    <header>My Header</header>
    <slot />
    <footer>My Footer</footer>
  </div>
</template>`,
    }, 'custom')
  },
})

You can then use this layout in your pages:

pages/about.vue
<script setup lang="ts">
definePageMeta({
  layout: 'custom',
})
</script>

<template>
  <div>About Page</div>
</template>
Due to the lack of support for virtual .vue files by @vitejs/plugin-vue, you can work around this limitation by passing write: true to the first argument of addLayout.