What You’ll Learn
In this guide, you’ll learn how to use Astro’s layout files to create a consistent structure for all your web pages. This means you can define common elements like headers and footers once and reuse them everywhere. We’ll cover creating a base layout, using slots to insert page-specific content, and applying this layout to different pages in your Astro project.
Why Use Layouts?
Imagine you’ve built a few pages for your website. You’ve added a header to each one. That’s fine for a few pages, but what if you add many more? Copying and pasting the same header code into every new page becomes a lot of work. If you ever want to change the header, you’d have to update it on every single page. This is where Astro’s layout files come in handy. They let you create a template once and use it to wrap all your pages.
Creating Your First Layout File
You can place layout files anywhere in your Astro project, but a common practice is to create a layouts folder inside the src directory. Let’s start by making that folder.
Create a new folder named
layoutsinside your project’ssrcdirectory.Inside the
layoutsfolder, create a new file. A good name for a main layout file isbase.astro. This file must be an Astro component, meaning it uses the.astrofile extension.
Designing the Base Layout
Now, let’s build the structure for our layout. We’ll take the existing template from a page and adapt it for our base layout. This layout will include common elements that appear on every page of your site.
Copy the entire HTML template from one of your existing page components (like your homepage).
Paste this code into your new
base.astrofile.Update the
<title>tag within the<head>section to your site’s name. For example, change it toBook Bytes.Add an
<h1>tag with your site’s title just before the navigation bar (<nav>) inside the header. This provides a visible site title on the page.Remove any
<h1>tags that were originally placed directly below the header. These were specific to the homepage and don’t belong in the general layout.Instead of the removed
<h1>, add a<main>tag. This tag will serve as a container for the unique content of each page.
Using Slots for Dynamic Content
How do we tell the layout where to put the content that’s unique to each page? We use a special component called <slot />. Think of it like a placeholder.
Inside the
<main>tag in yourbase.astrofile, add the self-closing<slot />tag. This tells Astro: ‘Whatever content is placed inside this layout component on a specific page should be displayed right here.’
Applying the Layout to a Page
Now that we’ve created our layout, let’s use it on a page. We’ll start with the homepage.
Go back to your homepage file (e.g.,
index.astroin thepagesfolder).Delete the entire existing HTML template from this file. We’re replacing it with our layout.
At the top of the file, between the two sets of three dashes (
---), you’ll find the front matter. This is where we can write JavaScript code. We need to import our layout component here.Add the following import statement in the front matter:
import BaseLayout from '../layouts/base.astro';. This line tells Astro where to find your layout component. The../means ‘go up one directory’, then intolayouts, and finally selectbase.astro.Expert Note: JavaScript or TypeScript code in Astro’s front matter runs during the build process or on the server, not in the user’s browser. This keeps your site fast.
Below the front matter, use the
BaseLayoutcomponent like an HTML tag. Wrap it with<BaseLayout></BaseLayout>.Place the content that should appear on this specific page *inside* the
<BaseLayout>tags. For example, add an<h2>Homepage</h2>tag.Save the file. When you view this page in your browser, you’ll see the header and navigation from your
base.astrolayout, with your<h2>Homepage</h2>content displayed within the main area.
Applying Layouts to Other Pages
Now, let’s apply this same layout to your other pages to ensure consistency across your site.
For each of your other pages (like
about.astroorbooks.astro), delete their existing HTML templates.In the front matter of each page, import the
BaseLayoutcomponent using the correct path. Remember to adjust the path if the page is in a subfolder.- For a page in the
pagesfolder (likeabout.astro), the path is:import BaseLayout from '../layouts/base.astro'; - For a page in a subfolder (like
pages/books.astro), you might need to go up an extra level:import BaseLayout from '../../layouts/base.astro';
- For a page in the
Use the
<BaseLayout></BaseLayout>component in the template section of the page.Place the specific content for that page (e.g.,
<h2>About Us</h2>or<h2>Our Books</h2>) inside the<BaseLayout>tags.Save each file. Now, when you navigate between your pages, you’ll see the consistent header and navigation defined in your
base.astrolayout, with each page’s unique content appearing below.
Benefits of Using Layouts
Using layout files in Astro significantly reduces repetitive code. Instead of copying common elements like headers, footers, or navigation bars to every page, you define them once in a layout. This makes your project cleaner, easier to manage, and much faster to update. If you need to change your site’s navigation, you only need to edit the base.astro file, and the change will automatically apply to all pages using that layout.
Source: Astro Crash Course #3 – Layouts (YouTube)
