directory-structure/layouts

22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Override layout per page with NuxtLayout

By setting `layout: false` in `definePageMeta`, you can use the `<NuxtLayout>` component directly within a page to override the layout on a per-page basis. This allows you to customize the layout structure for specific pages and use slots to pass content to different parts of the layout.

NuxtLayout as root element warning

If `<NuxtLayout>` is used within pages, it should not be the root element, or layout/page transitions should be disabled.

Layout components auto-import asynchronously

Components placed in the layouts directory are automatically loaded via asynchronous import when used, which provides best performance.

Single layout recommendation

If an application has only a single layout, it is recommended to use `app.vue` directly instead of creating a layout.

Layout must have single root element

Layouts must have a single root element to allow Nuxt to apply transitions between layout changes. The root element cannot be a `<slot />`.

Enable layouts with NuxtLayout component

To enable layouts in a Nuxt application, add the `<NuxtLayout>` component to your `app.vue` file wrapping the `<NuxtPage>` component.

How to use a layout in a page

There are three ways to use a layout: (1) Set a `layout` property in your page using `definePageMeta`, (2) Set the `name` prop of `<NuxtLayout>`, (3) Set the `appLayout` property in route rules.

Layout name normalization to kebab-case

Layout names are normalized to kebab-case, so a layout named `someLayout` becomes `some-layout`.

Default layout fallback

If no layout is specified, Nuxt will use `app/layouts/default.vue` as the default layout.

Default layout example

A default layout file at `app/layouts/default.vue` can contain shared content for all pages, with page content displayed in the `<slot />` component.

Named layouts in nested directories

When layouts are in nested directories, the layout name is based on its directory path and filename with duplicate segments removed. Examples: `~/layouts/desktop/default.vue` becomes `desktop-default`, `~/layouts/desktop-base/base.vue` becomes `desktop-base`, `~/layouts/desktop/index.vue` becomes `desktop`.

Layout naming convention recommendation

For clarity, it is recommended that the layout's filename matches its normalized kebab-case name, for example `DesktopDefault.vue` for the `desktop-default` layout.

Dynamic layout changes with setPageLayout

The `setPageLayout` helper function can be used to change the layout dynamically during runtime.

Set layout via route rules

Layouts can be set for specific routes or route patterns using the `appLayout` property in the `routeRules` configuration in `nuxt.config.ts`. Examples: `'/admin': { appLayout: 'admin' }` for a single route, `'/dashboard/**': { appLayout: 'dashboard' }` for multiple routes, `'/landing': { appLayout: false }` to disable layout for a route.

Passing props to layouts via definePageMeta

Props can be passed to layouts using the object syntax for the `layout` property in `definePageMeta`. Set the layout name in the `name` property and pass props in the `props` object. The layout can receive these props via `defineProps` with full type safety.

Passing props to layouts via setPageLayout

When changing the layout dynamically with `setPageLayout`, props can be passed as the second argument, for example: `setPageLayout('panel', { sidebar: true, title: 'Dashboard' })`.

Use NuxtLayout component with NuxtPage for multiple layouts

When your application requires different layouts for different pages, you can use the app/layouts/ directory with the <NuxtLayout /> component in app.vue to define multiple layouts and apply them per page. The structure would be <NuxtLayout><NuxtPage /></NuxtLayout>.

Page and layout transitions via definePageMeta

In Nuxt 3, page and layout transitions are defined using definePageMeta with a transition property, for example: definePageMeta({ transition: { name: 'page' } }). The style prop from <Nuxt> no longer applies to transition when used on <slot>, so styles should be moved to the -active CSS class.

Error layout migration path

In Nuxt 3, move ~/layouts/_error.vue to ~/error.vue. If you want to ensure this page uses a layout, you can use <NuxtLayout> directly within error.vue.

Use definePageMeta to select layout in Nuxt 3

In Nuxt 3, use the definePageMeta compiler macro to specify which layout a page uses. The syntax is: definePageMeta({ layout: 'layout-name' }). This replaces the Nuxt 2 approach of defining layout in component options.

Layout naming convention when referenced in pages

Layouts are kebab-cased when referenced in pages using definePageMeta. For example, a layout file named app/layouts/customLayout.vue is referenced as 'custom-layout' in the page's layout property.

Replace Nuxt component with slot in layouts

In Nuxt 3, layouts use slots instead of the <Nuxt> component that was used in Nuxt 2. You must replace <Nuxt /> with <slot /> within layout templates to render the current page. This also allows advanced use cases with named and scoped slots.

Give your agent this brain