Passing Props to Islands

Props passed to a hydrated island are serialized to JSON and reconstructed in the browser. Functions, classes, and Dates need special care.

3 min read Level 2/5 #astro#islands#props

What you'll learn

Recognize what serializes
Convert non-serializable values
Avoid huge serialized payloads

When you hydrate an island, Astro serializes its props to JSON, embeds them in the page, and parses them back on the client. This works for almost everything — but a few types need care.

What Serializes Fine

Strings, numbers, booleans, null
Arrays and plain objects of the above
Dates (Astro round-trips them as ISO strings)
Nested combinations

What Doesn’t

Functions — onClick={fn} won’t work; the function can’t be reconstructed
Class instances — they round-trip as plain objects, losing methods
JSX / Astro components — pass children via <slot />, not as a prop, when possible
Live DOM references — meaningless in the serialized payload

For functions, define them inside the island itself or pass IDs and have the island look up the handler.

Example — What Works

---
import UserCard from "../components/UserCard.tsx";

const user = { id: 1, name: "Ada", joined: new Date("2026-01-01") };
const tags = ["js", "astro"];
---

<UserCard client:visible user={user} tags={tags} />

Inside the React UserCard:

export default function UserCard({ user, tags }) {
  // user.joined is a Date again
  return <article>{user.name} — {user.joined.toLocaleDateString()}</article>;
}

Example — What Doesn’t

<!-- ✗ onClick is a function — won't survive serialization -->
<MyButton client:load onClick={() => console.log("click")} />

The fix: define the handler inside the React component, or pass an identifier the component knows what to do with.

Watch The Size

Serialized props are inlined into the HTML. Passing a 10 MB JSON blob to an island doubles your page size. If the data is large:

Fetch it inside the island
Pass only what the island truly needs
Render the heavy stuff in the surrounding Astro template (which doesn’t need to serialize anything)

Up Next

Plain <script> tags — for behavior that doesn’t need a framework.

Scripts →