ilha

Use this page as a map of the public ilha API. Start with Introduction if you are building your first island.

Create an island

Import the callable default export:

import ilha from "ilha";

const Status = ilha(() => <p>Ready</p>);

const Greeting = ilha<{ name: string }>(({ input }) => (
  <p>Hello, {input.name}</p>
));

ilha(renderFn) is shorthand for ilha.render(renderFn). ilha<Props>(renderFn) is shorthand for .input<Props>().render(renderFn).

Use the builder when the island needs local capabilities:

const Counter = ilha
  .state("count", 0)
  .action("increment", (_, { state }) => {
    state.count((count) => count + 1);
  })
  .render(({ state, action }) => (
    <button onclick={action.increment}>
      Count: {state.count()}
    </button>
  ));

Builder chain

Call .render() exactly once and last.

API	Purpose	Learn more
`ilha.input<T>()` / `ilha.input(schema)`	Define typed, defaulted, or validated input props.	Input
`.as(tag)`	Choose the wrapper tag when this island is a child slot.	Render
`.state(key, initial?)`	Add local reactive state.	State
`.derived(key, fn)`	Add synchronous or abortable asynchronous derived data.	Derived
`.action(key, fn)`	Add a typed reusable operation with reactive status.	Actions
`.on(selector, handler)`	Add an advanced delegated or host event listener.	Advanced listeners
`.effect(fn)`	Run a reactive client effect with cleanup and cancellation.	Effect
`.onMount(fn)`	Run client setup once per mount and return optional cleanup.	On mount
`.onError(fn)`	Handle errors from this island.	On error
`.transition(options)`	Add enter and leave lifecycle transitions.	Transition
`.css(styles)`	Attach styles scoped to the island host.	CSS
`.render(fn)`	Finish the builder and return an `Island`.	Render

Declare actions before callbacks that consume them. Prefer lowercase native event props for element-owned events; reserve .on() for selectors, host listeners, full handler context, or combined modifiers.

Island methods

A completed island is callable and also exposes explicit rendering and lifecycle methods.

API	Purpose
`Island.toString(props?)`	Render synchronously to HTML.
`await Island(props?)`	Render to HTML when asynchronous children or derived data may exist.
`Island.mount(host, props?)`	Render and mount into one host; returns an unmount function.
`await Island.hydratable(props, options)`	Emit hydration markup with a name and optional state snapshot.
`Island.key(key)(props?)`	Create a keyed child invocation for reorderable or conditional lists.
`Island.define(tagName, options?)`	Register the island as a custom element.

Use mount({ Counter }) when the server already emitted named [data-ilha] hosts. Use Counter.mount(host, props) to render directly into one client host.

Helpers from `ilha`

import {
  mount,
  html,
  raw,
  css,
  signal,
  computed,
  effect,
  context,
  batch,
  untrack,
  from,
  onUncaughtError,
} from "ilha";

