Skip to content
Ilha
Esc
↑↓navigate↵open⌘Jpreview
On this page

Core package reference

Public exports from the ilha package.

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

Component

A component is a function, async function, or generator that returns a view.

import { const atom: AtomFnatom } from "ilha";

const const Status: () => ViewStatus = () => <JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>Ready</JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>;

const 
const Greeting: ({ name }: {
    name: string;
}) => View
Greeting
= ({ name: stringname }: { name: stringname: string }) => <JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>Hello, {name: stringname}</JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>;
const const Counter: () => ViewCounter = () => { const const count: AtomHandle<number, number>count = atom<number>(init: number | Atom<number>, options?: AtomOptions<number> | undefined): AtomHandle<number, number> (+2 overloads)
An existing Effect atom, or a plain value. Store a function with `atom.lazy(() => fn)`; the `ilha/oxlint` rule `function-in-atom` flags `atom(fn)`.
atom
(0);
return ( <JSX.IntrinsicElements.button: ButtonHTMLAttributesbutton type?: string | undefinedtype="button" EventProps<HTMLButtonElement>.onclick?: ((event: Targeted<HTMLButtonElement, MouseEvent>) => void) | undefinedonclick={() => const count: AtomHandle<number, number>count.AtomHandle<number, number>.update: (f: (current: number) => number) => voidupdate((n: numbern) => n: numbern + 1)}> {const count: AtomHandle<number, number>count} </JSX.IntrinsicElements.button: ButtonHTMLAttributesbutton> ); };

Nested functions share the parent fiber. mount / renderToString on a function makes it a root.

Named exports

Export Purpose Learn more
atom(init, { equals? }) Writable reactive value; skip notify on equal writes State
atom.lazy(init) One-time initializer State
batch(fn) Coalesce multiple atom writes State
untrack(fn) Read atoms without subscribing State
createContext / context Atom-backed tree context Context and errors
ErrorBoundary Catch subtree failures Context and errors
watch(source, fn) Callback on atom or stream changes; receives { signal, onCleanup } State
watch.once(fn) Run once on mount; async callbacks with signal + promised cleanup State
when(stream, body) Per-emission generator (interrupts stale) Streams
h / Fragment JSX factory Templating
unsafe(html) Pre-rendered HTML painted without escaping Templating
IlhaError / IlhaCode Stable error codes with fix hints and docs links Errors
mount Activate a component in the DOM Render
renderToString Serialize a component to HTML Render

Element props

Every element accepts key and ref with no extra types. key reuses DOM nodes in lists; ref receives the live node on mount and null on unmount. Components accept key through JSX.IntrinsicAttributes — never add it to your own props. Disclosure and dialog events (ontoggle, onbeforetoggle, onclose, oncancel) type currentTarget to the element.

data-morph-preserve="a b" keeps the named live attributes across rerenders; the children token keeps the element’s live children. A user-opened <details> or <dialog> keeps open unless the render sets it explicitly. See Templating.

Paint Effect Stream values with yield Stream.map(...) — see Streams.

Data fetching, server-sent events, and custom elements are recipes, not exports — see Recipes.

atom

Call Meaning
atom(value) Writable atom
atom.lazy(fn) Run fn once on init
atom(effectAtom) Wrap an Effect atom
count() Read
count.set(v) Replace
count.update(fn) Patch
count.atom Underlying Effect atom

Derived values use Effect’s Atom.map or Atom.transform — pass handle.atom, then wrap in atom():

import * as import AtomAtom from "effect/reactivity/Atom";
import { const atom: AtomFnatom } from "ilha";

