How to use nested layouts astro

AstroHow-ToBeginner · 3 min read

How to Use Nested Layouts in Astro for Structured Pages

In Astro, you use nested layouts by creating layout components that wrap other layouts or pages with the <slot /> element. You import a parent layout inside a child layout and place <slot /> where the nested content should appear, allowing you to build layered page structures easily.

📐

Syntax

Nested layouts in Astro use the <slot /> element to define where child content appears inside a layout. You import a parent layout inside a child layout and wrap the <slot /> to nest content.

Key parts:

<slot />: Placeholder for nested content.
Importing layouts: Use import ParentLayout from './ParentLayout.astro' to nest layouts.
Wrapping content: Place <slot /> inside the parent layout to show child layout or page content.

astro

--- ParentLayout.astro ---
---
// This is the top-level layout
---
<html lang="en">
  <head>
    <title>Site Title</title>
  </head>
  <body>
    <header>Header content</header>
    <main>
      <slot />
    </main>
    <footer>Footer content</footer>
  </body>
</html>

--- ChildLayout.astro ---
---
import ParentLayout from './ParentLayout.astro'
---
<ParentLayout>
  <section class="child-layout">
    <h2>Child Layout Section</h2>
    <slot />
  </section>
</ParentLayout>

💻

Example

This example shows a nested layout where ChildLayout uses ParentLayout. The page content is rendered inside the child layout's <slot />, which is inside the parent layout's <slot />. This creates a page with header, footer, and a child section wrapping the page content.

astro

--- src/layouts/ParentLayout.astro ---
---
---
<html lang="en">
  <head>
    <title>My Astro Site</title>
  </head>
  <body>
    <header>
      <h1>Site Header</h1>
    </header>
    <main>
      <slot />
    </main>
    <footer>
      <p>Site Footer</p>
    </footer>
  </body>
</html>

--- src/layouts/ChildLayout.astro ---
---
import ParentLayout from './ParentLayout.astro'
---
<ParentLayout>
  <section style="border: 2px solid blue; padding: 1rem;">
    <h2>Child Layout Wrapper</h2>
    <slot />
  </section>
</ParentLayout>

--- src/pages/index.astro ---
---
import ChildLayout from '../layouts/ChildLayout.astro'
---
<ChildLayout>
  <p>Welcome to the nested layout example page!</p>
</ChildLayout>

Output

<html lang="en"> <head> <title>My Astro Site</title> </head> <body> <header> <h1>Site Header</h1> </header> <main> <section style="border: 2px solid blue; padding: 1rem;"> <h2>Child Layout Wrapper</h2> <p>Welcome to the nested layout example page!</p> </section> </main> <footer> <p>Site Footer</p> </footer> </body> </html>

⚠️

Common Pitfalls

Common mistakes when using nested layouts in Astro include:

Forgetting to include <slot /> in layouts, which causes child content not to render.
Not importing the parent layout correctly inside the child layout.
Trying to nest layouts without wrapping the child content inside the parent layout component.

Always ensure each layout has a <slot /> and that you import and wrap layouts properly.

astro

--- Wrong: Missing <slot /> in ParentLayout ---
---
<html lang="en">
  <body>
    <header>Header</header>
    <!-- Missing <slot /> here -->
    <footer>Footer</footer>
  </body>
</html>

--- Right: Add <slot /> to render child content ---
---
<html lang="en">
  <body>
    <header>Header</header>
    <main>
      <slot />
    </main>
    <footer>Footer</footer>
  </body>
</html>

📊

Quick Reference

Parent Layout: Defines main page structure with <slot /> for nested content.
Child Layout: Imports and wraps Parent Layout, adds its own structure and <slot />.
Page: Uses Child Layout and provides page-specific content inside.
Always use <slot /> to pass content down the layout chain.

✅

Key Takeaways

Use in layouts to define where nested content appears.

Import and wrap parent layouts inside child layouts to nest them.

Each layout must include to pass content down.

Pages use the most nested layout and provide their content inside it.

Missing causes child content not to render.