Export	Purpose	Learn more
`mount(registry, options?)`	Discover and mount named island hosts in the browser.	Mount
`html\`…``	Create escaped `RawHtml` template output.	HTML
`raw(value)`	Mark a trusted string as unescaped `RawHtml`.	Raw
`css\`…``	Create reusable CSS text for `.css()`.	CSS helper
`signal(initial)`	Create a standalone readable and writable signal.	Signals
`computed(fn)`	Create a lazy, cached, read-only value from signals.	Signals
`effect(fn)`	Run a standalone reactive effect; returns a stop function.	Signals
`context(key, initial)`	Get or create a keyed shared signal.	Signals
`context.delete(key)`	Remove one key from the context registry.	Signals
`context.clear()`	Clear the context registry, commonly between tests or HMR runs.	Signals
`batch(fn)`	Batch signal writes into one propagation pass.	Signals
`untrack(fn)`	Read signals without subscribing the active reactive scope.	Signals
`from(selector, island, props?)`	Mount an island into an existing selector or element.	Mount
`onUncaughtError(fn)`	Register a global fallback for otherwise uncaught island errors.	On error

Signal setters accept a value or updater:

count(1);
count((previous) => previous + 1);

A function argument is interpreted as an updater. Wrap function-valued replacements:

callback(() => nextCallback);

Actions

An action receives its payload first and context second:

.action("save", async (draft: Draft, { state, derived, input, host, signal }) => {
  const response = await fetch("/api/save", {
    method: "POST",
    body: JSON.stringify(draft),
    signal,
  });
  state.saved(await response.json());
})

Each action accessor is callable and exposes reactive status properties:

action.save.pending;
action.save.data;
action.save.error;

Native event props

Use lowercase DOM event names in JSX:

<button onclick={action.save}>Save</button>
<input oninput:abortable={(event, { signal }) => search(event, signal)} />

Handlers receive the native event and { signal }. Add at most one native modifier: :abortable, :once, :capture, or :passive.

JSX runtime

Use the automatic runtime with a pragma or tsconfig.json:

/** @jsxImportSource ilha */

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "ilha"
  }
}

Build tools resolve ilha/jsx-runtime in production and ilha/jsx-dev-runtime in development.

Intrinsic props are element-specific. Native event currentTarget and bind:* accessors use the element’s concrete DOM type. RawHtml is accepted by string-valued HTML and SVG attributes:

<img src={raw(icon)} alt="Icon" />
<svg>
  <use href={raw("#icon")} xlinkHref={raw("#icon")} />
</svg>

Common public types

import type {
  Island,
  KeyedIsland,
  RawHtml,
  HydratableOptions,
  MountOptions,
  MountResult,
  SignalAccessor,
  SignalSetter,
  SignalWriter,
  ExternalSignal,
  IslandState,
  IslandDerived,
  DerivedAccessor,
  DerivedValue,
  ActionAccessor,
  IslandActions,
  ActionContext,
  HandlerContext,
  HandlerContextFor,
  NativeEventHandler,
  NativeEventContext,
  NativeEventModifier,
  EffectContext,
  OnMountContext,
  ErrorContext,
  ErrorSource,
} from "ilha";

Type	Use it for
`Island`	A callable, renderable, mountable island.
`KeyedIsland`	A keyed child invocation returned by `Island.key()`.
`RawHtml`	Trusted HTML produced by `html` or `raw`.
`HydratableOptions`	Hydration name and snapshot options.
`MountOptions`	Registry mounting root and lazy behavior.
`MountResult`	Registry mount result, including its `unmount()` function.
`SignalAccessor`	A readable and writable signal, including `.select()`.
`SignalSetter`	A direct value or functional updater accepted by writable signals.
`SignalWriter`	The write target used by typed bindings such as `bind:this`.
`ExternalSignal`	A standalone signal accepted by templates and `bind:*`.
`IslandState`	Local state accessors exposed to island callbacks.
`IslandDerived`	Named derived accessors exposed to island callbacks.
`DerivedAccessor`	A derived value accessor with loading and error information.
`DerivedValue`	The `{ loading, value, error }` envelope behind a derived accessor.
`ActionAccessor`	A callable action with `.pending`, `.data`, and `.error`.
`IslandActions`	The typed action map exposed to island callbacks.
`ActionContext`	State, derived data, input, host, and abort signal passed to an action.
`HandlerContext`	Full context passed to advanced `.on()` listeners.
`HandlerContextFor`	Event-specific `.on()` context with typed event and target.
`NativeEventHandler`	Lowercase native event-prop handler type.
`NativeEventContext`	Native handler lifecycle context containing `signal`.
`NativeEventModifier`	`"abortable"`, `"once"`, `"capture"`, or `"passive"`.
`EffectContext`	Context passed to `.effect()`.
`OnMountContext`	Context passed to `.onMount()`.
`ErrorContext`	Context passed to `.onError()`.
`ErrorSource`	`"on"`, `"effect"`, `"mount"`, `"transition"`, or `"action"`.

Package	Guide
`@ilha/router`	Router
`@ilha/store`	Store
`@ilha/astro`	Astro