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:

PackageFrameworkNotes
@astrojs/reactReactWorks with React function components
@astrojs/vueVueWorks with Vue single-file components
@astrojs/svelteSvelteSupports Svelte components and stores
@astrojs/preactPreactA smaller alternative to React
@astrojs/solidSolidFine-grained reactivity
@astrojs/litLitWeb component standard
@astrojs/alpinejsAlpineLightweight 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:

DirectiveHydration timingCost
NoneNeverNo JavaScript at all
client:visibleWhen it scrolls into viewDeferred until the reader reaches it
client:idleWhen the browser is idleDeferred until the main thread is free
client:mediaWhen a media query matchesLoaded only on matching devices
client:loadImmediatelyPaid on every page view
client:onlyOnly in the browser, never server-renderedRequired 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:

PackagePurpose
@astrojs/mdxLets you use components inside Markdown files
@astrojs/sitemapEmits a sitemap from the routes that were built
@astrojs/rssGenerates an RSS feed from a content collection
@astrojs/nodeServer adapter for a Node process
@astrojs/vercel, @astrojs/netlify, @astrojs/cloudflareServer adapters for the corresponding platforms
@astrojs/starlightA 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.

Found an issue with this content?

Tell us what could be improved.