Templates

Pages, components, and layouts are all .html templates. Learn the shared syntax and the three roles a template can play.

Every .html file in Aero is a template. The same syntax — { } expressions, directives, <script is:build> — works in all of them. The difference is where the file lives and what role it plays:

Role	Directory	Purpose
Page	client/pages/	Becomes a URL via file-based routing
Component	client/components/	Reusable markup, imported into pages and layouts
Layout	client/layouts/	Shared page shell with <slot /> for content

Template auto-import

By default (templateAutoImport: true), Aero resolves -layout and -component tags from your project tree. You do not need a matching import in <script is:build> for each tag. The build, aero check, and the VS Code extension use the same rules: tag base name → client/layouts/*.html or client/components/**/*.html.

Still import explicitly: @content/*, npm packages, .ts / .js modules, and assets (@images/*, etc.).

When to add an explicit template import:

• Override — pin a non-default file for the same binding (e.g. import footer from '@components/theme/footer.html' for <footer-component />).
• Disambiguation — two files share a basename (e.g. components/toggle.html and components/theme/toggle.html); Aero errors until you import one path explicitly.
• Opt-out — set templateAutoImport: false in aero.config.ts to require imports for every layout/component (legacy behaviour).

Tag demo-list-component maps to binding demoList and file **/demo-list.html under components. Layout tags only search client/layouts/ (non-recursive); component tags search client/components/ recursively.

Pages

Every .html file in client/pages/ becomes a route. index.html maps to /, about.html maps to /about. See Routing for dynamic routes and getStaticPaths.

client/pages/about.html

<base-layout>
	<h1>About</h1>
	<p>This is a page.</p>
</base-layout>

Components

Components are .html files in client/components/. Use them as custom elements with the -component suffix; no import is required unless you are overriding or disambiguating (see Template auto-import):

client/components/greeting.html

<script is:build>
	const { name } = Aero.props
</script>

<h2>Hello, { name }!</h2>

client/pages/index.html

<greeting-component name="World" />

Explicit imports use the .html extension: import greeting from '@components/greeting.html'. When you add one, it overrides auto-import for that binding.

Props

Pass data to a component via attributes. Use { } for dynamic values:

<greeting-component name="World" />

<greeting-component name="{ site.author }" />

Inside the component, destructure from Aero.props:

<script is:build>
	const { name, greeting = 'Hello' } = Aero.props
</script>

<h2>{ greeting }, { name }!</h2>

Spread an object with props="{ ...obj }" to pass every key as a separate prop:

<card-component props="{ ...cardProps }" />

Use self-closing syntax (/>) when a component has no slot content. Use opening and closing tags to pass children into its <slot>:

<card-component title="Note">
	<p>This fills the card's default slot.</p>
</card-component>

Layouts

Layouts are .html files in client/layouts/ that wrap page content. Use <slot /> to mark where the content goes:

client/layouts/base.html

<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<title>My Site</title>
	</head>
	<body>
		<header>Site header</header>
		<slot />
		<footer>Site footer</footer>
	</body>
</html>

client/pages/about.html

<base-layout>
	<h1>About</h1>
	<p>This fills the default slot.</p>
</base-layout>

Nested layouts

A layout can use another layout. Content flows from page to inner layout to outer layout:

client/layouts/docs.html

<base-layout>
	<nav>Docs sidebar</nav>
	<main>
		<slot />
	</main>
</base-layout>

Named slots

Define named slots with the name attribute. Pages target them with slot:

client/layouts/base.html

<nav>
	<slot name="nav" />
</nav>
<main>
	<slot />
</main>

client/pages/home.html

<base-layout>
	<a href="/docs" slot="nav">Docs</a>
	<h1>Welcome</h1>
</base-layout>

Expressions

Wrap any JavaScript expression in single braces to interpolate it into text or attributes:

<script is:build>
	const title = 'Hello from Aero'
</script>

<h1>{ title }</h1>

Text interpolations are HTML-escaped by default. Use raw() for intentional unescaped HTML:

<p>{ raw(htmlString) }</p>

Loops

Use for (or for) with a for…of expression to repeat an element:

<ul>
	<li for="{ const item of items }">{ item }</li>
</ul>

Inside the loop body, Aero provides index, first, last, and length as automatic variables.

Conditionals

Use if, else-if, and else as attributes:

<div if="{ user }">Hello, { user.name }</div>
<p else>Not logged in.</p>

Switch / case

Match a value against multiple alternatives:

<div switch="{ status }">
	<p case="loading">Loading…</p>
	<p case="ready">Ready</p>
	<p default>Other</p>
</div>

Wrapperless output with <template>

Put a directive on <template> to emit only the children without a wrapper element:

<ul>
	<template for="{ const item of items }">
		<li>{ item.name }</li>
	</template>
</ul>

This works with if, for, and switch. It is especially useful inside <table> or <select> where an extra <div> would be invalid.

All directive attributes also accept a data- prefix for strict HTML spec compliance: for, if, else, etc.