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.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.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 generatorbodyfor 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) => UnsafeHtmlMark 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): UnsafeHtmlMark 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 IlhaErrorError 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 IlhaErrorError 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.