Astro components

This chapter follows Creating an Astro project.

Astro components are the building block of pages, layouts, and UI. They run on the server, at build time for static routes or per request for on-demand routes, and produce HTML. Nothing in the component script reaches the browser unless you put it in a <script> tag.

The component script and the template

A component has two parts separated by a code fence. Above the fence is the component script, written in TypeScript or JavaScript. Below it is the template, which is HTML with expressions.

1
---
2
const name = 'Astro';
3
const items = ['Pages', 'Layouts', 'Components'];
4
const response = await fetch('https://example.com/api/status');
5
const status = await response.json();
6
---
7
<h2>Hello, {name}</h2>
8
<p>Status: {status.ok ? 'up' : 'down'}</p>
9
<ul>
10
  {items.map((item) => <li>{item}</li>)}
11
</ul>

The script runs once per render, and top-level await is allowed. A fetch here happens on the server, so API keys used in the script never reach the browser. For a static route the request happens during the build, and the result is baked into the HTML.

Template expressions

Curly braces evaluate JavaScript inside the template. Conditionals and lists use ordinary expressions rather than template-specific syntax:

1
---
2
const user = { name: 'Ada', admin: true };
3
const tags = ['astro', 'islands'];
4
const html = '<strong>trusted markup</strong>';
5
---
6
{user.admin && <span class="badge">Admin</span>}
7
{tags.length > 0 ? <p>{tags.join(', ')}</p> : <p>No tags</p>}
8
<p class:list={['card', { 'card--admin': user.admin }]}>Profile</p>
9
<div set:html={html} />

Two directives are worth knowing early. class:list builds a class string from strings, arrays, and objects. set:html injects a raw HTML string without escaping; use it only with content you trust, since everything else in braces is escaped by default.

Props

Components receive attributes as Astro.props. Declare an interface named Props and Astro type-checks every place the component is used:

1
---
2
interface Props {
3
  title: string;
4
  href: string;
5
  featured?: boolean;
6
}
7

8
const { title, href, featured = false } = Astro.props;
9
---
10
<a class:list={['card', { featured }]} href={href}>
11
  <h3>{title}</h3>
12
</a>

1
---
2
import Card from '../components/Card.astro';
3
---
4
<Card title="Routing" href="/routing/" featured />

Props are plain values. Functions can be passed to other Astro components, but there are no event handlers in the React sense, because the component never runs in the browser.

Slots

A <slot /> marks where child content goes. Named slots let a layout accept several regions, and content inside the slot tag is the fallback when nothing is passed:

1
---
2
interface Props {
3
  title: string;
4
}
5
const { title } = Astro.props;
6
---
7
<html lang="en">
8
  <head>
9
    <meta charset="utf-8" />
10
    <title>{title}</title>
11
  </head>
12
  <body>
13
    <header><slot name="header">Default header</slot></header>
14
    <main><slot /></main>
15
  </body>
16
</html>

1
---
2
import BaseLayout from '../layouts/BaseLayout.astro';
3
---
4
<BaseLayout title="About">
5
  <nav slot="header">Custom navigation</nav>
6
  <p>This paragraph fills the default slot.</p>
7
</BaseLayout>

A layout is nothing more than a component with a default slot that wraps a page. This site’s article pages use the same pattern, with a named hero slot for the page header.

Scoped styles

A <style> block in a component is scoped automatically. Astro adds a unique attribute to the component’s elements and rewrites selectors to match, so h3 in Card.astro cannot affect headings elsewhere.

1
<h3>Scoped heading</h3>
2

3
<style>
4
  h3 {
5
    color: rebeccapurple;
6
  }
7
</style>

Use :global(...) for selectors that must reach outside, such as Markdown content rendered into a slot, and <style is:global> for a whole global block. Pass server values into CSS with define:vars:

1
---
2
const accent = '#0b7285';
3
---
4
<style define:vars={{ accent }}>
5
  a {
6
    color: var(--accent);
7
  }
8
</style>

Client-side scripts

A <script> tag in a component is the way to run code in the browser without a UI framework. Astro bundles it, supports TypeScript and imports, and includes it once per page even if the component appears many times.

1
<button data-copy="npm create astro@latest">Copy</button>
2

3
<script>
4
  document.querySelectorAll<HTMLButtonElement>('[data-copy]').forEach((button) => {
5
    button.addEventListener('click', () => {
6
      navigator.clipboard.writeText(button.dataset.copy ?? '');
7
    });
8
  });
9
</script>

Because the script runs once for the page, select elements by attribute rather than assuming one instance. Server values reach the script through data-* attributes, as above. <script is:inline> opts out of processing and emits the tag exactly as written.

Images

astro:assets optimizes local images at build time. It infers width and height to prevent layout shift, converts to modern formats, and lazy-loads by default:

1
---
2
import { Image } from 'astro:assets';
3
import hero from '../assets/hero.png';
4
---
5
<Image src={hero} alt="Diagram of an Astro page with islands" />

Keep images you want optimized in src/, not public/; files in public/ are served as-is. Remote images work too, but need explicit width and height and an allowed domain in the config. <Picture /> produces several formats in a <picture> element.

Next: Routing in Astro.