Add a UI framework integration

Sometimes a piece of the page really wants a framework. A search box with live results, a multi-step form with local state. For that, Astro has official integrations for React, Vue, Svelte, Solid, Preact, and more.

Install one with astro add. For React:

npx astro add react

The command installs @astrojs/react, react, and react-dom, then updates astro.config.mjs. It asks before each step, so read what it proposes.

After it runs, the config looks like this:

import { defineConfig } from 'astro/config'
import react from '@astrojs/react'

export default defineConfig({
  integrations: [react()]
})

Now write a React component in src/components/Counter.jsx:

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>Clicked {count} times</button>
}

And use it from an Astro page like any other component:

---
import Counter from '../components/Counter.jsx'
---

<Counter />

It renders, but it doesn’t work

Open the page. You see the button with “Clicked 0 times”. Click it. Nothing.

That’s not a bug. Astro rendered the component to HTML on the server and shipped the HTML. It did not ship React to the browser. Making it interactive is a separate decision called hydration, and you express it with a client:* directive. That’s the next lesson.

Check the Network panel now, before adding the directive. Filter by JS. No React bundle. That’s the baseline to remember.

The site is still Astro

Adding React doesn’t turn the project into a React app. Pages are still .astro. Markdown still renders. You could add Vue tomorrow with npx astro add vue and use both on the same page.

That flexibility is useful for migrations, when you have a valuable component you don’t want to rewrite. It’s also a trap. Two frameworks means two runtimes for visitors to download.

My advice is to pick one framework and stick with it. Add a second only for a concrete reason you can write down.