|
| 1 | +--- |
| 2 | +title: Composition |
| 3 | +description: Embed child islands directly inside a parent's template, rendered inline during SSR and activated independently on the client. |
| 4 | +--- |
| 5 | + |
| 6 | +# Composing Islands |
| 7 | + |
| 8 | +Child islands are interpolated directly inside a parent's html`` template. The child is rendered inline during SSR and activated independently on the client. Each child is managed as its own island — it owns its own state, lifecycle, and reactivity. |
| 9 | + |
| 10 | +## Basic usage |
| 11 | + |
| 12 | +```ts twoslash |
| 13 | +import ilha, { html } from "ilha"; |
| 14 | + |
| 15 | +const Icon = ilha.render(() => `<svg>…</svg>`); |
| 16 | + |
| 17 | +const Card = ilha.render( |
| 18 | + () => html` |
| 19 | + <div class="card"> |
| 20 | + ${Icon} |
| 21 | + <p>Card content</p> |
| 22 | + </div> |
| 23 | + `, |
| 24 | +); |
| 25 | +``` |
| 26 | + |
| 27 | +## Passing props to a child |
| 28 | + |
| 29 | +Call the child island with a props object to forward data: |
| 30 | + |
| 31 | +```ts twoslash |
| 32 | +import ilha, { html } from "ilha"; |
| 33 | +import { z } from "zod"; |
| 34 | + |
| 35 | +const Badge = ilha |
| 36 | + .input( |
| 37 | + z.object({ |
| 38 | + label: z.string(), |
| 39 | + color: z.string().default("teal"), |
| 40 | + }), |
| 41 | + ) |
| 42 | + .render(({ input }) => html` <span style="background:${input.color}">${input.label}</span> `); |
| 43 | + |
| 44 | +const Card = ilha.render( |
| 45 | + () => html` |
| 46 | + <div> |
| 47 | + ${Badge({ label: "New", color: "coral" })} // [!code highlight] |
| 48 | + <p>Content</p> |
| 49 | + </div> |
| 50 | + `, |
| 51 | +); |
| 52 | +``` |
| 53 | + |
| 54 | +Props are validated against the child island's schema, so type errors surface at authoring time. |
| 55 | + |
| 56 | +## Multiple children |
| 57 | + |
| 58 | +Interpolate as many child islands as needed: |
| 59 | + |
| 60 | +```ts twoslash |
| 61 | +import ilha, { html } from "ilha"; |
| 62 | + |
| 63 | +const Avatar = ilha.render(() => `<img src="/avatar.png" />`); |
| 64 | +const Actions = ilha.render(() => html`<button>Follow</button>`); |
| 65 | + |
| 66 | +const Profile = ilha.render( |
| 67 | + () => html` |
| 68 | + <div class="profile"> |
| 69 | + ${Avatar} |
| 70 | + <div class="profile-actions">${Actions}</div> |
| 71 | + </div> |
| 72 | + `, |
| 73 | +); |
| 74 | +``` |
| 75 | + |
| 76 | +## Keyed children |
| 77 | + |
| 78 | +Use `.key()` when a child may reorder or appear conditionally. Keys must be unique within a parent render: |
| 79 | + |
| 80 | +```ts twoslash |
| 81 | +const items = [] as any[]; |
| 82 | +// ---cut--- |
| 83 | +import ilha, { html } from "ilha"; |
| 84 | + |
| 85 | +const Item = ilha.input<{ name: string }>().render(({ input }) => html`<span>${input.name}</span>`); |
| 86 | + |
| 87 | +const List = ilha.render( |
| 88 | + () => |
| 89 | + html`<ul> |
| 90 | + ${items.map((item) => html`<li>${Item.key(item.id)({ name: item.name })}</li>`)} |
| 91 | + </ul>`, |
| 92 | +); |
| 93 | +``` |
| 94 | + |
| 95 | +## SSR behavior |
| 96 | + |
| 97 | +During SSR, interpolating a child island renders its HTML inline as part of the parent's output. The child island's styles, derived values, and render function all run as part of the parent's SSR pass. |
| 98 | + |
| 99 | +```html |
| 100 | +<!-- Output of Card.toString() --> |
| 101 | +<div class="card"> |
| 102 | + <svg>…</svg> |
| 103 | + <p>Card content</p> |
| 104 | +</div> |
| 105 | +``` |
| 106 | + |
| 107 | +## Client behavior |
| 108 | + |
| 109 | +On the client, each child is mounted independently into its own host element. The parent manages the lifecycle of its children — when the parent unmounts, all children are unmounted too. |
| 110 | + |
| 111 | +Children are preserved across parent re-renders. If a keyed list reorders, live child subtrees are detached before the parent morphs and reattached afterwards, so DOM state, listeners, and internal state remain intact. |
| 112 | + |
| 113 | +## Accessing child state from the parent |
| 114 | + |
| 115 | +Child islands are self-contained — the parent cannot directly read or write the child's state. If you need to share values between parent and child, use [`context()`](/guide/helpers/context) to create a shared global signal that both islands can read and write: |
| 116 | + |
| 117 | +```ts twoslash |
| 118 | +import ilha, { html, context } from "ilha"; |
| 119 | + |
| 120 | +const expanded = context("card.expanded", false); |
| 121 | + |
| 122 | +const Toggle = ilha |
| 123 | + .on("button@click", () => expanded(!expanded())) |
| 124 | + .render(() => html`<button>Toggle</button>`); |
| 125 | + |
| 126 | +const Content = ilha |
| 127 | + .effect(() => { |
| 128 | + // reacts to expanded signal from sibling |
| 129 | + }) |
| 130 | + .render(() => html`<p>Content</p>`); |
| 131 | + |
| 132 | +const Card = ilha.render(() => html` <div>${Toggle} ${Content}</div> `); |
| 133 | +``` |
| 134 | + |
| 135 | +## Notes |
| 136 | + |
| 137 | +- The parent's render cycle and the child's render cycle are independent. A state change in a child does not trigger a re-render in the parent. |
| 138 | +- Child props are serialized as `data-ilha-props` on the child's host element, so they are available during hydration without passing them again manually. |
| 139 | +- A dev warning is logged when two children in the same parent render share the same key. |
0 commit comments