const const items: AtomHandle<number[], number[]>items = atom<number[]>(init: number[] | Atom.Atom<number[]>, options?: AtomOptions<number[]> | undefined): AtomHandle<number[], number[]> (+2 overloads)
An existing Effect atom, or a plain value. Store a function with `atom.lazy(() => fn)`; the `ilha/oxlint` rule `function-in-atom` flags `atom(fn)`.
atom
([1, 2]);
const const sum: AtomHandle<number, number>sum = atom<number>(init: number | Atom.Atom<number>, options?: AtomOptions<number> | undefined): AtomHandle<number, number> (+2 overloads)
An existing Effect atom, or a plain value. Store a function with `atom.lazy(() => fn)`; the `ilha/oxlint` rule `function-in-atom` flags `atom(fn)`.
atom
(
import AtomAtom.const map: <Atom.Atom<number[]>, number>(self: Atom.Atom<number[]>, f: (_: number[]) => number) => Atom.Atom<number> (+1 overload)
Maps the current value of an atom with a pure function. **Details** When the source atom is writable, the returned atom remains writable and keeps the source atom's write input type.
@stabilityunstable@categorycombinators@since4.0.0
map
(const items: AtomHandle<number[], number[]>items.AtomHandle<number[], number[]>.atom: Atom.Atom<number[]>atom, (list: number[]list) => list: number[]list.Array<number>.reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: number[]) => number, initialValue: number): number (+2 overloads)
Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
@paramcallbackfn A function that accepts up to four arguments. The reduce method calls the callbackfn function one time for each element in the array.@paraminitialValue If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.
reduce
((total: numbertotal, n: numbern) => total: numbertotal + n: numbern, 0))
);

Atoms from Effect

The initializer also accepts an Effect atom, an Effect, or a Stream:

const const status: AtomHandle<AsyncResult<string, never>, AsyncResult<string, never>>status = atom<string, never>(init: Effect.Effect<string, never, AtomRegistry> | Stream<string, never, AtomRegistry>, options?: AtomOptions<AsyncResult<string, never>> | undefined): AtomHandle<AsyncResult<string, never>, AsyncResult<string, never>> (+2 overloads)
An effect or stream runs once; the handle holds its `AsyncResult`.
atom
(const effect: Effect.Effect<string, never, never>effect);

The value of an Effect-backed atom is an Effect AsyncResult. During paint, waiting results keep the previous view, failures render the error text, and successes render the value. Use this to hold async data in atoms; for streams of views, prefer Streams.

watch

Order-based primitive — call at the top level of a component. watch(source, fn) runs fn when source changes and once on mount. Accepts an atom handle, handle.atom, or a Stream. watch.once(fn) runs fn once on mount; return a function to clean up on unmount.

Both forms pass { signal, onCleanup }: the signal aborts when a run goes stale or the component unmounts, and callbacks may be async with a promised cleanup.

when

Generator instruction — use with yield* inside a generator component. Prefer yielding a Stream of views directly when you do not need per-emission interruption.

  • when(stream, body) — run generator body for each value; a new value interrupts the previous body. SSR takes the first value.

Stream views (yield Stream.map(...)) also take one value on SSR. Side effects and user-gated flows use Effect (Stream.runForEach, Deferred) — see Streams.

unsafe

Marks a string as pre-rendered HTML and paints it without escaping:

import { const unsafe: (html: string) => UnsafeHtml
Mark a string as pre-rendered HTML and paint it without escaping. Use it for markup you built or sanitized yourself — SVG from an external library, Markdown rendered to HTML, embed codes. Never pass untrusted user input: unlike interpolated strings, this content is not escaped and scripts inserted this way do not run, but event attributes and other markup still apply.
unsafe
} from "ilha";
const
const Badge: ({ svg }: {
    svg: string;
}) => View
Badge
= ({ svg: stringsvg }: { svg: stringsvg: string }) => <JSX.IntrinsicElements.span: HTMLAttributes<HTMLSpanElement>span>{function unsafe(html: string): UnsafeHtml
Mark a string as pre-rendered HTML and paint it without escaping. Use it for markup you built or sanitized yourself — SVG from an external library, Markdown rendered to HTML, embed codes. Never pass untrusted user input: unlike interpolated strings, this content is not escaped and scripts inserted this way do not run, but event attributes and other markup still apply.
unsafe
(svg: stringsvg)}</JSX.IntrinsicElements.span: HTMLAttributes<HTMLSpanElement>span>;

