Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Integrations with Frameworks

Using React, Vue and Svelte Components in Astro

Render React, Vue, Svelte, Solid and Preact components inside Astro pages, choose client directives, pass props and slots, and mix frameworks safely.

One of Astro's best features is that you are not locked into one UI library. You can drop a React counter, a Vue form and a Svelte chart into the same page, or reuse components from an older project. Each framework component is rendered to HTML on the server and, if you ask, hydrated in the browser as an independent island.

Set up a framework

Terminal
npx astro add react    # or vue, svelte, preact, solid

The integration registers a renderer that knows how to turn that framework's components into HTML at build time. After that, import and use a component like any other:

ASTRO
---
// src/pages/index.astro
import Counter from '../components/Counter.jsx';
import Greeting from '../components/Greeting.vue';
import Chart from '../components/Chart.svelte';
---
<h1>Mixed frameworks</h1>
<Counter initial={5} />
<Greeting name="Ada" />
<Chart client:visible data={[3, 5, 8]} />

With no client directive, a component renders to static HTML and ships zero JavaScript. That is the default and the reason Astro pages are fast: only the interactive parts cost bytes.

Client directives

A directive tells Astro when to load and hydrate a component:

Directive Hydrates Use for
client:load Immediately on page load Above-the-fold interactivity (menus, carts)
client:idle When the browser is idle (requestIdleCallback) Lower-priority widgets
client:visible When it scrolls into view Below-the-fold charts, comments
client:media="(max-width: 600px)" When the media query matches Mobile-only menus
client:only="react" Only in the browser, no server HTML Components that need window at start
ASTRO
<SearchBox client:idle />
<Comments client:visible />
<MobileNav client:media="(max-width: 768px)" />
<MapWidget client:only="react" />

client:only needs the framework name because there is no server render to infer it from. It also leaves an empty space in the HTML, so add a <div slot="fallback"> to reserve room.

Start with no directive. Add client:visible or client:idle when something must be interactive. Reach for client:load last.

Props across the island boundary

Props are serialised into the page so the browser can hydrate with the same data. Therefore they must be serialisable: strings, numbers, booleans, arrays, plain objects, Date, Map, Set, URL, BigInt, RegExp. Functions and class instances cannot cross:

ASTRO
---
const post = { title: 'Hello', tags: ['astro', 'islands'] };
---
<Card client:load post={post} />          <!-- OK -->
<Card client:load onSelect={() => {}} />  <!-- Error: functions are not serialisable -->

Handle events inside the island. If the parent .astro file needs to react, use a custom DOM event or shared store (next lesson).

Children and slots

Astro children become the framework's native slot idea:

ASTRO
<Panel client:load>
  <h2>Static heading rendered by Astro</h2>
  <p>Passed as children.</p>
</Panel>
  • React/Preact/Solid receive them as props.children.
  • Vue and Svelte receive them in the default slot.
  • Named slots: <div slot="footer"> maps to a Vue/Svelte named slot, or a prop in React (props.footer).

Astro renders the children once, on the server, and gives the island the resulting HTML. This keeps heavy static content out of the JavaScript bundle.

Mixing several frameworks

If you install more than one JSX-based framework (React, Preact, Solid), Astro must know which files belong to which. Use include and exclude:

JavaScript
// astro.config.mjs
import react from '@astrojs/react';
import preact from '@astrojs/preact';

export default defineConfig({
  integrations: [
    react({ include: ['**/react/*'] }),
    preact({ include: ['**/preact/*'] }),
  ],
});

Vue and Svelte have unique file extensions (.vue, .svelte) so they need no extra rules. Remember each extra framework adds its own runtime to pages that use it. Mixing is great for migrations and for using the best library, but for a new project pick one.

Things you cannot do

  • Import an Astro component inside a framework component. Pass Astro output in as children or slots instead.
  • Use Astro.props or frontmatter in a React file; it has its own props.
  • Share React context across islands: each island is its own root.

Hydration mismatch

Server and client output must match. Anything that differs on the first client render (random numbers, Date.now(), window.innerWidth) causes a mismatch warning. Initialise with a neutral value and update inside an effect or onMount:

JSX
import { useEffect, useState } from 'react';

export default function Clock() {
  const [now, setNow] = useState(null);
  useEffect(() => setNow(new Date().toLocaleTimeString()), []);
  return <p>{now ?? 'Loading...'}</p>;
}

Try it: the island idea

This stand-in is not Astro. It shows the principle: render everything to HTML first, then run per-island activation according to its directive.

JS Directive scheduler

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: can this prop cross the boundary?

A quick checker for props, modelled on what serialisation supports.

JS Serialisable props

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to a React component with no client directive?

    Astro renders framework components on the server by default. Without a directive nothing is sent to hydrate them.
  2. 2. Which directive fits a comments widget at the bottom of a long article?

    client:visible waits until the component scrolls into view, so users who never reach the bottom never download its code.
  3. 3. Why can't you pass an event handler function from an .astro file to an island?

    The browser rebuilds props from serialised data. Functions cannot be written into HTML, so handlers must live inside the island.
  4. 4. With React and Preact both installed, how does Astro know which files belong to which?

    Both use .jsx/.tsx, so you must give each integration a glob pattern for its files.

Summary

  • Add a framework with astro add; components render to HTML on the server.
  • No directive means no JavaScript; use client:visible/idle before client:load.
  • Props must be serialisable; handle events inside the island.
  • Children become slots; multiple JSX frameworks need include.
  • Avoid hydration mismatches by keeping the first render deterministic.

Next: Sharing State Between Islands