<NuxtLayout>

Nuxtは、ページやエラーページにレイアウトを表示するための<NuxtLayout>コンポーネントを提供します。

<NuxtLayout />コンポーネントを使用して、app.vueまたはerror.vueでdefaultレイアウトを有効にすることができます。

app.vue

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

こちらも参照 guide > directory-structure > layouts

Props

name: レンダリングするレイアウト名を指定します。文字列、リアクティブな参照、または計算プロパティにすることができます。これはlayouts/ディレクトリ内の対応するレイアウトファイルの名前と一致している必要があります。
- type: string
- default: default

pages/index.vue

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

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

レイアウト名はケバブケースに正規化されることに注意してください。したがって、レイアウトファイルがerrorLayout.vueという名前の場合、<NuxtLayout />のnameプロパティとして渡されるときにはerror-layoutになります。

error.vue

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

こちらも参照 guide > directory-structure > layouts

fallback: 無効なレイアウトがnameプロップに渡された場合、レイアウトはレンダリングされません。このシナリオでレンダリングされるfallbackレイアウトを指定します。これはlayouts/ディレクトリ内の対応するレイアウトファイルの名前と一致している必要があります。
- type: string
- default: null

Additional Props

NuxtLayoutは、レイアウトに渡す必要がある任意の追加プロップも受け入れます。これらのカスタムプロップは属性としてアクセス可能になります。

pages/some-page.vue

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

上記の例では、titleの値はテンプレート内で$attrs.titleを使用するか、<script>内でuseAttrs().titleを使用してカスタム.vueで利用可能になります。

layouts/custom.vue

const layoutCustomProps = useAttrs()

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

Transitions

<NuxtLayout />は、Vueの<Transition />コンポーネントでラップされる<slot />を介してコンテンツをレンダリングし、レイアウトトランジションを有効にします。これが期待通りに機能するためには、<NuxtLayout />がページコンポーネントのルート要素でないことが推奨されます。

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

こちらも参照 getting-started > transitions

Layout's Ref

レイアウトコンポーネントのrefを取得するには、ref.value.layoutRefを通じてアクセスします。

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

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

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

こちらも参照 guide > directory-structure > layouts

tips

このセクションは公式ドキュメントの翻訳ではなく、本サイト独自の補足記事です。

NuxtLayoutコンポーネントの実践的な活用ガイド

Nuxt.jsでのレイアウト管理は、アプリケーションの見た目や構造を統一しつつ、ページごとに異なるデザインを適用するために欠かせません。NuxtLayoutコンポーネントは、こうしたレイアウトの切り替えや共通化を簡単に実現できる強力な仕組みです。

本記事では、Nuxt公式ドキュメントの説明を補完し、NuxtLayoutの使いどころや実務での具体例、注意すべきポイントを詳しく解説します。初〜中級のNuxtユーザーが、より効果的にレイアウトを活用できるようになることを目指しています。

まず結論：NuxtLayoutのポイントまとめ

レイアウトの切り替えを簡単に実現
nameプロパティで表示するレイアウトを動的に指定可能。ページごとに異なるレイアウトを柔軟に切り替えられる。
デフォルトレイアウトの指定が容易
app.vueやerror.vueでNuxtLayoutを使うことで、全体のデフォルトレイアウトを一括管理できる。
カスタムプロパティの受け渡しが可能
レイアウトに任意の属性を渡し、$attrsやuseAttrs()でアクセスできるため、柔軟なレイアウト設計が可能。
トランジション対応
Vueの<Transition>でラップされているため、レイアウト切り替え時にスムーズなアニメーションを実装できる。
レイアウトコンポーネントのref取得も可能
レイアウト内のメソッドや状態にアクセスしたい場合、ref.value.layoutRef経由で操作できる。

いつ使うべきか？使わない方がよいケース

使うべきケース

複数のページで共通の枠組みを持ちたいとき
ヘッダーやフッター、サイドバーなど共通部分をレイアウトにまとめることで、コードの重複を減らせる。
ページごとに異なるレイアウトを適用したいとき
管理画面と公開サイトでレイアウトを分ける、特定のページだけ特別なデザインにしたい場合に便利。
動的にレイアウトを切り替えたいとき
ユーザーの状態やルートに応じてレイアウトを切り替える柔軟なUIを実現できる。

使わない方がよいケース

単一のレイアウトしか使わない小規模アプリ
レイアウト切り替えの複雑さが不要な場合は、NuxtLayoutを使わずにapp.vueに直接共通部分を置くほうがシンプル。
レイアウト内で大量の状態管理やロジックを行いたい場合
レイアウトはあくまでUIの枠組みとして使い、ビジネスロジックはページやストアに分離したほうが保守性が高い。

実務でよくあるユースケースとサンプルコード

1. デフォルトレイアウトの設定

app.vueでNuxtLayoutを使い、全ページ共通のレイアウトを指定します。

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

このようにすることで、layouts/default.vueが全ページのベースレイアウトになります。

2. ページごとに異なるレイアウトを指定

ページコンポーネント内でnameを指定し、特定のレイアウトを適用します。

<script setup lang="ts">
const layoutName = 'admin'
</script>

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

layouts/admin.vueを用意しておけば、管理画面専用のUIを簡単に実装可能です。

3. レイアウトにカスタムプロパティを渡す

レイアウトにタイトルなどの情報を渡し、動的に表示内容を変えられます。

<template>
  <NuxtLayout name="custom" title="ユーザーダッシュボード">
    <NuxtPage />
  </NuxtLayout>
</template>

layouts/custom.vue内でuseAttrs()を使って受け取れます。

const attrs = useAttrs()
console.log(attrs.title) // "ユーザーダッシュボード"

よくある落とし穴・注意点

SSRとHydrationのズレに注意

NuxtLayoutのnameを動的に切り替える場合、サーバーサイドレンダリング（SSR）とクライアントサイドのHydrationで不一致が起きると、警告や表示崩れの原因になります。
動的なレイアウト指定は、できるだけサーバー側でも同じ値になるように制御しましょう。

レイアウトのルート要素にしないほうが良い

NuxtLayoutはトランジションを有効にするために、ページコンポーネントのルート要素でないことが推奨されています。
例えば、<div>などでラップしてからNuxtLayoutを配置すると、トランジションが期待通りに動作します。

パフォーマンスへの影響

レイアウト切り替え時に大きなコンポーネントを頻繁に再レンダリングすると、パフォーマンス低下の原因になります。
共通部分はできるだけレイアウトにまとめ、ページ固有の重い処理はページコンポーネントに分離するのが望ましいです。

まとめ

NuxtLayoutはNuxtアプリのレイアウト管理を強力にサポートするコンポーネントです。
共通UIの統一やページごとのレイアウト切り替えを簡単に実現でき、カスタムプロパティの受け渡しやトランジション対応も備えています。

ただし、SSRとの整合性やパフォーマンス面での注意も必要です。
本記事のポイントを押さえ、実務でのユースケースに応じて適切に活用すれば、より保守性の高いNuxtアプリ開発が可能になります。

レイアウト名はケバブケースに正規化されるため、ファイル名とnameプロパティの指定に注意してください。例えばerrorLayout.vueはerror-layoutとして指定します。

※このページは Nuxt.js 公式ドキュメントの翻訳ページです。

公式ドキュメントの該当ページはこちら：
https://nuxt.com/docs/3.x/api/components/nuxt-layout