Components and Integrations
Astro gives you two component systems that are meant to be used together. The first is the .astro component, which is a template with a server-side script block, a scoped stylesheet, and a slot for children. It renders to HTML and costs nothing at runtime. The second is any component from any supported UI framework, which is useful when you already have one, or when the widget genuinely needs client-side state. The skill is knowing which to reach for, and the decision is usually made by asking how much JavaScript the widget is worth.
A .astro component has three parts. The frontmatter block runs on the server during the build and is where props are read and data is fetched. The template is the markup, and it can use the values that the frontmatter produced. The style block is scoped to the component unless you opt out with is:global.
---
// src/components/Callout.astro
interface Props {
title?: string;
kind?: 'note' | 'warning';
}
const { title = 'Note', kind = 'note' } = Astro.props;
---
<div class={`callout callout--${kind}`}>
<p class="callout__title">{title}</p>
<slot />
<slot name="footer" />
</div>
<style>
.callout {
border-inline-start: 4px solid var(--accent);
padding: 1rem;
}
.callout__title {
font-weight: 600;
margin-block-end: 0.5rem;
}
</style>
A slot with a name lets a caller fill a specific region, and a slot with fallback content renders that content when the caller provides nothing. The same file can then be used like this in a page:
---
import Callout from '../components/Callout.astro';
---
<Callout title="Before you upgrade" kind="warning">
Back up your configuration file first.
<span slot="footer">See the <a href="/upgrade/">upgrade guide</a>.</span>
</Callout>
Framework components are added with an integration, and the official ones cover the common choices:
| Package | Framework | Notes |
|---|---|---|
@astrojs/react | React | Works with React function components |
@astrojs/vue | Vue | Works with Vue single-file components |
@astrojs/svelte | Svelte | Supports Svelte components and stores |
@astrojs/preact | Preact | A smaller alternative to React |
@astrojs/solid | Solid | Fine-grained reactivity |
@astrojs/lit | Lit | Web component standard |
@astrojs/alpinejs | Alpine | Lightweight interactivity inside the template |
The integration is added with a command that also updates the configuration file:
npx astro add react
npx astro add vue
npx astro add svelte
Afterwards a framework component is imported into a template like any other component, and the client directive decides how it arrives in the browser:
---
import SearchBox from '../components/SearchBox.jsx';
import Chart from '../components/Chart.vue';
import Toggle from '../components/Toggle.svelte';
---
<SearchBox client:load />
<Chart client:visible />
<Toggle client:idle />
The directive is the whole performance story. A component with no directive is rendered to HTML on the server and shipped as markup, so it is not interactive but it is free. A component with a directive is additionally shipped as JavaScript and hydrated in the browser, and the directive says when that happens:
| Directive | Hydration timing | Cost |
|---|---|---|
| None | Never | No JavaScript at all |
client:visible | When it scrolls into view | Deferred until the reader reaches it |
client:idle | When the browser is idle | Deferred until the main thread is free |
client:media | When a media query matches | Loaded only on matching devices |
client:load | Immediately | Paid on every page view |
client:only | Only in the browser, never server-rendered | Required for browser-only APIs |
client:only takes the framework name as a value, as in client:only="react", and it is the correct answer for a component that touches window, document, or a browser-only library during render. Such a component cannot be rendered on the server at all, so the directive tells Astro to skip that step and mount it directly in the browser.
The pieces fit together more flexibly than the name suggests. A framework component can be passed into an .astro component as a child, including through a named slot, and an .astro component can be passed into a framework component as a child. The usual division of labour is that .astro files own structure and content while framework components own behaviour, but nothing prevents a React island from rendering inside a slot of an Astro layout.
The rest of the framework is extended with integrations too, and the official set covers most deployment and content needs:
| Package | Purpose |
|---|---|
@astrojs/mdx | Lets you use components inside Markdown files |
@astrojs/sitemap | Emits a sitemap from the routes that were built |
@astrojs/rss | Generates an RSS feed from a content collection |
@astrojs/node | Server adapter for a Node process |
@astrojs/vercel, @astrojs/netlify, @astrojs/cloudflare | Server adapters for the corresponding platforms |
@astrojs/starlight | A complete documentation site theme built on Astro’s own primitives |
Starlight is worth calling out because it changes what you have to build. With it, a project gains a sidebar generated from a configuration file, a built-in search index, a dark mode toggle, a table of contents, and a set of callout and card components, all of which are ordinary Astro components you can restyle. A documentation site can therefore be a valid project in an afternoon rather than a week.
Three more capabilities sit on top of the component model. The ClientRouter component from astro:transitions enables client-side navigation between pages, so a link does not perform a full page load; it is imported into a layout and placed in the head, and it was known as ViewTransitions in earlier versions. Server islands let a component be deferred to the server and streamed into the page after the rest of it has loaded, using the server:defer prop on a component in a project that uses a server adapter. And Astro Actions provide a typed way to define and call server functions, with the schema validated on both sides:
// src/actions/index.ts
import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';
export const server = {
subscribe: defineAction({
input: z.object({ email: z.string().email() }),
handler: async ({ email }) => {
await saveSubscriber(email);
return { ok: true };
},
}),
};
Taken together, these pieces let you assemble a page from content, static templates, and interactive widgets that each carry only the cost they need. The rule of thumb that keeps a project fast is simple: default to no JavaScript, add a directive only when a component genuinely needs to be interactive, and reach for client:visible before client:load whenever the widget does not have to work before the reader scrolls to it.