Use it for markup you built or sanitized yourself — SVG from an external library, Markdown rendered to HTML, embed codes. Never pass untrusted user input. Inserted scripts do not run, but event attributes and other markup still apply, and the URL and style sanitizers that guard JSX props are skipped. See Templating.

renderToString

await renderToString(component, {
  snapshot?: boolean;      // embed atom values for hydration (default true)
  markers?: boolean;       // wrap in <div data-ilha> (default true)
  timeout?: number;        // serialize after this many ms even if busy
});

Waits until in-flight work is idle, then serializes. when and Stream views take one value.

mount

const unmount = mount(element, component, {
  hydrate?: boolean;              // restore snapshots from existing markup
  onError?: (error: Error) => void; // component failure hook
});

onError receives a failing root component and a nested component no ErrorBoundary caught, before the error view paints.

Errors

Failures throw IlhaError, which exposes code, fix, and docs:

import { class IlhaError
Error thrown by ilha with a stable `code`, a `fix` hint and a `docs` URL.
IlhaError
, const atom: AtomFnatom } from "ilha";
try { atom<number>(init: number | Atom<number>, options?: AtomOptions<number> | undefined): AtomHandle<number, number> (+2 overloads)
An existing Effect atom, or a plain value. Store a function with `atom.lazy(() => fn)`; the `ilha/oxlint` rule `function-in-atom` flags `atom(fn)`.
atom
(0);
} catch (var error: unknownerror) { if (var error: unknownerror instanceof class IlhaError
Error thrown by ilha with a stable `code`, a `fix` hint and a `docs` URL.
IlhaError
) {
var console: Consoleconsole.Console.log(...data: any[]): void (+1 overload)
The **`console.log()`** static method outputs a message to the console. [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)
log
(var error: IlhaErrorerror.IlhaError.code: IlhaCodecode, var error: IlhaErrorerror.IlhaError.fix: stringfix, var error: IlhaErrorerror.IlhaError.docs: stringdocs);
} }

Warnings go through console.warn with the same message shape, once per code and detail. Every code has a page under /errors.

ilha/renderer

createRenderer(ops) paints components into a host that is not a DOM: a native toolkit, a canvas scene graph, a test tree. You supply PaintOps; atoms, generators, streams, contexts, keyed components, and error boundaries behave as they do under mount().

import { createRenderer } from "ilha/renderer";
import type { PaintOps } from "ilha/renderer";

const renderer = createRenderer(ops);
const { unmount, ready, runtime } = renderer.mount(root, App, {
  onError?: (error: Error) => void;         // component failure hook
  onRuntime?: (runtime: IlhaRuntime) => void; // runs before the root component
});

Every paint materializes fresh host nodes and hands the complete child list of the painted root to ops.placeChildren(root, nodes). Your host decides what to keep. Holes (components, atoms, streams) are span hosts built with createElement.

Op Role
createElement, createText Build a host node
createRaw(html, parent) Nodes for an unsafe() view
placeChildren(root, nodes) Make a root’s children exactly nodes
morph(root, nodes, hydrate) Optional. Reconcile a root with a fresh render instead of placeChildren
reuseNode(host) Optional. Node to place for a hole that survived the repaint; defaults to the host
committed(el) Optional. The element a rendered element ended up as, for refs; defaults to el
setProp(el, key, value) Optional. Return true to claim a prop with its original value
setStyle, setFormControl Optional. Handle style and value / checked / selected; default to attributes
bindEvents(el, props, fiber) Optional. Bind event props; call the exported bindEvents to reuse Ilha’s

Without setProp, a prop reaches the host as a string attribute and a style object as CSS text. Implement it to receive objects as written.

onRuntime hands you the mount’s runtime before any component runs. Every fiber of the mount carries it, so getFiber().runtime identifies the mount from inside a component.

Types

Component, View, AtomHandle, UnsafeHtml, IlhaError, IlhaCode, MountOptions, RenderToStringOptions.

Was this page helpful?