gil-wiki/reference/4.api/1.components/3.nuxt-layout.md

title, description, links

title	description	links
<NuxtLayout>	Nuxt provides the <NuxtLayout> component to show layouts on pages and error pages.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-layout.ts xs

You can use <NuxtLayout /> component to activate the default layout on app.vue or error.vue.

<template>
  <NuxtLayout>
    some page content
  </NuxtLayout>
</template>

:read-more{to="/docs/4.x/directory-structure/app/layouts"}

Props

• name: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It must match the name of the corresponding layout file in the app/layouts/ directory, or false to disable the layout.
  • type: string | false
  • default: default

<script setup lang="ts">
// layouts/custom.vue
const layout = 'custom'
</script>

<template>
  <NuxtLayout :name="layout">
    <NuxtPage />
  </NuxtLayout>
</template>

::note Please note the layout name is normalized to kebab-case, so if your layout file is named errorLayout.vue, it will become error-layout when passed as a name property to <NuxtLayout />. ::

<template>
  <NuxtLayout name="error-layout">
    <NuxtPage />
  </NuxtLayout>
</template>

::read-more{to="/docs/4.x/directory-structure/app/layouts"} Read more about dynamic layouts. ::

• fallback: If an invalid layout is passed to the name prop, no layout will be rendered. Specify a fallback layout to be rendered in this scenario. It must match the name of the corresponding layout file in the app/layouts/ directory.
  • type: string
  • default: null

Additional Props

NuxtLayout also accepts any additional props that you may need to pass to the layout. These custom props are then made accessible as attributes.

<template>
  <div>
    <NuxtLayout
      name="custom"
      title="I am a custom layout"
    >
      <!-- ... -->
    </NuxtLayout>
  </div>
</template>

In the above example, the value of title will be available using $attrs.title in the template or useAttrs().title in <script setup> at custom.vue.

<script setup lang="ts">
const layoutCustomProps = useAttrs()

console.log(layoutCustomProps.title) // I am a custom layout
</script>

Layout Props from Page Meta

When using definePageMeta with the object syntax for layout, props are automatically passed to the layout component. The layout can receive them with defineProps:

<script setup lang="ts">
definePageMeta({
  layout: {
    name: 'admin',
    props: {
      sidebar: true,
    },
  },
})
</script>

<script setup lang="ts">
const props = defineProps<{
  sidebar?: boolean
}>()
</script>

::read-more{to="/docs/4.x/directory-structure/app/layouts#passing-props-to-layouts"} Read more about passing props to layouts. ::

Transitions

<NuxtLayout /> renders incoming content via <slot />, which is then wrapped around Vue’s <Transition /> component to activate layout transition. For this to work as expected, it is recommended that <NuxtLayout /> is not the root element of the page component.

::code-group

<template>
  <div>
    <NuxtLayout name="custom">
      <template #header>
        Some header template content.
      </template>
    </NuxtLayout>
  </div>
</template>

<template>
  <div>
    <!-- named slot -->
    <slot name="header" />
    <slot />
  </div>
</template>

::

:read-more{to="/docs/4.x/getting-started/transitions"}

Layout's Ref

To get the ref of a layout component, access it through ref.value.layoutRef.

::code-group

<script setup lang="ts">
const layout = ref()

function logFoo () {
  layout.value.layoutRef.foo()
}
</script>

<template>
  <NuxtLayout ref="layout">
    default layout
  </NuxtLayout>
</template>

<script setup lang="ts">
const foo = () => console.log('foo')
defineExpose({
  foo,
})
</script>

<template>
  <div>
    default layout
    <slot />
  </div>
</template>

::

:read-more{to="/docs/4.x/directory-structure/app/layouts"}