Framework Components

Build your Astro website without sacrificing your favorite component framework.

Astro supports a variety of popular frameworks including React, Preact, Svelte, Vue, SolidJS, AlpineJS and Lit.

Installing Integrations

Astro ships with optional integrations for React, Preact, Svelte, Vue, SolidJS, AlpineJS and Lit. One or several of these Astro integrations can be installed and configured in your project.

To configure Astro to use these frameworks, first, install its integration and any associated peer dependencies:

npm install --save-dev @astrojs/react react react-dom

Then import and add the function to your list of integrations in astro.config.mjs:

import { defineConfig } from 'astro/config';

import react from '@astrojs/react';
import preact from '@astrojs/preact';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';
import lit from '@astrojs/lit';
import alpine from '@astrojs/alpinejs';

export default defineConfig({
  integrations: [react(), preact(), svelte(), vue(), solid(), lit(), alpine()],
});

⚙️ View the Integrations Guide for more details on installing and configuring Astro integrations.

⚙️ Want to see an example for the framework of your choice? Visit astro.new and select one of the framework templates.

Using Framework Components

Use your JavaScript framework components in your Astro pages, layouts and components just like Astro components! All your components can live together in /src/components, or can be organized in any way you like.

To use a framework component, import it from its relative path in your Astro component script. Then, use the component alongside other components, HTML elements and JSX-like expressions in the component template.

---
import MyReactComponent from '../components/MyReactComponent.jsx';
---
<html>
  <body>
    <h1>Use React components directly in Astro!</h1>
    <MyReactComponent />
  </body>
</html>

By default, your framework components will only render on the server, as static HTML. This is useful for templating components that are not interactive and avoids sending any unnecessary JavaScript to the client.

Hydrating Interactive Components

A framework component can be made interactive (hydrated) using a client:* directive. These are component attributes that determine when your component’s JavaScript should be sent to the browser.

With all client directives except client:only, your component will first render on the server to generate static HTML. Component JavaScript will be sent to the browser according to the directive you chose. The component will then hydrate and become interactive.

---
// Example: hydrating framework components in the browser.
import InteractiveButton from '../components/InteractiveButton.jsx';
import InteractiveCounter from '../components/InteractiveCounter.jsx';
import InteractiveModal from "../components/InteractiveModal.svelte"
---
<!-- This component's JS will begin importing when the page loads -->
<InteractiveButton client:load />

<!-- This component's JS will not be sent to the client until
the user scrolls down and the component is visible on the page -->
<InteractiveCounter client:visible />

<!-- This component won't render on the server, but will render on the client when the page loads -->
<InteractiveModal client:only="svelte" />

The JavaScript framework (React, Svelte, etc) needed to render the component will be sent to the browser along with the component’s own JavaScript. If two or more components on a page use the same framework, the framework will only be sent once.

Available Hydration Directives

There are several hydration directives available for UI framework components: client:load, client:idle, client:visible, client:media={QUERY} and client:only={FRAMEWORK}.

📚 See our directives reference page for a full description of these hydration directives, and their usage.

Mixing Frameworks

You can import and render components from multiple frameworks in the same Astro component.

---
// Example: Mixing multiple framework components on the same page.
import MyReactComponent from '../components/MyReactComponent.jsx';
import MySvelteComponent from '../components/MySvelteComponent.svelte';
import MyVueComponent from '../components/MyVueComponent.vue';
---
<div>
  <MySvelteComponent />
  <MyReactComponent />
  <MyVueComponent />
</div>

Passing Props to Framework Components

You can pass props from Astro components to framework components:

---
import TodoList from '../components/TodoList.jsx';
import Counter from '../components/Counter.svelte';
---
<div>
  <TodoList initialTodos={["learn Astro", "review PRs"]} />
  <Counter startingCount={1} />
</div>

Passing Children to Framework Components

Inside of an Astro component, you can pass children to framework components. Each framework has its own patterns for how to reference these children: React, Preact, and Solid all use a special prop named children, while Svelte and Vue use the <slot /> element.

---
import MyReactSidebar from '../components/MyReactSidebar.jsx';
---
<MyReactSidebar>
  <p>Here is a sidebar with some text and a button.</p>
</MyReactSidebar>

Additionally, you can use Named Slots to group specific children together.

For React, Preact, and Solid these slots will be converted to a top-level prop. Slot names using kebab-case will be converted to camelCase.

---
import MySidebar from '../components/MySidebar.jsx';
---
<MySidebar>
  <h2 slot="title">Menu</h2>
  <p>Here is a sidebar with some text and a button.</p>
  <ul slot="social-links">
    <li><a href="https://twitter.com/astrodotbuild">Twitter</a></li>
    <li><a href="https://github.com/withastro">GitHub</a></li>
  </ul>
</MySidebar>

export default function MySidebar(props) {
  return (
    <aside>
      <header>{props.title}</header>
      <main>{props.children}</main>
      <footer>{props.socialLinks}</footer>
    </aside>
  )
}

For Svelte and Vue these slots can be referenced using a <slot> element with the name attribute. Slot names using kebab-case will be preserved.

<aside>
  <header><slot name="title" /></header>
  <main><slot /></main>
  <footer><slot name="social-links" /></footer>
</aside>

Nesting Framework Components

Inside of an Astro file, framework component children can also be hydrated components. This means that you can recursively nest components from any of these frameworks.

---
import MyReactSidebar from '../components/MyReactSidebar.jsx';
import MyReactButton from '../components/MyReactButton.jsx';
import MySvelteButton from '../components/MySvelteButton.svelte';
---

<MyReactSidebar>
  <p>Here is a sidebar with some text and a button.</p>
  <div slot="actions">
    <MyReactButton client:idle />
    <MySvelteButton client:idle />
  </div>
</MyReactSidebar>

This allows you to build entire “apps” in your preferred JavaScript framework and render them, via a parent component, to an Astro page.

Can I use Astro Components inside my Framework Components?

Any UI framework component becomes an “island” of that framework. These components must be written entirely as valid code for that framework, using only its own imports and packages. You cannot import .astro components in a UI framework component (e.g. .jsx or .svelte).

You can, however, use the Astro <slot /> pattern to pass static content generated by Astro components as children to your framework components inside an .astro component.

---
import MyReactComponent from  '../components/MyReactComponent.jsx';
import MyAstroComponent from '../components/MyAstroComponent.astro';
---
<MyReactComponent>
  <MyAstroComponent slot="name" />
</MyReactComponent>

Can I Hydrate Astro Components?

If you try to hydrate an Astro component with a client: modifier, you will get an error.

Astro components are HTML-only templating components with no client-side runtime. But, you can use a <script> tag in your Astro component template to send JavaScript to the browser that executes in the global scope.

📚 Learn more about client-side <script> tags in Astro components