Rinch

A GUI framework for Rust that uses HTML and CSS for layout, renders natively, and won’t make you mass a single .clone() at a signal.

Live Demo — All Rinch components, running in your browser via WASM. Or run locally: cargo run --release -p ui-zoo-desktop

Philosophy

• HTML/CSS layout — The layout system that billions of people have already debugged for you, powered by Servo’s Stylo and Taffy’s flexbox.
• Fine-grained reactivity — Signal changes update one DOM node, not a component tree. No virtual DOM. No diffing.
• Components run once — Your function builds the DOM, closures keep it updated. That’s the whole model.
• Native performance — GPU rendering via Vello/wgpu, or software rendering via tiny-skia. A gpu build carries both, picks at run time, and falls back to software when the GPU will not start.
• WASM too — Same components, same signals, browser-native DOM. ~3MB binary, zero JavaScript.

Quick Example

use rinch::prelude::*;

#[component]
fn app() -> NodeHandle {
    let count = Signal::new(0);

    rsx! {
        div {
            p { "Count: " {|| count.get().to_string()} }
            button { onclick: move || count.update(|n| *n += 1), "+" }
        }
    }
}

fn main() {
    App::new(app).title("Counter").size(800, 600).run();
}

Signal is Copy. No .clone() before closures. The {|| ...} closure creates an Effect that tracks its dependencies and surgically updates that text node when count changes. The app function runs once, builds the DOM, and never runs again.

What’s Included

• 60+ Components — Buttons, inputs, modals, tabs, accordions, color pickers, trees, a rich text editor, and more.
• Theme System — 14 color palettes, dark mode, CSS variables for everything. Mantine-inspired.
• 5,000+ Icons — Tabler Icons with a type-safe enum. Dead code elimination drops the ones you don’t use.
• Native Platform — Menus, file dialogs, clipboard, system tray, transparent windows.
• Developer Tools — F12 DevTools, inspect mode, MCP server for Claude Code integration.
• Game Engine Embedding — Submit GPU textures or CPU pixels into a Rinch UI, or embed Rinch into your own render loop.

Getting Started

From zero to window in about ninety seconds.

Prerequisites

• Stable Rust, edition 2024. Rinch itself is built and tested with the one version its rust-toolchain.toml names (1.99.0 today); no nightly feature is needed.
• A C/C++ compiler (Stylo has native dependencies)
• On Linux: libfontconfig-dev and pkg-config (for font discovery)

Create a Project

cargo new my-app
cd my-app

Add Rinch

# Cargo.toml
[dependencies]
rinch = { git = "https://github.com/joeleaver/rinch.git", features = ["desktop", "components", "theme"] }

What the features do:

• "desktop" — windowing, event loop, software renderer. Required for desktop apps.
• "components" — the 60+ component library (Button, TextInput, Modal, etc.).
• "theme" — CSS variable generation, color palettes, dark mode. Auto-enabled by "components".
• "gpu" — adds GPU rendering via Vello/wgpu beside the software renderer; the window uses the GPU and falls back to software when it will not start (see Rendering Backends). Optional.
• "clipboard" — clipboard read/write. Optional.
• "file-dialogs" — native open/save dialogs. Optional.

Write Your App

use rinch::prelude::*;

#[component]
fn app() -> NodeHandle {
    let count = Signal::new(0);

    rsx! {
        Stack { gap: "md", p: "xl",
            Title { order: 1, "Hello, Rinch!" }
            Text { color: "dimmed", "Your first app. It only goes up from here." }

            Group { gap: "sm",
                Button { onclick: move || count.update(|n| *n += 1), "+" }
                Button { variant: "outline", onclick: move || count.set(0), "Reset" }
            }

            Text { size: "xl", {|| format!("Count: {}", count.get())} }
        }
    }
}

fn main() {
    App::new(app)
        .title("My App")
        .size(800, 600)
        .theme(ThemeProviderProps {
            primary_color: Some("cyan".into()),
            ..Default::default()
        })
        .run();
}

Run It

cargo run --release

Always use --release for running apps. Debug mode is slow because Stylo and Parley do serious work. Release builds are fast.

You should see a window with a title, description, two buttons, and a count that updates when you click “+”.

What Just Happened

1. #[component] injected a __scope: &mut RenderScope parameter. You never see it, but rsx! needs it.
2. rsx! built a DOM tree: created elements, set attributes, wired event handlers.
3. {|| format!("Count: {}", count.get())} created an Effect that reads count and updates a text node. When count changes, that closure re-runs and updates only that text node.
4. App::new(app)…run() opened a window, loaded theme CSS, mounted the component, and started the event loop. App is the one entry point: every startup option — title, size, theme, menu bar, window props, GPU device — is a method on it, and they all compose.

Your app function ran exactly once. It will never run again. The closures handle everything from here.

What’s Next

• RSX Syntax — The full macro syntax: elements, attributes, events, control flow.
• State Management — Signals, Memos, Stores, Context.
• Components — The full component library.
• Theming — Colors, dark mode, CSS variables.
• Writing Components — Build your own.
• WASM — Run in the browser.

RSX Syntax

RSX is a JSX-like syntax for building UI in Rust. It lets you write HTML-like markup directly in your Rust code.

How RSX Works

The rsx! macro generates DOM construction code that:

1. Creates DOM nodes via RenderScope
2. Sets up Effects for reactive expressions {|| ...}
3. Wires event handlers

This enables fine-grained reactive updates - when a signal changes, only the affected DOM nodes are updated, not the entire tree.

Component Signature

Components use the #[component] attribute macro and return a NodeHandle:

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
fn my_component() -> NodeHandle {
    rsx! {
        div { "Hello from my component!" }
    }
}
}

The #[component] macro injects the __scope: &mut RenderScope parameter automatically, which is used by rsx! to create DOM nodes and Effects.

Basic Syntax

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
fn example() -> NodeHandle {
    rsx! {
        div {
            h1 { "Hello, World!" }
            p { "This is a paragraph." }
        }
    }
}
}

HTML Elements

Standard HTML elements are written in lowercase:

#![allow(unused)]
fn main() {
rsx! {
    div {
        span { "Text content" }
        button { "Click me" }
        input { type: "text", placeholder: "Enter text..." }
    }
}
}

Attributes

Attributes are specified after the element name:

#![allow(unused)]
fn main() {
rsx! {
    div { class: "container", id: "main",
        a { href: "https://example.com", "Link text" }
        img { src: "image.png", alt: "Description" }
    }
}
}

Boolean attributes

A handful of HTML attributes carry no useful string: their presence is their value. disabled, checked, readonly, required, multiple, hidden, selected, open, autofocus and the rest of the HTML boolean set are all of this kind, and so are rinch’s own data-disabled, data-nofocus, data-trap-focus, data-backdrop and data-scroll-lock-exempt.

Write them as a bool — static or reactive — and rsx! renders the right shape rather than the string:

#![allow(unused)]
fn main() {
let busy = Signal::new(false);

rsx! {
    // true  → `disabled` (present, no value)
    // false → the attribute is removed
    button { disabled: {move || busy.get()}, "Rename" }
}
}

This matters because HTML has no falsey spelling: a present disabled attribute disables the control whatever it holds, so disabled="false" is still disabled. Writing the string would make the binding a one-way latch — the control could turn off and never back on (issue #551).

The rule is keyed on the attribute’s name, not on the value’s type, because several attributes that take a bool-looking value need the literal "false" kept:

#![allow(unused)]
fn main() {
rsx! {
    // `draggable` is an *enumerated* attribute: "true" / "false" are both
    // values, and removing it means `auto`. It keeps the string.
    div { draggable: {move || on.get()} }
    // So do the ARIA states, and rinch's own `data-viewport-ready` — an
    // opt-out whose *absence* means ready.
    div { aria-expanded: {move || open.get()} }
}
}

A closure that yields a string into a boolean attribute follows a writer’s truthiness rule: everything is on except "false" (any case) and "0", so the bare "" that components write stays on.

That rule is the writer’s, and for the HTML set it is nobody’s reader: no reader of disabled, checked, readonly and their kind has a falsey string on either backend, because a browser has none (issue #612). rinch’s own data-disabled, data-nofocus, data-trap-focus, data-backdrop and data-scroll-lock-exempt — listed as boolean attributes above — are the exception, and the only one: their readers do honour a literal "false", on desktop through rinch_core::dom::data_attr_is_on and, for the ones the web reads at all, through selectors like [data-nofocus]:not([data-nofocus="false" i]). That escape is narrower than the writer’s rule, too: "0" is on for those five.

Writing one by hand. set_attribute is the literal primitive on both backends: it writes the string you give it, so set_attribute("checked", "false") leaves the attribute present, and a present boolean attribute is true. There are two spellings of off, and neither is a string:

#![allow(unused)]
fn main() {
// Rendering a bool you already have — presence or absence, chosen for you.
node.write_attribute("checked", &flag.to_string());

// Or say it outright.
if flag { node.set_attribute("checked", "") } else { node.remove_attribute("checked") }
}

That was a real divergence until issue #622: the web backend mapped truthiness onto presence for checked and selected alone, so the same call unchecked a box in the browser and checked it on the desktop backend.

On the web, checked, <option selected> and a media element’s muted also drive the control’s live property, not only the attribute — a browser stops mirroring checked/selected’s attribute into the property once the user has toggled the control (and never mirrors muted’s dynamically at all; HTML reads it once, at load, to seed defaultMuted), and rinch has no such flag, so a programmatic write keeps winning. checked/selected follow the attribute’s presence, matching what the desktop backend’s :checked reads; muted is rinch’s own invention — deliberately more dynamic than plain HTML — because nothing else lets a reactive muted: {|| m.get()} binding mute or unmute a <video>/<audio> element at all (issue #754). The name is folded ASCII-lowercase before any of this is decided, so CHECKED/MUTED written in any case still mirror (issue #758) — desktop already folds the attribute name this way (#738); on the web the browser folds the written attribute itself, so only rinch’s own Rust-side matching needed the fold.

These three are also the reason a falsey write of them is never skipped. Turning a boolean attribute off is otherwise a no-op when the attribute is already gone, and write_attribute skips it to save a restyle — but on the web a user’s toggle (or, for muted, a <video controls>’s own mute button) leaves the property on with the attribute absent, so the skip was exactly the write that would have corrected it, and a box the user clicked stayed checked against a binding that said false (issue #687, and #754 for muted). checked, selected and muted now always reach the backend, which is the only layer that can see the property.

Component props are unaffected — a component’s disabled: bool is an ordinary typed field, and the component decides how to render it.

Event Handlers

Event handlers are on* attributes on HTML elements. Pointer/click handlers are Fn() closures; read the cursor position, button, and modifier keys from get_click_context():

#![allow(unused)]
fn main() {
use rinch::prelude::*;

rsx! {
    div {
        onclick: || println!("clicked"),
        onmousedown: || {
            let ctx = get_click_context();
            match ctx.button {
                MouseButton::Right => println!("right press"),
                _ if ctx.modifiers.shift => println!("shift+press"),
                _ => println!("press at {}, {}", ctx.mouse_x, ctx.mouse_y),
            }
        },
        onmouseup: || println!("released"),
        onmousemove: || { /* fires on each (coalesced) move over this element */ },
        onmouseenter: || println!("hover in"),
        onmouseleave: || println!("hover out"),
        oncontextmenu: || println!("right-click menu"),
        "Interactive"
    }
}
}

Supported HTML-element event attributes:

Pointer moves are coalesced

On desktop, winit can report several pointer moves between two frames — a 1000 Hz mouse does. The shell keeps only the newest one and hands it to the app before the next other event (so a press is judged where the pointer last was) or at the end of the batch. Hover, onmousemove, data-ondragover / data-ondragmove and a Drag::absolute() / Drag::percent() on_move all see one move per batch, at the latest position. This is the browser’s model: it dispatches pointermove at most once per frame. A component drag’s layout runs once per frame too, not once per move.

One pointer-capture drag at a time

Drag::start() ends any drag that is already live before arming its own, and it ends it through that drag’s on_cancel — never its on_end. Usually a press arming a drag while another is live means the earlier drag’s release was lost (a context menu or a window-manager grab swallowed it, or it went to another rinch document on the same thread — a DevTools window, a second embedded RinchContext), so there is no trustworthy position to commit. On a touch screen it can also be a second finger: rinch-web dispatches a second finger’s press, and a drag it arms cancels the first finger’s while that finger is still down — there is one drag at a time, not one per finger. Keep teardown in on_cancel and it runs on every ending but a commit — and an unmount of the component that armed the drag, which drops it without calling back.

A drag whose release never arrives is ended the same way, through on_cancel at the last position on_move saw. On rinch-web that happens on the first move that reports the button up. Desktop cannot see the button on a move, so it ends the drag on the next event that proves the release was missed: a left press (handled before the press reaches any handler, so nothing it dispatches sees the old drag) or the window losing focus. Until one of those arrives, the stranded drag keeps following the pointer. The same press or blur also ends a stranded element drag (cancelled: ondragend, no ondrop), a scrollbar-thumb drag and a text-selection drag.

Three consequences on desktop. A window blur mid-drag cancels the drag even when its release would still have arrived (on X11 and Wayland a global hotkey or a held Alt+Tab can blur the window during a healthy drag). A drag armed by the middle or right button is cancelled by a left press made while it is held. And a drag armed with no button down — from a shortcut or a timer, then placed with a click — is cancelled by that click, as the web cancels it on its first move. Arm a Drag from a press (onclick or onmousedown) and none of this reaches a normal gesture.

A drag ends on the release of the button that started it. On desktop a right or middle release while the left button still holds a drag is a chord, not the end of it: a left-armed Drag keeps following the pointer and commits on the left release, and the same holds for an element drag (it is not dropped), a scrollbar-thumb drag and a text-selection drag. A drag armed by a right press ends on the right release, and a drag armed outside any press (a timer) belongs to whichever button was pressed last. The web gets this from the browser, whose pointerup fires only once every button is up.

onscroll fires once per container that moved, whichever axis moved it, and its ScrollEvent payload carries both offsets — so a horizontal-only scroller reports its position rather than an unchanging scroll_top (issue #177). ScrollEvent is #[non_exhaustive]: read its fields by name, and construct one (in a test, say) with ScrollEvent::new(top, left) rather than a struct literal.

#![allow(unused)]
fn main() {
div {
    style: "overflow: auto; width: 200px; height: 100px",
    onscroll: move |ev: ScrollEvent| {
        column.set((ev.scroll_left / char_width) as usize);
    },
    // …wide content…
}
}

On desktop a scroll offset is kept on the device pixel grid (issue #1543), so scrolled text moves by whole device pixels and does not re-space as it scrolls: at a display scale of 125% the offsets are multiples of 0.8px. The ScrollEvent offsets and scroll_top() report that snapped value, so set_scroll_top(10.33) at 125% reads back 9.6. Do not compare an offset you wrote with one you read back for equality.

oninput and onchange follow HTML semantics and are not aliases (they were before issue #226): oninput fires on every keystroke with the live value, while onchange fires once when the typed gesture ends — focus leaves the control after a modification, Enter commits explicitly, or a <select> commits a pick — and only if the value actually changed since the control was focused. Use oninput for live previews and controlled inputs, onchange for validate-on-commit, autosave-on-leave, and undo bracketing. On Enter, onchange fires before onsubmit, and the eventual blur does not re-fire an already-committed value. Enter commits single-line inputs only — in a <textarea> (as in HTML) the gesture runs until blur, where Enter inserts a line break instead (see Enter in a <textarea>). Like the browser’s change, the event bubbles: data-onchange on an ancestor of the control receives the commit too.

Mouse and click handlers read per-event data from get_click_context(): mouse_x/mouse_y, element bounds (relative_x(), percent_x(), …), button (MouseButton::{Left, Middle, Right}), and modifiers (shift/ctrl/alt/meta). These behave identically on the desktop and web (WASM) backends.

The element bounds are the box the element is painted in, which is what getBoundingClientRect() reports on the web — so a CSS transform on the element or any ancestor moves and resizes them, and a position: fixed element reports its viewport box rather than one displaced by its ancestors (#203). That is what makes Drag::percent() and percent_x() read correctly inside the left: 50%; top: 50%; transform: translate(-50%, -50%) centring idiom, and inside a transform: scale() zoom container. mouse_x/mouse_y are unchanged — still plain viewport coordinates, which is what popup placement in DropdownMenu, Select and ContextMenu reads them as. For a rotated element the bounds are the axis-aligned bounding box, the same approximation the browser makes.

Keyboard activation

Enter and Space on a keyboard-focused element run its onclick — the same handler as a pointer press, on both backends. What Tab can reach differs by backend: on web the browser makes <button>, <a href> and the like Tab stops on its own; on desktop only an element with tabindex (or a text input) is a Tab stop today, so a bare <button> needs tabindex="0" there (issue #252). The handler receives a ClickContext whose cursor sits at the element’s centre (mouse_x/mouse_y = the middle of element_x/element_y

• size), with button: Left and no text hit, so placement logic that reads get_click_context() (a Select flipping to fit the viewport, say) keeps working for a keyboard user. Those bounds are the painted box, the same one a pointer press reports, so a transformed element activates to the same numbers either way in. Ctrl/Meta chords are left alone; Shift and Alt ride along in modifiers.

On desktop, activation latches once per physical press (a held key does not repeat). On web, two routes cover the two kinds of element:

• Natively activatable elements — <button> and <summary> on Enter or Space, <a href> on Enter, checkbox/radio inputs on Space — use the browser’s own activation: the click the browser synthesises is what dispatches the handler. The browser’s semantics apply, so <a href> also navigates on Enter (exactly as a mouse click on it already does), a checkbox still toggles, and a held Enter repeats at the browser’s key-repeat rate. Where the browser has no activation for a key — Space on a link — rinch dispatches it from keydown instead (the handler runs, the page does not scroll, and nothing navigates), matching desktop.
• tabindex elements (a <div tabindex="0"> such as a Tree node) get no browser click, so rinch dispatches from keydown: once per press, and the key is consumed for the whole press — including its auto-repeats — so a held Space neither re-activates nor scrolls the page. Elements the browser focuses on its own without tabindex (a keyboard-focusable scroll container, <video controls>) keep their keys: Space there scrolls or plays, it does not activate the clickable around them.

Neither route double-fires with the mouse: a pointer press dispatches from pointerdown, and the trailing click of that same gesture — including the extra click a <label> fires at its control — is suppressed, even if a key was pressed while the button was held. A press that dispatched nothing has nothing to duplicate, so its clicks are not suppressed: a <label for="x"> outside every handler, whose <input id="x"> sits inside a clickable wrapper, activates that wrapper once by mouse as it does by keyboard (issue #272, web only — the desktop backend does not follow for, so there the press does nothing). The same rule lets a click through when something else swallowed the press: a third-party widget (a map, a chart) inside a clickable card that stops its own pointerdown from propagating now activates the card on release, as a browser’s own click would — stop click too if the widget must not. Clicks with no pointer gesture behind them — assistive technology (whose clicks are trusted, with no pointer or key event of their own on Firefox/WebKit), element.click() — are honoured once, and a click a handler raises itself (hidden_input.click()) does not re-enter that handler. Enter inside an <input>/<textarea>, an editable region or the rich-text editor is never an activation of a surrounding clickable; it is the onsubmit gesture described above (or, in a <textarea> with no onsubmit, a line break). An element with no live handler in its ancestry is a quiet no-op — the key falls through to the browser, so Tab and scrolling keep their usual meaning.

A mouse press focuses the nearest focusable ancestor of what it hits, like a browser — so a clicked tabindex element owns Enter/Space straight away, without having to be reached by Tab first. A component that wants the keys for itself (a code editor, a keyboard-driven grid) registers for them; see Keyboard Focus.

Enter in a <textarea>

Enter has two meanings in a multi-line field, and which one it takes is the author’s declaration:

So a notes field takes line breaks with no ceremony, a chat composer sends on Enter and takes a break on Shift+Enter, and a single-line <input> is unchanged — a line break is not representable in its value.

onsubmit is read the way onchange is: from the control, then up its ancestors, so an onsubmit on the wrapper around a field submits that field. One backend difference to know about: on web, Shift+Enter in an <input> does nothing (the browser’s own Enter path is what desktop’s commit stands in for), while on desktop it commits like a plain Enter.

The break is an ordinary edit: it moves the caret, fires oninput with the new value (\n included) and is one Backspace away from gone. On Android the soft keyboard is told per focused field which kind it is serving, so a <textarea> gets a keyboard whose Enter types a newline instead of an action key that ends the input session.

Moving between lines

ArrowUp and ArrowDown move the caret one visual line in a <textarea> — a line the text soft-wrapped onto counts, as in a browser — aiming at the column the first of a run of vertical moves started from, so a short line in between does not pull the caret left for good. On desktop this reads the same text layout a click is hit-tested against, so the caret lands where a click at that height would put it (except at a soft-wrap point, below). ArrowUp on the first line goes to the start of the text and ArrowDown on the last line to its end; in a single-line <input> that is all they do (Chrome’s behaviour on Linux and Windows). Shift extends the selection. Without Shift a selection collapses, moving from its start (up) or its end (down). An <input type="number"> is not moved: a browser steps its value there, which desktop does not do.

Where a soft-wrapped line is shorter than the column aimed at, desktop stops one character before the wrap point, since a caret at the wrap point itself would be drawn at the start of the next line. A browser keeps a caret affinity for that and places it after the last character instead. Where the wrap is at a space the space hangs and nothing looks different; in text with no spaces (CJK) the caret is visibly one column short.

Home and End in a <textarea> go to the start and end of the caret’s visual line, soft-wrapped lines included; Ctrl+Home and Ctrl+End (Cmd on macOS) go to the start and end of the whole text. Shift extends the selection. Without Shift a selection collapses and moves from its head — the end the caret is at — rather than from its start or end as ArrowUp and ArrowDown do, which is what Chrome does. In a single-line <input> Home and End go to the ends of the value. A Home or End moves the caret off the column a run of vertical moves was aiming at, so the next ArrowUp or ArrowDown aims from where the caret now is; one that leaves the caret where it was keeps that column, as in Chrome.

End on a soft-wrapped line follows the rule above: desktop stops one character before the wrap point, a browser at the wrap point with the caret drawn at the end of the line. When the wrap is at a space, the caret sits before that space, so a character typed there goes before it — abcd abcdX abcd where Chrome types abcd abcd Xabcd.

Sizing a <textarea>

A <textarea> holds its value in its value attribute, and has no content to size against. Text written as its child — textarea { "hi" }, or a parsed <textarea>hi</textarea> — is its default value, as in HTML: the field shows and edits it, and follows it when it changes (a reactive textarea { {|| draft.get()} }) — until the user edits the field or something sets its value. That is HTML’s dirty value flag, which focusing and blurring do not set (#1186); from then on a child change updates only the default value (defaultValue on the web), and the field keeps what the user typed. The rule is the same on the desktop and on rinch-web, value writes included (#1222): a write equal to the shown text sets the flag too, as a script .value write does in Chrome, and removing the value attribute is a write of "" — the field empties and stays dirty, since no script write clears the flag again. (A browser’s form reset does; the desktop has no form reset.) A child change while the field is focused and unedited keeps the caret at its offset, clamped to the new text, as in Chrome.

A text child is not a controlled value. Until #1206, rinch-web wrote a textarea’s value from its children on every change (#100), so textarea { {|| draft.get()} } with draft.set(String::new()) after a submit cleared the field there even after the user had typed — and did not on the desktop. It no longer does on either backend. For a field the app keeps in step with a signal, bind the value itself — a value_fn on the Textarea component, or a reactive value: on the raw element — which reaches the field whether or not the user has typed:

#![allow(unused)]
fn main() {
let draft = Signal::new(String::new());
rsx! {
    div {
        Textarea {
            value_fn: move || draft.get(),
            oninput: move |v: String| draft.set(v),
        }
        // or, on the raw element:
        // textarea { value: {|| draft.get()}, oninput: move |v: String| draft.set(v) }
        button { onclick: move || { send(draft.get()); draft.set(String::new()); }, "Send" }
    }
}
}

It sizes the field no more than a value does. An <input>’s children are not shown at all, and neither is an element child of a <textarea> — a div built into one through rsx or append_child has no box, draws nothing and does not size the field (#1178), as in a browser. A control with no width is as wide as its cols (a textarea, default 20) or size (a text <input>, default 20) average characters of its font, as in a browser, and a textarea reserves a scrollbar’s width beside them (#1177). A textarea’s height comes from rows, which reserves that many lines plus padding and border — 2 rows when unset, matching HTML. rows is read as HTML reads it: the leading digits ("3abc" is 3, "2.5" is 2), and 2 when there are none or they come to zero:

#![allow(unused)]
fn main() {
rsx! {
    textarea { rows: "6" }                        // six lines tall
    textarea { style: "min-height: 200px;" }      // or size it with CSS
}
}

min-height, max-height and an explicit height all work as usual: height overrides the rows height outright, min-height acts as a floor so the taller of the two wins, and max-height caps it. The rows height is the textarea’s content height, as in a browser, so a min-height: 0 textarea in a flex column can shrink below it. An <input> is sized the same way from one line. The Textarea component exposes the same thing as min_rows.

Components

Components are custom UI elements written in PascalCase. They implement the Component trait and render directly to DOM nodes:

#![allow(unused)]
fn main() {
rsx! {
    Button { variant: "filled", color: "blue", onclick: || println!("clicked"),
        "Click me"
    }

    Alert { icon: TablerIcon::InfoCircle, color: "blue", title: "Info",
        "This is an informational message."
    }
}
}

Note: Shell-level constructs like windows, menus, and themes are configured at the runtime level via props, not in RSX.

Attributes on a component

A component’s props are the fields of its struct, so Group { gap: "xs" } sets a field. A hyphenated name can never be a Rust field, so rsx! treats one written on a component as an attribute for the component’s root DOM element, applied after Component::render — the same route the universal style: and class: props take:

#![allow(unused)]
fn main() {
rsx! {
    // The whole toolbar takes clicks without taking the keyboard; no wrapper div.
    Group { gap: "xs", data-nofocus: "", aria-label: "Formatting",
        Button { onclick: move || ed.command("toggleBold"), "B" }
    }
}
}

That covers data-*, aria-* and any other hyphenated name (issue #433). The rules are the HTML element’s rules:

• A boolean attribute — the HTML set and rinch’s own data-disabled, data-nofocus, data-trap-focus, data-backdrop and data-scroll-lock-exempt — is written as a presence for a truthy value and removed for a falsey one (Boolean attributes). Any other attribute is written as the string.
• A reactive value, data-state: {|| state.get()}, is an effect on the root that rewrites the attribute when its signals change, and re-renders nothing — on a component that re-renders for a reactive struct prop too (issue #1190): the effect belongs to the current render, so a change to the attribute’s signals updates the root in place and the component keeps its local state. When the component re-renders for its struct prop, every attribute is written again on the new root, and a reactive one gets a fresh effect there. The same holds for style:, class: and the style shorthands.
• The caller writes last. An attribute the component also writes on its own root takes the caller’s value at mount, and a falsey boolean removes the component’s. After that the last write wins: a component effect that later writes the same attribute overwrites the caller’s value, and a reactive attribute overwrites it back only when its own signals change. That includes rinch’s own wiring attributes: a caller’s data-rid on a component replaces the id of the component’s own click handler, so it stops firing. Don’t.

Unhyphenated attribute names — id, tabindex, role — are not routed: on a component they are still struct fields, and a component that does not declare one does not compile.

Fragments

Use empty braces to group multiple elements without a wrapper:

#![allow(unused)]
fn main() {
rsx! {
    div {
        // Multiple children without extra wrapper
        span { "First" }
        span { "Second" }
    }
}
}

Text Content

Text can be included directly in elements:

#![allow(unused)]
fn main() {
rsx! {
    p { "This is text content" }
    span { "Multiple " "strings " "concatenated" }
}
}

Expressions

Rust expressions can be embedded in curly braces:

#![allow(unused)]
fn main() {
let name = "World";
let count = 42;

rsx! {
    p { "Hello, " {name} "!" }
    p { "Count: " {count} }
}
}

Reactive Expressions

For fine-grained reactivity, use closure syntax {|| expr} to create expressions that automatically update when signals change. Without the closure, values are captured once at initial render and never update.

Static vs Reactive

#![allow(unused)]
fn main() {
let count = Signal::new(0);

rsx! {
    // ❌ STATIC: Captured once, never updates
    p { "Count: " {count.get()} }

    // ✅ REACTIVE: Creates an effect, updates when count changes
    p { "Count: " {|| count.get().to_string()} }
}
}

Reactive Text

Wrap dynamic text in a closure to make it reactive:

#![allow(unused)]
fn main() {
let name = Signal::new("World".to_string());
let count = Signal::new(0);

rsx! {
    // Simple reactive text
    h1 { "Hello, " {|| name.get()} "!" }

    // Reactive with formatting
    p { {|| format!("You clicked {} times", count.get())} }

    // Conditional text
    p { {|| if count.get() > 10 { "Many clicks!" } else { "Keep clicking" }} }
}
}

Reactive Styles

Style attributes can also be reactive:

#![allow(unused)]
fn main() {
let progress = Signal::new(50);
let is_active = Signal::new(false);

rsx! {
    // Reactive width
    div {
        class: "progress-bar",
        style: {|| format!("width: {}%", progress.get())}
    }

    // Multiple reactive style properties
    div {
        style: {|| format!(
            "background: {}; opacity: {}",
            if is_active.get() { "blue" } else { "gray" },
            if is_active.get() { "1" } else { "0.5" }
        )}
    }
}
}

Reactive Classes

Dynamically change CSS classes based on state:

#![allow(unused)]
fn main() {
let is_selected = Signal::new(false);
let variant = Signal::new("primary");

rsx! {
    // Conditional class
    div {
        class: {|| if is_selected.get() { "item selected" } else { "item" }}
    }

    // Dynamic class from state
    button {
        class: {|| format!("btn btn-{}", variant.get())}
    }
}
}

Important: Closure Must Be the Direct Expression

The {|| ...} pattern requires the closure to be the direct expression inside the braces. Block expressions with setup code now work:

#![allow(unused)]
fn main() {
let count = Signal::new(0);

rsx! {
    // ✅ CORRECT: Closure is the direct expression
    div { style: {|| format!("width: {}px", count.get() * 10)} }

    // ✅ CORRECT: Block with setup + final closure — works!
    div { style: {
        let multiplier = 10;
        move || format!("width: {}px", count.get() * multiplier)
    }}

    // ✅ CORRECT: Compute inside the closure
    div { style: {move || {
        let multiplier = 10;
        format!("width: {}px", count.get() * multiplier)
    }}}
}
}

You can compute intermediate values outside the RSX, inside the closure body, or in a setup block before the closure.

Why Closures?

Rust macros operate on syntax, not types. The macro cannot distinguish between:

• signal.get() - reading reactive state
• hashmap.get("key") - reading a regular value

The closure {|| ...} explicitly marks the expression as reactive, telling Rinch to:

1. Create an Effect that wraps this expression
2. Track which signals are read inside the closure
3. Re-run and update the DOM when those signals change

This approach has benefits:

• Zero runtime overhead for static content
• Clear intent - you know exactly what’s reactive
• Works with Rust’s ownership - closures capture values correctly

What Supports Reactive Expressions?

Control Flow

Rinch supports native Rust control flow directly in RSX. All control flow is always reactive — the conditions, iterators, and scrutinees are automatically wrapped in closures and tracked by Effects. When the underlying signals change, only the affected branches are updated.

if / else

Write standard Rust if/else directly in RSX:

#![allow(unused)]
fn main() {
let visible = Signal::new(true);
let count = Signal::new(5);

rsx! {
    div {
        // Simple if
        if visible.get() {
            p { "I'm visible!" }
        }

        // if/else
        if count.get() > 10 {
            p { "Big number!" }
        } else {
            p { "Small number" }
        }

        // if/else if/else
        if count.get() > 100 {
            p { "Huge" }
        } else if count.get() > 10 {
            p { "Big" }
        } else {
            p { "Small" }
        }
    }
}
}

Showing a subtree you built earlier

A branch body does not have to build fresh markup. It may yield a NodeHandle you built once outside the if, and toggling the condition then moves that same subtree in and out of the page rather than rebuilding it:

#![allow(unused)]
fn main() {
let panel = heavy_panel(__scope);   // built once
let open = Signal::new(false);

rsx! {
    div {
        if open.get() {
            {panel.clone()}
        }
    }
}
}

The subtree keeps its identity across every toggle: its DOM nodes, any state inside them, and anything else holding a handle into it all survive being hidden. That is guaranteed on both backends — issue #719 was a period during which rinch-web lost the subtree on the first hide, silently, while desktop kept it.

The subtree is kept wherever it sits in the branch’s markup, including nested inside something the branch builds itself — if open.get() { div { {panel.clone()} } } — which used to throw it away with the wrapper (issue #732). The wrapper div is the branch’s own and is rebuilt on every show and discarded on every hide as usual; panel is detached rather than discarded along with it, and the next show puts the same panel back inside a fresh wrapper.

What counts as “built by the branch” is anything minted through the branch’s RenderScope or through a scope created on its behalf — a for’s rows, a nested if, a component, a List patching a late row — and anything minted by raw document access under such a node (an Editor’s blocks, raw HTML). If your own code builds nodes through a separate RenderScope that belong to the branch and go with it (an observer patching rows, a timer adding to the branch’s markup), create it with RenderScope::with_parent(doc, node, Some(scope.id())), naming the branch’s scope. Content that must outlive the branch — a cache you show again later — must not name it: build it with RenderScope::new, or outside the branch, and it is only ever detached. A RenderScope::new placed inside a branch’s markup belongs to no branch, so a hide only detaches its nodes; if nothing shows them again they are never reclaimed.

A cache filled from inside a for

An if can be handed a panel that was built before it. A for row usually cannot: the row’s subtree depends on the item, so a cache of rows is filled inside the row’s body, the first time each key is seen. Everything built through the scope the body is given belongs to the row — its nodes are discarded when the key leaves the list, and its effects, signals and event handlers are disposed — so a row cached that way is gone the next time its key appears (issue #733). On rinch-web nothing is shown for it; on desktop the nodes come back and their reactive bindings do not.

Build a cached row through a cache scope instead, and keep the scope with the row:

#![allow(unused)]
fn main() {
type TabCache = Rc<RefCell<HashMap<u32, (NodeHandle, RenderScope)>>>;

/// Hand back the cached tab, or build it once and keep its scope with it.
fn cached_tab(scope: &mut RenderScope, cache: &TabCache, id: u32) -> NodeHandle {
    if let Some((tab, _keep)) = cache.borrow().get(&id) {
        return tab.clone();
    }
    let mut keep = scope.cache_scope();
    let tab = keep.build(|__scope| rsx! {
        article { {expensive_tab(__scope, id)} }
    });
    cache.borrow_mut().insert(id, (tab.clone(), keep));
    tab
}

#[component]
fn tab_strip(open_tabs: Signal<Vec<u32>>) -> NodeHandle {
    let cache = TabCache::default();
    // Let go of every cached tab when the strip unmounts.
    let evict = cache.clone();
    __scope.on_cleanup(move || {
        for (_, (tab, keep)) in evict.borrow_mut().drain() {
            keep.dispose();
            tab.discard();
        }
    });
    rsx! {
        div {
            for id in open_tabs.get() {
                {cached_tab(__scope, &cache, id)}
            }
        }
    }
}
}

(This block is compiled and run as crates/rinch-macros/tests/rsx_for_cache_scope_733.rs.)

• scope.cache_scope() returns a new RenderScope on the same document that belongs to no row and no branch. Nothing the list does discards what it builds.

• keep.build(|__scope| …) builds through it and makes it the owner of every Signal::new, Memo::new, store and event handler created inside. Do not skip build and use the cache scope’s &mut directly: the row then comes back with its nodes, but a Signal::new, a memo or an onclick made while building belonged to the row that happened to be rendering and was freed with it. A write to that signal is then a no-op, the bindings that read it never update, and nothing panics or warns.

• The scope and the node are released together, by you. They are two values, and nothing ties them:

  • drop the scope and keep the node, and the node comes back inert — its effects, signals and handlers were disposed;
  • discard the node and keep the scope, and its effects go on running against a node that no longer exists, for as long as the scope lives;
  • drop both without discarding the node — which is what happens when the cache itself is dropped, because the component that owns it unmounted — and the effects stop but every cached node stays in the backend for the life of the page. Measured on the mock and in Chrome 153: 50 mounts of a list of two cached rows leave 200 nodes behind without the on_cleanup above, and none with it.

  So evicting one entry is scope.dispose() and then node.discard(), and a cache owned by anything that can unmount drains itself in on_cleanup, as tab_strip does. A key that never comes back holds its row until then. (One value that owns both and releases them in step is issue #1454.)

• A cached row is not rebuilt when its item changes. The body is called again for a changed item under the same key and hands the same node back, so anything in it that should follow the item has to be reactive.

The same works in an if or match body whose cache is filled lazily.

What tells you when a cached row was built the wrong way. If a body’s root node — the node the body itself evaluates to — was already discarded, rinch counts it and emits a tracing warning that names cache_scope, once per node and for at most 32 nodes per thread. That is narrower than it sounds:

• It is a tracing event, and nothing shows it unless a subscriber is installed. The desktop shell installs one; rinch-web installs none (issue #1455), so a browser app sees it only with a console subscriber of its own (the tracing-wasm crate is one), and cargo test prints it only if the test installs one (tracing_subscriber::fmt().with_test_writer()). What a test can assert on without one is the counter, rinch_core::dom::__retired_view_returns() — (returns seen, nodes warned about) on the current thread.
• Only a backend that reclaims discarded nodes can notice: rinch-web, and the MockDomDocument your component tests run on. Desktop reclaims nothing yet, so it shows the row and reports nothing.
• A discarded node nested in fresh markup is not noticed. for t in tabs.get() { div { class: "tab", {cached} } } with cached built through the row’s scope loses the row in the same way — the div comes back empty — and nothing is counted or logged, because the body’s root is the fresh div (issue #1456).

So the absence of a warning proves nothing: test a cached list on the mock or in a browser, not only on desktop, and assert that the row is there.

Two more things to know. The branch’s RenderScope is disposed on every hide, so effects created inside the branch closure stop; put the reactive wiring in the same scope as the panel binding, not in the closure. And a subtree that is out of the page is not laid out, so a measurement taken while it is hidden is stale.

Plain markup in a branch — if open.get() { p { "hi" } } — is rebuilt on every show and thrown away on every hide, which is what you want for anything cheap.

if let

Pattern matching with if let is also supported:

#![allow(unused)]
fn main() {
let current_user = Signal::new(Some("Alice".to_string()));

rsx! {
    div {
        if let Some(name) = current_user.get() {
            p { "Welcome, " {name} "!" }
        } else {
            p { "Please log in" }
        }
    }
}
}

How if works internally

The if block desugars to show_dom() — the same runtime function used by the Show component. The condition is auto-wrapped in a move || { ... } closure, creating an Effect that watches the signals read inside it. When the condition changes:

1. The old branch’s scope is disposed (cleaning up nested effects)
2. Old DOM nodes are removed
3. New branch content is rendered with a fresh scope

Braces around control flow

A brace in child position is transparent to control flow: { match x { … } } renders the same reactive match_dom as match x { … }, and the same goes for if and for, at any depth — including a braced match arm body, _ => { if … }.

That is worth stating because the two used to differ, silently. A braced construct was parsed as a plain Rust expression and evaluated once, so it kept whichever branch was true when it mounted and never changed again — one brace apart from a fully reactive twin, with no diagnostic (issue #221).

Braced control flow whose bodies are not rsx cannot be made reactive — there is no markup for the runtime to swap — so it is a compile error now instead of a silent freeze:

#![allow(unused)]
fn main() {
// error: `match` wrapped in braces renders once and never updates
{ match selected.get() {
    Some(p) => rsx! { div { {p.name.clone()} } },
    None => rsx! { div { "—" } },
} }
}

The message names both ways out, because which one is right depends on what you meant. For reactive markup, drop the braces and write each arm as rsx rather than as a nested rsx! invocation:

#![allow(unused)]
fn main() {
match selected.get() {
    Some(p) => div { {p.name.clone()} },
    None => div { "—" },
}
}

For a reactive value, wrap the whole thing in a closure — the reactive expression form from earlier in this guide:

#![allow(unused)]
fn main() {
{|| match selected.get() {
    Some(p) => p.name.clone(),
    None => "—".to_string(),
}}
}

Everything else in braces is untouched: an expression ({ count.to_string() }), a reactive closure ({|| count.get()}) and a call ({ section(__scope) }) never begin with a control-flow keyword, so they are the expressions they always were.

Capturing the same value in more than one branch

Every closure RSX builds is a move closure — a branch, a match arm, a per-item view, a reactive binding’s effect, an event handler — and show_dom takes the then branch and the else branch, so both are constructed whichever way the condition comes out. A non-Copy value named by two of them would be moved twice.

The macro handles that for you. At each construction site it emits a shadow clone of what that site shares with a sibling site, or reaches for from outside a body that re-runs. So this compiles, and label is still yours afterwards:

#![allow(unused)]
fn main() {
let label = String::from("hello");

rsx! {
    div {
        if label.is_empty() {
            p { "empty" }
        } else {
            p { {label.clone()} }
        }
        Text { {label.clone()} }
    }
}
}

What is not cloned. A value only one site names is moved, exactly as before, so a type that isn’t Clone keeps working where it always did. A value bound inside a repeating body — a let at the top of a branch, the for item itself — is a fresh local on every run and is never cloned. Signal and Memo are Copy, so where a shadow does fall on one it is a copy, not an allocation.

What still needs a manual .clone(). The analysis is lexical: it cannot see a value hidden inside a macro (format!("{}", label) hides label from it), and it compares sites within one construct — two separate if blocks that both name one String still need one of them to clone. When rustc does report an E0382 or E0507 from inside rsx!, the fix is the ordinary one: give the site that complains its own clone.

for loops

Write standard for..in loops directly in RSX:

#![allow(unused)]
fn main() {
let todos = Signal::new(vec![
    Todo { id: 1, name: "Buy groceries".into() },
    Todo { id: 2, name: "Write code".into() },
    Todo { id: 3, name: "Take a walk".into() },
]);

rsx! {
    div {
        for todo in todos.get() {
            div { key: todo.id, {todo.name.clone()} }
        }
    }
}
}

Keys

Use key: on the first child element or component to enable efficient keyed reconciliation. When the list changes, items with the same key are preserved (not re-rendered), and only new/removed items trigger DOM operations:

#![allow(unused)]
fn main() {
for item in items.get() {
    div { key: item.id,
        span { {item.name.clone()} }
    }
}
}

key: also works on components — place it on the component tag directly:

#![allow(unused)]
fn main() {
for item in items.get() {
    TodoRow { key: item.id, label: item.name.clone() }
}
}

If no key: prop is provided, items are keyed by their Debug representation (fallback).

Keys must be unique within one list. The whole reconcile rests on one key naming one item and one DOM node, so a repeat used to leave a row that rendered, swallowed clicks and never updated again (issue #185). What a repeat means depends on who chose the key:

So for tag in ["rust", "rust", "gui"] renders three rows, and for n in vec![1, 1, 2] renders three rows. Reordering such a list still moves rows rather than rebuilding them, because the ordinal follows the value, not the position.

The one thing the fallback cannot give you is stable identity across an edit: if the first "rust" is deleted, the second one inherits its key and its DOM node. Where rows carry per-row state, give them a real key::

#![allow(unused)]
fn main() {
for (i, n) in numbers.get().into_iter().enumerate() {
    div { key: i, {n.to_string()} }
}
}

Prefer a stable per-row id where the data has one. An index key makes identity follow position, so inserting or removing anywhere but the end re-renders every row after the change — correct, but it gives up the reconciliation the keys are there for. Reach for the index only when the rows genuinely have nothing else to distinguish them.

How for works internally

The for loop desugars to for_each_dom_typed(), which:

1. Wraps the iterator in a move || { ... } closure (making it reactive)
2. Creates a <!-- for --> comment marker in the DOM
3. Evaluates the collection and renders initial items
4. Creates an Effect that watches the collection
5. When the collection changes, uses LIS-based keyed reconciliation (diff_keyed()) to compute minimal DOM operations: insert new items, remove deleted items, and reposition moved items
6. For surviving items (same key), compares data via PartialEq — only re-renders items whose data actually changed

The loop variable is owned (T, not &T), so you can capture it directly in move closures. let bindings before the element are available in the key: expression too:

#![allow(unused)]
fn main() {
for todo in todos.get() {
    let id = todo.id;
    div { key: id,
        {todo.name.clone()}
        button {
            onclick: move || todos.update(|t| t.retain(|t| t.id != id)),
            "Delete"
        }
    }
}
}

A binding counts as used if either the key: expression or the body reads it, so an item used only as a key (for id in ids { span { key: id, "row" } }) does not warn unused variable, and neither does an if let or match binding its branch reads. A binding nothing reads still warns, at your pattern. (For a for loop the check is by name, so a binding that both the key and the body merely spell — as a path segment or a struct-literal field name, say — can go unreported.)

Note: The item type must implement Clone + PartialEq + 'static for for loops to work. This enables efficient data comparison for selective re-rendering.

Reactivity in for Loops

The for loop expression itself is reactive — it reads a Signal, which creates an Effect. When that Signal changes, the loop re-evaluates and reconciles the list. Items whose data changed (per PartialEq) get their component re-created with fresh props. This means the component function runs again with the new values.

Because of this, closures on plain props inside for-loop components are unnecessary — the whole function runs again with new values when the item changes. Closures are needed for per-item Signals created with Signal::new() inside the loop body, since those change independently of the list data.

#![allow(unused)]
fn main() {
// Props are plain values from the for loop — no closure needed
#[component]
pub fn TodoItem(label: String, completed: bool) -> NodeHandle {
    // ❌ Unnecessary: `completed` is a plain bool, not a Signal.
    // The closure captures it once, but the component is re-created
    // with a fresh `completed` value when the item data changes anyway.
    rsx! { Text { style: {|| if completed { "text-decoration: line-through" } else { "" }} } }

    // ✅ Simpler: just use the value directly
    rsx! { Text { style: if completed { "text-decoration: line-through" } else { "" } } }
}

// Per-item Signal — closure IS needed
for todo in todos.get() {
    let editing = Signal::new(false);  // Per-item state
    div { key: todo.id,
        // ✅ Closure needed: `editing` is a Signal that changes independently
        span { style: {|| if editing.get() { "outline: 1px solid blue" } else { "" }} }
    }
}
}

Rule of thumb: If the value comes from a Signal (.get()), use a closure. If it comes from the for loop variable (a plain value), just use it directly.

Filtering and Transforming Collections

You can filter, map, and transform the collection inline in the for expression. The entire expression is wrapped in a reactive closure by the macro, so all Signals read inside it are tracked:

#![allow(unused)]
fn main() {
let todos = Signal::new(vec![/* ... */]);
let filter = Signal::new(Filter::All);

rsx! {
    div {
        // Filter the collection inline — .filter(), .map(), .collect() all work
        for todo in todos.get().into_iter().filter(|t| {
            match filter.get() {
                Filter::All => true,
                Filter::Active => !t.completed,
                Filter::Completed => t.completed,
            }
        }).collect::<Vec<_>>() {
            TodoItem { key: todo.id, label: todo.text.clone() }
        }
    }
}
}

Both todos and filter are tracked — the loop re-evaluates when either Signal changes. Any iterator chain that produces a Vec<T> (where T: Clone + PartialEq + 'static) works.

match

Write standard Rust match directly in RSX:

#![allow(unused)]
fn main() {
let tab = Signal::new(0);

rsx! {
    div {
        match tab.get() {
            0 => div { "Home page" },
            1 => div { "About page" },
            2 => div { "Settings page" },
            _ => div { "Page not found" },
        }
    }
}
}

Match with pattern bindings

Patterns that bind variables work — each arm re-evaluates the scrutinee to extract the bound values:

#![allow(unused)]
fn main() {
let result = Signal::new(Ok::<String, String>("Hello".into()));

rsx! {
    div {
        match result.get() {
            Ok(value) => p { "Success: " {value} },
            Err(msg) => p { class: "error", "Error: " {msg} },
        }
    }
}
}

Match with guards

Guard expressions are supported:

#![allow(unused)]
fn main() {
match score.get() {
    n if n >= 90 => div { "A" },
    n if n >= 80 => div { "B" },
    n if n >= 70 => div { "C" },
    _ => div { "F" },
}
}

Several nodes in one arm

An arm body in braces can hold several nodes, as an if or for body can — they are rendered together as the arm:

#![allow(unused)]
fn main() {
match tab.get() {
    0 => { h2 { "Home" } p { "Welcome back." } },
    1 => { let n = count.get(); b { {n.to_string()} } " items" },
    2 => { Badge { "new" } Badge { "beta" } },
    _ => { overview_section(__scope) },   // one expression, as always
}
}

What the braces hold is decided by how they start:

• let always starts rsx nodes.
• An element or component (div {, Card {), a string literal, if/for/ match, or an interpolation { … } starts rsx nodes when more nodes follow it: { {label} span { "!" } }, { if open.get() { "▾" } span { "Menu" } }.
• An element, component or string literal on its own is that one node.
• Anything else is a single Rust expression, as it always was: a call, a variable, a closure, and a method called on a literal or on a struct ({ "a".to_string() }, { if a { "x" } else { "y" } .len() }). So { overview_section(__scope) }, { panel.clone() } and {|| count.get().to_string()} are unchanged. Lone control flow in braces is the transparent brace described under Braces around control flow.

(Until issue #395 only a body starting with let could hold more than one node.) A mistake inside a multi-node arm is reported by the rsx parser, at the mistake, like one in any other rsx body — including one inside a leading if/for/match when another node follows it. (Finding that following node after a head that failed to parse is a token-level heuristic: a condition that itself holds braces, such as if let Foo { a } = x, can defeat it and leave you with the single-node error instead.) A lone braced if/for/match whose bodies are not rsx still gets the “renders once” error described under Braces around control flow.

One consequence: { Point { x: 1 } } in an arm is a component named Point, exactly as Point { x: 1 } unbraced is, not a Rust struct literal. A struct literal that cannot be an element — shorthand fields ({ Foo { a } }), a .. base ({ Foo { ..Default::default() } }), or one with a method called on it ({ Point { x: 1 }.into_node(__scope) }) — stays an expression, and so does a path such as geom::Point { x: 1 }, which is not an element name.

How match works internally

The match block desugars to match_dom(), which generalizes show_dom() to N branches. A discriminant closure returns the index of the active branch (0, 1, 2, …). When the discriminant changes, the old branch is disposed and the new branch is rendered.

Programmatic Conditional Rendering (show_dom)

For cases requiring explicit control (e.g., lazy evaluation of children that contain hooks), use show_dom() directly:

#![allow(unused)]
fn main() {
show_dom(
    __scope,
    &parent,
    move || visible.get(),           // Condition closure
    |scope| {                        // Then branch
        let div = scope.create_element("div");
        div.set_text("Visible!");
        div
    },
    Some(|scope| {                   // Else branch (optional)
        let div = scope.create_element("div");
        div.set_text("Hidden");
        div
    }),
)
}

Programmatic List Rendering (for_each_dom_typed)

For cases requiring the raw list API, use for_each_dom_typed() directly:

#![allow(unused)]
fn main() {
for_each_dom_typed(
    __scope,
    &parent,
    move || todos.get().into_iter().collect::<Vec<_>>(),
    |todo| todo.id.to_string(),
    |todo, __child_scope| {
        let __scope = __child_scope;
        rsx! { div { {todo.name.clone()} } }
    },
)
}

How Keyed Reconciliation Works

When the list changes, for uses the LIS (Longest Increasing Subsequence) algorithm to find the minimum DOM operations:

#![allow(unused)]
fn main() {
// Before: ["a", "b", "c", "d"]
// After:  ["b", "e", "c", "a"]

// Operations:
// - Remove "d"
// - Insert "e" at index 1
// - Move "a" to index 3
// - Items "b" and "c" stay in place (part of LIS)
}

This means:

• Unchanged items keep their DOM nodes (no re-render)
• Moved items are repositioned in DOM (no re-create)
• Changed items are re-rendered if their data differs (via PartialEq)
• Internal state (signals, effects) is preserved for unchanged items
• Only new items trigger component initialization

Note: The loop variable is owned (T, not &T), so you can capture it directly in move closures without manual field extraction.

Event Handlers

Events use the onevent: handler syntax:

#![allow(unused)]
fn main() {
// Inside a #[component] function:
let count = Signal::new(0);

rsx! {
    button {
        onclick: move || count.update(|n| *n += 1),
        "Increment"
    }
}
}

Sharing Event Handlers

You can extract event handlers into variables and reuse them across multiple elements. This is especially useful when a button and a text input should trigger the same action:

#![allow(unused)]
fn main() {
let input_text = Signal::new(String::new());
let todos = Signal::new(Vec::<String>::new());

// Extract shared logic into a closure
let add_todo = move || {
    let text = input_text.get();
    if !text.trim().is_empty() {
        todos.update(|t| t.push(text.trim().to_string()));
        input_text.set(String::new());
    }
};

rsx! {
    // Both TextInput (on Enter) and Button (on click) use the same handler
    TextInput {
        value_fn: move || input_text.get(),
        oninput: move |value: String| input_text.set(value),
        onsubmit: add_todo,
    }
    Button { onclick: add_todo, "Add" }
}
}

This works because Signal implements Copy, so closures capturing signals can be used in multiple places without .clone().

Style Shorthands

The rsx! macro supports CSS shorthand props on both HTML elements and components. Shorthands expand to set_style() calls that merge with existing styles.

Spacing scale values (xs, sm, md, lg, xl) auto-resolve to var(--rinch-spacing-{value}). On a positioned element the top/right/bottom/left shorthands accept any CSS length — px, %, em, var(), calc() — not just the spacing scale. A calc() mixing % with a length (calc(50% - 10px)) resolves correctly on desktop too (#278) — for insets, sizes, margins, padding, gaps, transforms and border radii alike. One named limitation: a non-affine calc() (a min()/max()/clamp() with a percentage inside) resolves as its large-container linearization on desktop rather than tracking the breakpoint.

Available Shorthands

Usage

#![allow(unused)]
fn main() {
// On HTML elements
div { p: "md", m: "lg", w: "200px", "Padded and margined" }

// On components
Stack { gap: "md", p: "xl", maw: "600px",
    Text { "Constrained content" }
}

// Reactive shorthands
let big = Signal::new(false);
div { p: {|| if big.get() { "xl" } else { "sm" }}, "Dynamic padding" }

// Spacing scale values auto-resolve
div { p: "md" }    // becomes: padding: var(--rinch-spacing-md)
div { p: "20px" }  // becomes: padding: 20px (passed through)
}

Application Order

style: is merged, not assigned (issue #647). Its declarations are laid over whatever is already on the element — a shorthand prop, something the runtime wrote through set_style(), and on a component every inline declaration the component’s own render wrote — last-wins per property:

#![allow(unused)]
fn main() {
// The component publishes `--rinch-modal-z-index: 517` on its root from
// `render`; the caller's `margin: 0` joins it rather than replacing it.
Modal { z_index: 517, style: "margin: 0" }

// `padding` survives the first signal change. It used to be erased, because
// the re-firing `style:` effect wrote the whole `style` attribute.
div { style: {|| format!("color: {}", tint.get())}, p: "md" }
}

Shorthands are applied through set_style() after component rendering and after the style: prop, so a shorthand wins a collision with style: at mount:

#![allow(unused)]
fn main() {
div { style: "padding: 0", p: "12px" }   // padding is 12px
}

A reactive style: takes that back on its first re-fire, and keeps it:

#![allow(unused)]
fn main() {
let css = Signal::new(String::from("padding: 0"));
div { style: {move || css.get()}, p: "12px" }
// padding is 12px at mount, and 0 from the first `css.set(...)` onward
}

The shorthand is applied once, at mount; nothing re-asserts it. Declaring the same property from both props on one element is the mistake — pick one. Everything else composes:

#![allow(unused)]
fn main() {
let css = Signal::new(String::from("margin: 0"));
div { style: {move || css.get()}, mt: "8px" }   // margin-top stays 8px, always
}

That second line is the shape the merge has to get right, and it is not a collision: margin-top beats margin only while it stays after it in the block, so a re-run must overwrite the closure’s margin where it stands rather than removing and re-appending it. A reactive style: also never accumulates — a property the closure has stopped naming is removed, or restored to the value it had been overriding — and it leaves alone any property whose current value somebody else has written since, rather than reverting a value it never saw.

An element with no second author on its style attribute keeps the author’s string verbatim, on every fire.

One parser, and what it does with an awkward value

Every author of an inline style — a style: prop, a style shorthand, a set_style() from a component or the runtime — splits and re-joins the attribute with the same parser (issue #670). Four things follow that you can rely on:

• A ; or : inside url(…), "…" or '…' is part of that value. A background-image: url(data:image/png;base64,…) already on the element survives every later write by anybody else. rinch-dom used to split on a bare ;, so the next unrelated set_style() on that node cut the URI in half and the image vanished.
• A property name is ASCII case-insensitive, as CSS makes it (issue #711). style: "color: blue; COLOR: red" is one property declared twice, not two properties, and a later set_style("color", …) replaces it however either was spelled. A custom property is the exception and is compared exactly: --Foo and --foo are two variables, here and in a browser.
• A property declared twice collapses at the last declaration’s position, which is what a browser does. That is behaviour and not spelling as soon as a shorthand is involved: style: "inset: 0px; left: 25px; inset: 4px" computes a left of 4px, because the surviving inset sits after the left it overrides.
• …but the value that survives is the !important one, which is not always the last. style: "color: red !important; color: blue" stays red, as in a browser. The slot still moves to the last declaration’s position; only the value is decided by priority.

One caveat on the last two, and it only bites on invalid CSS (issue #722): rinch collapses duplicates before validity where a browser collapses after. A browser throws an invalid declaration away as it parses, so the duplicate never competes; rinch keeps it, and the property can end up with no usable value. style: "color: notacolor !important; color: blue" computes blue in a browser and falls back to black here. Two valid declarations — the only shape worth writing — behave identically.

What the attribute reads back as afterwards is the CSSOM-touched form: names lowercased, duplicates collapsed. A browser keeps the author’s bytes in getAttribute("style") until something touches the CSSOM and rinch re-serialises on every merge, so rinch reaches that form one write earlier — the two agree on the result, not on when it appears. An element nobody has written to since is untouched either way.

/* … */ comments are removed before any of this — from a property name as readily as a value — everywhere CSS sees one, and each leaves a space behind, because a comment ends the token before it even though it is not one itself. The two places CSS does not see a comment are inside a string and inside an unquoted url(…), which is a single token: url(http://a/*b*/c.png) keeps its /*b*/ and names the image the author wrote, as in a browser. There is one place a browser sees a comment and keeps it where rinch removes it — the interior of a custom property value, where Chrome reads --x: 1px /* c */ 2px back verbatim and rinch reads it back as 1px 2px. The token stream is the same either way, so a var() substitution cannot tell; only the attribute string differs. An !important is carried through the value untouched; it is read, never rewritten, and the reading honours CSS’s own looseness — red!important, red ! IMPORTANT and red !ImPoRtAnT are all important, while a !important inside a string or url(…), or one whose ! is escaped, is ordinary text.

Styling

Inline styles and CSS classes work like regular HTML:

#![allow(unused)]
fn main() {
rsx! {
    html {
        head {
            style {
                "
                .container { padding: 20px; }
                .highlight { color: red; }
                "
            }
        }
        body {
            div { class: "container",
                span { class: "highlight", "Styled text" }
            }
        }
    }
}
}

State Management

There are no hooks. There is no re-rendering. Your component function runs once, builds the DOM, and closures keep it updated forever. Here’s how you manage state.

Core Primitives

For shared state, use stores. A store is a struct with Signal fields and methods that mutate them. Clean, testable, no prop drilling.

Signal

The foundational reactive primitive. Create one, read it in closures, and those closures re-run when the value changes.

#![allow(unused)]
fn main() {
let count = Signal::new(0);

count.get();                 // Read
count.set(5);                // Write
count.update(|n| *n += 1);  // Read-modify-write
}

Signal<T> is Copy. Use it in as many closures as you want — no .clone() needed.

#![allow(unused)]
fn main() {
#[component]
fn toggle() -> NodeHandle {
    let on = Signal::new(false);

    rsx! {
        button { onclick: move || on.update(|b| *b = !*b),
            {|| if on.get() { "ON" } else { "OFF" }}
        }
    }
}
}

Cross-Thread Dispatch

Signal::set() and Signal::update() must be called from the main thread. From a background thread, use send() and update_send():

#![allow(unused)]
fn main() {
let progress = Signal::new(0);

std::thread::spawn(move || {
    for i in 0..100 {
        std::thread::sleep(Duration::from_millis(50));
        progress.send(i);  // Dispatches to main thread automatically
    }
});
}

For more details, see Signals.

Memo

Cached derived state that recomputes only when its dependencies change.

#![allow(unused)]
fn main() {
let first = Signal::new("Alice".to_string());
let last = Signal::new("Smith".to_string());

let full = Memo::new(move || format!("{} {}", first.get(), last.get()));
// full.get() recomputes only when first or last change
}

Memo<T> is also Copy. Dependencies are tracked automatically — no dependency arrays.

For more details, see Memos.

Effect (Advanced)

Most reactive DOM updates happen through {|| expr} closures in RSX. For the rare case where you need to react to signal changes outside of the DOM (logging, syncing to an external system), use Effect:

#![allow(unused)]
fn main() {
use rinch::reactive::Effect;

let count = Signal::new(0);

Effect::new(move || {
    println!("Count is now: {}", count.get());
});
}

Effect is intentionally excluded from the prelude. If you’re reaching for it, ask yourself: can this be a closure in RSX, or a method on a store? Usually the answer is yes.

For more details, see Effects.

Lifetimes: What Owns Your State

State created during a render belongs to the thing being rendered, and dies with it. You rarely have to think about this — it is what stops a list that churns 10,000 rows from leaking 10,000 signals — but it becomes visible the moment a handle outlives its component.

The rule: a Signal, Memo, Effect or event handler created while something is rendering is owned by that render. When the owner goes away — a for row is reconciled out, an if branch flips, a component unmounts — every resource it owned is freed.

No ambient owner means app lifetime. A signal created in main(), in startup code, or in a detached callback has no owner and lives as long as the thread. That is why hoisted, app-wide state keeps working with no ceremony.

Reading a freed handle panics; writing to one does not

Signal<T> is Copy, so nothing stops a handle from outliving what created it — a background thread, a timer, a global registry. Reads and writes deliberately behave differently:

#![allow(unused)]
fn main() {
count.get();       // panics if the signal was freed
count.set(5);      // no-op plus a warning if the signal was freed
}

You may always write to a handle; you may only read a live one.

The asymmetry is not an oversight. A background thread that calls send() every 50ms cannot be asked to notice that the UI moved on, so a write to a dead signal must be survivable. A read has nothing to return — T need not implement Default — so it asserts.

When a handle may legitimately be gone, ask instead of assuming:

#![allow(unused)]
fn main() {
if let Some(n) = count.try_get() {       // None if freed
    println!("still here: {n}");
}
let len = items.try_with(|v| v.len());   // Option<usize> — None if freed
if count.is_alive() {                    // no subscription is created
    schedule_more_work();
}
}

Memo<T> has try_get() and is_alive() too. is_alive() never subscribes the current observer — liveness is not reactive, and tracking it would resurrect the dependency you are trying to drop.

Global callback registries are released too

A callback handed to a process-wide registry is the classic way for a component’s state to outlive the component — the registry keeps the closure, the closure keeps a Signal, and the next event reads a handle whose storage is gone. Registering one from inside a render therefore ties it to that render:

#![allow(unused)]
fn main() {
// `set_keyboard_interceptor` is not in the prelude — it is a document-level
// capture-phase hook, not everyday component API. `set_paste_interceptor` is.
use rinch::core::set_keyboard_interceptor;

#[component]
fn shortcuts() -> NodeHandle {
    let count = Signal::new(0);
    // Released when this component unmounts — the interceptor cannot outlive
    // `count` and read it after it is freed.
    set_keyboard_interceptor(move |k| {
        // Releases arrive here too (`k.is_up()`) — gate on the press or a
        // held "j" counts twice.
        if k.is_down() && k.key == "j" { count.update(|n| *n += 1); true } else { false }
    });
    rsx! { div { {|| count.get().to_string()} } }
}
}

This applies to set_keyboard_interceptor, set_paste_interceptor, set_selection_callback and set_selection_sync_callback (issue #183). Two consequences are worth knowing:

• Registering with no ambient owner still means app lifetime. A hook installed from main(), from startup code or from a detached callback has no owner, so nothing removes it — unchanged, and what app-wide shortcuts rely on.
• An earlier component unmounting never clears a later one’s registration. These are single, last-wins slots — per document, since two documents can share a thread (issues #340, #478): a registration made while a document’s code is running — its event dispatch, its mount, or an effect it owns (issue #295), or a timer, run_on_main_thread closure or http/ws callback armed from any of those (issue #963) — belongs to that document, one made outside any document (from main, a timer armed there, on rinch-web) is the thread-global fallback, and each document is served whichever of its own and the fallback is newer — so the last registration wins in a single-document app wherever it was made. A clear from outside any document clears every entry; one from inside a document leaves that document with nothing. With several documents on one thread that cuts both ways: code outside any document — main, a timer armed there, a closure queued from a worker thread, a native menu or tray callback — overrides every document’s own registration and its clear wipes them all. The release only reclaims the slot if it is still holding the callback that registered it.
• Register once per component, not once per event. Each call from inside a live component queues its own release, and those accumulate until the component unmounts. Installing a hook from a render (as above) is the intended shape; re-installing one on every click or on every run of a reactive closure is not.

rinch-ws callbacks work the same way from the outside — an on_message registered inside a component stops firing once that component unmounts, even if the WsHandle was parked somewhere longer-lived:

#![allow(unused)]
fn main() {
// `WsHandle` is neither `Clone` nor `Copy`, so a store holds it behind an `Rc`:
//     #[derive(Clone)] struct AppStore { socket: Rc<WsHandle> }
#[component]
fn feed() -> NodeHandle {
    let lines = Signal::new(Vec::<String>::new());
    // The socket outlives this component: the store holds the handle open.
    let ws = use_store::<AppStore>().socket;
    // Holds `lines`, which this component owns, so it must stop firing when
    // this component goes away.
    ws.on_message(move |m| {
        if let Some(t) = m.as_text() {
            lines.update(|v| v.push(t.to_string()));
        }
    });
    rsx! { div { {|| lines.get().join("\n")} } }
}
}

The mechanism underneath differs, and the difference is visible in one place. The interceptor slots above release the callback when the scope disposes; a WebSocket callback is checked at dispatch and dropped by the first event that arrives after the component is gone. That is deliberate: a socket’s callbacks can be re-registered as often as the app likes, and queueing a release per registration would grow without bound. The practical consequence is that the “register once per component” advice above does not apply to rinch-ws — and that a callback belonging to an unmounted component is released on the next event rather than at unmount.

Each of a connection’s four callbacks carries its own owner, so one handle may be shared by two components — a message list registering on_message, a connection-status badge registering on_close — and each stops on its own component’s unmount rather than on the other’s. A slot that will never be dispatched again (on_open after the handshake) is released by the first event that finds any of the connection’s callbacks dead.

Android platform callbacks

The rinch-android services follow the rinch-ws rule, for the same reason — they are registered from live components, often more than once:

#![allow(unused)]
fn main() {
use rinch_android::sensors::{DELAY_UI, SensorType};

#[component]
fn compass() -> NodeHandle {
    let heading = Signal::new([0.0f32; 3]);
    // Stops firing, and is released, when this component unmounts. Before, only
    // an explicit `stop()` removed it, and the callback kept reading `heading`
    // after it had been freed.
    rinch_android::sensors::start(SensorType::MagneticField, DELAY_UI, move |d| {
        heading.set([d.values[0], d.values[1], d.values[2]]);
    });
    rsx! { div { {|| format!("{:?}", heading.get())} } }
}
}

This covers sensors::start, location::start, lifecycle::on_pause / on_resume, and the one-shot results behind camera::pick_image, camera::take_photo, file_picker::pick_file / save_file and permissions::request_permission. Four things follow:

• The one-shots are covered too. They are removed on delivery, which bounds the leak but not the lifetime: Android delivers a result whatever the user does — a cancelled picker still reports RESULT_CANCELED — so a picker opened by a component that has since unmounted used to be delivered exactly once, into that component’s freed state. It is now discarded instead.
• Release does not wait for an event. Every one of these registries is drained once a frame, and each drain also releases what unmounted components left behind. A sensor that has fallen silent, an activity result that never comes back and an app that never backgrounds would otherwise pin their callbacks — and everything captured — for the life of the process. Each release is logged at debug, because the symptom is otherwise silent: the callback simply stops firing.
• Releasing a sensor or location callback powers the hardware down, because nothing else can. Once the entry is gone, sensors::stop has no SensorType to be called with and the component that knew it is disposed — so the release calls stopSensor / stopLocationUpdates itself, rather than freeing a Box and leaving a radio on. Only what it actually released: a sensor another component is still using stays armed, including one re-registered from inside the released callback’s own Drop.
• Registration from android_main keeps app lifetime, unchanged. That is what an app-wide on_pause autosave relies on.
• Stopping from inside the callback works. “Stop the sensor once the reading crosses a threshold”, or “stop location once the fix is accurate enough”, used to panic with a BorrowMutError, because the registry was borrowed across the call. So did swapping a lifecycle handler from inside one.

sensors::stop and location::stop remain the way to stop early — the moment you have the fix you wanted, rather than at unmount. What they no longer have to be is a leak-preventing ritual.

Keeping the screen on: a guard, not a callback

One Android service ties itself to the component by a third shape. screen::keep_screen_on() returns a guard — the display is held awake while the KeepScreenOn value is alive, and dropping it releases the hold (refcounted, so several holders compose). There is no callback to check at dispatch: a window flag is written once and never dispatched again, so nothing would ever visit it to notice a dead owner. The guard supplies the release structurally instead.

Most callers want the reactive form, which is also where unmount release comes from — the effect underneath is scope-owned, and disposal drops the closure holding the guard:

#![allow(unused)]
fn main() {
#[component]
fn player() -> NodeHandle {
    let playing = Signal::new(false);
    // Held while `playing` is true; released when it goes false — or when
    // this component unmounts mid-playback, whichever comes first.
    rinch_android::screen::keep_screen_on_while(move || playing.get());
    // ...
}
}

keep_screen_on_while(|| true) reads as “while this component is mounted”. The opt-out for a kiosk binary that genuinely never releases is keep_screen_on().leak(), from android_main.

Opting out

Sometimes a resource is meant to outlive the component that created it — state handed to a longer-lived store, a registration something else owns:

#![allow(unused)]
fn main() {
let s = Signal::new(0).leak();       // this one signal gets app lifetime
unowned(|| { /* nothing in here is owned by the current render */ });
}

leak() searches the owner stack as it stands now, so call it in the same render that created the signal; from a later callback the stack is empty and it does nothing. unowned is a free function at the crate root rather than in the prelude, deliberately: it is an attractive nuisance that converts a lifetime bug into a permanent leak. Reach for try_get() / is_alive() first.

Effects are the exception

Dropping an Effect handle does not stop the effect. Disposal is explicit (effect.dispose()) or comes from the owning scope. See Effects.

Context

Share state across components without prop drilling. The ancestor creates it, any descendant reads it.

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct AppConfig {
    api_url: String,
}

#[component]
fn app() -> NodeHandle {
    create_context(AppConfig { api_url: "https://api.example.com".into() });
    rsx! { div { ChildComponent {} } }
}

#[component]
fn ChildComponent() -> NodeHandle {
    let config = use_context::<AppConfig>();
    rsx! { Text { {config.api_url.clone()} } }
}
}

use_context::<T>() panics if the context is missing (with a helpful message). Use try_use_context::<T>() for an Option<T> instead.

For reactive shared state, use stores — they’re contexts with Signal fields and methods.

Putting It Together

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
fn app() -> NodeHandle {
    let todos = Signal::new(vec!["Learn Rinch".to_string()]);
    let input = Signal::new(String::new());
    let count = Memo::new(move || todos.get().len());

    let add = move || {
        let text = input.get();
        if !text.is_empty() {
            todos.update(|t| t.push(text.clone()));
            input.set(String::new());
        }
    };

    rsx! {
        Stack { gap: "md", p: "xl",
            Title { order: 1, "Todos (" {|| count.get().to_string()} ")" }

            Group { gap: "sm",
                TextInput {
                    placeholder: "What needs doing?",
                    value_fn: move || input.get(),
                    oninput: move |v: String| input.set(v),
                    onsubmit: add,
                }
                Button { onclick: add, "Add" }
            }

            for todo in todos.get() {
                div { key: todo.clone(), {todo.clone()} }
            }
        }
    }
}
}

Signal is Copy, so add captures todos and input without ceremony. count is a Memo that recomputes when todos changes. The for loop is reactive — add or remove a todo and only the affected DOM nodes change.

Reactivity

Rinch uses a fine-grained reactivity model inspired by Solid.js and Leptos. This means that when state changes, only the parts of your UI that depend on that state are updated—not the entire component tree.

Why Fine-Grained Reactivity?

Traditional virtual DOM approaches (like React) re-render entire component subtrees when state changes, then diff the virtual DOM to find what changed. This works well but has overhead.

Fine-grained reactivity tracks dependencies at a granular level. When a signal changes, only the specific effects subscribed to that signal re-run. There’s no diffing step—updates are direct.

Benefits:

• Minimal re-computation
• Predictable performance
• No dependency arrays to maintain
• Automatic subscription management

Core Primitives

Rinch provides three core reactive primitives, plus a store pattern for shared state:

Note: For DOM updates, use {|| expr} closures in rsx rather than Effect. For shared state, use stores. Effect is a power-user escape hatch for rare cases like syncing to external systems.

Quick Example

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
fn counter() -> NodeHandle {
    // Create reactive state
    let count = Signal::new(0);

    // Create a derived value (Memo is Copy, just like Signal)
    let doubled = Memo::new(move || count.get() * 2);

    rsx! {
        div {
            // Use closure syntax {|| ...} for reactive updates
            // Both Signal and Memo are Copy — no .clone() needed
            p { "Count: " {|| count.get().to_string()} }
            p { "Doubled: " {|| doubled.get().to_string()} }

            button {
                onclick: move || count.update(|n| *n += 1),
                "Increment"
            }
        }
    }
}
}

Note: The closure syntax {|| expr} is required for fine-grained reactive updates. Without it, values are captured once and never update. See RSX Syntax - Reactive Expressions for details.

When are closures unnecessary? Inside for loop bodies, components are re-created when the item data changes (via keyed reconciliation). Plain props from the loop variable don’t need closures — only per-item Signals do. See RSX Syntax - Reactivity in for Loops for details.

How Dependency Tracking Works

1. When an Effect or Memo runs, it registers itself as the “current observer”
2. When a Signal is read (via .get()), it checks for a current observer
3. If there’s an observer, the signal subscribes it
4. When the signal’s value changes (via .set() or .update()), all subscribers are notified

This happens automatically—you never manually specify dependencies.

┌─────────────────┐        .get()         ┌─────────────────┐
│     Effect      │ ────────────────────► │     Signal      │
│                 │                        │                 │
│  (observer)     │ ◄──── subscribes ──── │  (subscribers)  │
└─────────────────┘                        └─────────────────┘
                                                   │
                                              .set() / .update()
                                                   │
                                                   ▼
                                           notify all subscribers
                                                   │
                                                   ▼
                                           effects re-run

Dependencies are per-run

The dependency set is rebuilt on every run, not accumulated. An effect ends each run subscribed to exactly the signals and memos it read that time, so a dependency it stops reading stops waking it:

#![allow(unused)]
fn main() {
let show_details = Signal::new(true);
let details = Signal::new(String::new());

Effect::new(move || {
    if show_details.get() {
        render(details.get()); // subscribed only while the branch is taken
    }
});

show_details.set(false); // re-runs; `details` is no longer a dependency
details.set("...".into()); // does not re-run the effect
show_details.set(true);   // re-runs, and picks `details` back up
}

Disposal releases the subscriptions too — an effect (or a scope full of them) that is disposed leaves nothing behind in the signals it read, so a long-lived signal does not accumulate dead observers as components mount and unmount.

Execution Order

When several effects observe the same signal, they run in registration order — the order the Effects (or Memos) were created. This is a guaranteed contract, not an implementation detail.

That makes the “run me last” idiom well-defined: an effect registered after a tree of rendering effects observes their writes in the same synchronous flush, so a measuring effect can read the post-patch DOM rather than the previous frame’s.

#![allow(unused)]
fn main() {
let width = Signal::new(100);

// Registered first — writes.
Effect::new(move || resize_panel(width.get()));

// Registered second — reads what the first one just wrote.
Effect::new(move || {
    width.get();
    record_measurement(measure_panel());
});

width.set(250); // resize_panel runs, then record_measurement sees the new size
}

Two related guarantees follow from the same queue:

• Effects run in the order they were queued. Notifying signal A then signal B runs A’s effects before B’s.
• A signal written from inside an effect queues its observers behind the current flush, not ahead of it. Cascading updates therefore run breadth-first, and an effect already scheduled for this flush is never preempted.

Effects are still de-duplicated per flush: an effect observing two signals that both change in one batch() runs once, at the position of its first enqueue.

An effect does not wake itself

There is one exception to “queued behind the current flush”: a write that reaches the effect that is running is, for that effect, usually dropped rather than queued.

A write made while no batch is open flushes at once — and every effect body a flush runs is in that state, because a flush runs with the batch closed. So the flush happens while the body that made the write is still on the stack. It reaches the running effect, finds it running, and skips it. The write itself lands, and every other effect that reads the signal runs for it. The running effect keeps what it computed on this pass, the wake is not left in the queue for later, and the effect sees the new value the next time something else re-runs it.

“A write the body made” includes code the body calls, and the common case is a scope’s cleanup. An effect that disposes a scope runs that scope’s on_cleanup callbacks inside its own body — rsx!’s if, match and for all do when they swap a branch or remove a row — so a cleanup that writes a signal the disposing effect reads does not re-run it. For example, a for row whose cleanup writes a signal the list’s collection closure reads does not make the list reconcile a second time.

#![allow(unused)]
fn main() {
let trigger = Signal::new(0);
let tally = Signal::new(0);
let child = Scope::new();
child.on_cleanup(move || tally.update(|n| *n += 1));
let child = RefCell::new(Some(child));

Effect::new(move || {
    let t = trigger.get();
    let seen = tally.get();
    if t == 1 {
        let scope = child.borrow_mut().take();
        if let Some(scope) = scope {
            scope.dispose(); // its cleanup writes `tally`, which this effect read
        }
    }
    println!("saw tally = {seen}");
});              // prints "saw tally = 0"

trigger.set(1);  // prints "saw tally = 0"; tally is now 1, and this
                 // effect does not run again for it
trigger.set(2);  // prints "saw tally = 1"
}

This is deliberate, and it is what lets such an effect settle. Were the wake queued instead, an effect that disposes a scope on every run, whose cleanup writes a signal the effect reads, would schedule itself again on every run and never stop. So do not rely on an effect observing a write made by its own cleanup: have a different effect read that signal, or read the signal after the disposal in the same body.

The exception has an exception. When the body runs while a batch is open — an Effect::new or Effect::run called directly from an event handler, which is a batch, or inside batch() — its writes are queued rather than flushed, the queue drains only after the body has returned, and the effect does run again for its own write.

Batching Updates

Outside a batch, effects run after each update. To avoid redundant runs, use batch():

#![allow(unused)]
fn main() {
batch(|| {
    count.set(1);
    name.set("Alice".to_string());
    age.set(30);
    // Effects only run once, after the batch completes
});
}

A top-level batch() flushes synchronously: by the time it returns, every effect its writes woke has run. Batches also nest — a batch() called inside another batch’s closure joins the outer transaction, and the single flush happens when the outermost batch exits. (A batch() opened from inside an effect run by a flush is its own outermost batch — the flag is restored before the flush begins — so it still flushes before returning. An effect body that runs while a batch is still open is different: Effect::new runs its body immediately, so an effect created inside a batch closure runs inside that batch, and a batch() opened there joins the outer transaction instead of flushing.)

Until the flush, no effect has run: inside the closure — including after a nested batch() returns — effects have not executed, so a signal an effect writes still holds its old value. Memos are different: Memo::get inside the batch returns the new value. A write marks every memo that reads it stale synchronously, and the read recomputes it (see Memos). It used to return the pre-batch value, which made a handler that wrote a signal and then read a memo of it act on stale data. The DOM is different too: any NodeHandle call made in the batch first runs the effects queued so far (see below).

If the closure panics, the panic propagates and the batching flag is restored on the way out, so later writes flush normally. Nothing is flushed during the unwind itself — the effects the aborted batch queued stay pending and run at the next flush (the next unbatched write or outermost batch exit — every event handler is one, whether or not it writes anything; the runtime does not schedule one on its own).

Event handlers run as batches

You rarely need to call batch() yourself: rinch runs each of these as one, on desktop, on the web (the delegated listeners go through the same rinch_core::events::dispatch_* functions) and in embed:

• onclick and every other data-rid handler (the element drag attributes included), oninput/onchange, onscroll, file drops;
• the keyboard interceptor and the Escape dismiss stack (one transaction for both), the paste interceptor;
• Drag on_move, on_end and on_cancel;
• menu and tray callbacks, and their shortcuts;
• a registered focus target’s on_focus_gained, on_focus_lost, on_key and on_ime;
• each callback drained from the main-thread queue — Signal::send/update_send and run_on_main_thread called from another thread, and on native set_timeout, rinch-http and rinch-ws completions — one transaction per callback, not one for the whole drain, because they were queued independently and a later one may rely on an earlier one’s effects;
• on the web, a set_timeout callback, a rinch-http completion and a rinch-ws event, which arrive straight from the browser.

Everything else that calls into your code is not batched by rinch, and its writes flush one by one as they always did. That includes, for example: run_on_main_thread called on the main thread (it runs its closure there and then, inside whatever transaction is open), set_selection_callback / set_selection_sync_callback, the configuration-change handler, on_child_inserted / on_child_removed observers, a RenderSurface’s event handler, the editor’s EditorHandle::on_change, on_link_click, on_link_hover, on_key, on_selection_change and on_caret_moved callbacks, and effects and memo computations themselves. Wrap any of those in batch() yourself if it writes several signals.

So a handler that writes five signals flushes effects once, when it returns, and the host is told once (on desktop, one ReRender, not five). A handler that writes no signal tells the host nothing — no ReRender, and an embedded context is not marked dirty — unless the theme changed with update_theme() since the host was last told (in this handler, or outside any handler), or effects an earlier batch left queued are still waiting (see the panic note above), which it then runs. A DOM change a handler makes directly, through a NodeHandle, is picked up by the host’s own dirty-node check, not by this notification — except, on desktop today, a scroll_into_view() request from a handler that changes nothing else, which waits for the next layout (#1145). Library code that keeps other state a host reads only when told (not a signal, not the DOM) calls rinch_core::note_host_change() when it changes, so the batch still notifies. What that means inside the handler:

• Memos are current. Write, then read a memo of what you wrote: you get the new value.
• Effects run when the handler returns — or earlier, the moment the handler touches the DOM (next section). Until then a signal an effect derives still holds its old value; read the source signal (or a memo) instead.
• Glitch-free. An effect that reads several of the signals the handler wrote runs once, and sees all of the writes, never a mix of old and new.

Touching the DOM inside a handler

A handler that writes a signal and then works on the DOM itself was written expecting the write to have reached the DOM already — it always had:

#![allow(unused)]
fn main() {
button { onclick: move || {
    dialog_open.set(true);   // a Modal's effect shows the dialog and focuses its first field
    email_field.focus();     // …but this handler wants the email field
}, "Sign in" }

button { onclick: move || {
    messages.update(|m| m.push(new_message()));  // a `for` effect appends the row
    log.scroll_to_bottom();                      // …and this should reach it
}, "Send" }
}

So every NodeHandle operation made from handler code first runs the effects the handler has queued so far — focus(), scroll_into_view(), set_scroll_top(), scroll_to_bottom(), reads such as get_attribute, children, scroll_height or get_layout_bounds, and writes such as set_attribute alike. It is the analogue of a browser flushing pending style when script asks for layout. Program order is kept: the Modal’s own focus request is made first and the handler’s focus() overrides it; the new message row exists before the scroll; a set_attribute made after a signal write wins over the effect bound to that signal, instead of being overwritten when the handler returns. A handler that only writes signals still flushes exactly once. rinch_core::flush_pending_effects() does the same thing explicitly, for code that reaches the DOM some other way.

The rule applies to handler code, not to effects: a NodeHandle call inside an effect body or a memo computation never drains the queue, since that code runs inside a flush and must not run effects queued behind it ahead of their turn. A handler dispatched from an effect (an effect that calls dispatch_event, or a web focus() that fires a listener synchronously) is handler code again: its batch is a flush context of its own.

One way to trip over it in your own code. If a handler writes a signal and then makes a NodeHandle call while holding a borrow of a RefCell that an effect of that signal also borrows, the effect runs inside that call — and panics with BorrowError/BorrowMutError. Before handlers were batched the same effect ran at the write itself, before your borrow was taken; the conflict is the same, it just moved from the write to the DOM call. Take the borrow after the DOM call, or drop it before. (Editor queries such as is_mark_active are not DOM calls and run no effects.)

Writing a library that keeps its own RefCell state? A NodeHandle call inside a handler can now run user effects, and a user effect is free to call back into your API. If your code touches the DOM while it holds a borrow of its own state, that is a BorrowMutError waiting to happen. Hold rinch_core::reactive::suppress_effect_flush() for as long as the borrow lives — no effect runs inside it; the pending ones run at the next DOM access outside it, or when the batch ends — and call rinch_core::flush_pending_effects() just before taking the borrow, so the caller’s earlier writes have reached the DOM you are about to work on. The rich-text editor does exactly this around every borrow of its core, so tick.set(1); editor.command("toggleBold") in one handler, or two commands in a row with an on_change that bumps a toolbar signal, behave as they did before handlers were batched.

Two consequences to know about

An effect sees only where the handler ended up, never the steps. show.set(false); show.set(true) in one handler does not remount the if branch; removing a for item and putting one with the same key back keeps that row and its state; closing and re-opening an overlay in one handler neither restores nor re-captures focus. (A NodeHandle call in between flushes, so it does make the step visible — that is what the rule above is for.)

A handler that blocks keeps its transaction open. If a handler shows a native modal dialog (a file picker, a message box) that runs a nested platform event loop — which macOS and Windows dialogs can — its batch stays open until the dialog returns, and anything rinch runs meanwhile, such as a drained Signal::send or a timer, joins that batch: its effects run when the dialog closes, not when it arrived.

Reading Without Tracking

Sometimes you want to read a signal without creating a subscription. Use untracked():

#![allow(unused)]
fn main() {
Effect::new(move || {
    // This creates a subscription
    let count = count.get();

    // This does NOT create a subscription
    let name = untracked(|| name.get());

    println!("Count: {count}, Name: {name}");
});
// This effect only re-runs when `count` changes, not when `name` changes
}

untracked hides only the observer directly above it. That matters only while an effect’s run is nested inside another effect’s run — the first run of an Effect::new written inside another effect’s body, for instance. A read inside untracked there is recorded on the outer effect. Later re-runs of the inner effect normally come from a flush with no effect beneath them and are unaffected (issue #932).

App handlers never subscribe the effect that calls them

A component often calls its app’s handler from inside one of its own effects — a coordinating effect that ends in onchange, a value_fn binding that reports back. The handler is app code, and it routinely reads signals: the controlled idiom onchange: move |v| if v != store.get() { store.set(v) } reads the store it writes. If that read counted, the component’s internal effect would be subscribed to the app’s store, and a write to the store from anywhere else would re-run it out of turn.

So every app-callback type’s invoke — Callback, ValueCallback<T>, InputCallback, FileDropCallback and ScrollCallback — runs the handler with no observer in view, however many effects deep the call is (issue #285). Handlers respond to events; effects respond to signals. A component author does not need to wrap cb.invoke(..) in untracked any more.

Only tracking changes: batching is untouched, so a handler’s writes inside an event handler still flush once, when the batch ends. An effect the handler creates, or one its writes run, tracks normally.

The same holds for the other app callbacks rinch runs synchronously from a call you can make inside an effect (issue #931):

• the rich-text editor’s EditorHandle hooks — on_change, on_selection_change, on_caret_moved, on_key, on_link_click and on_link_hover — so an app effect that calls set_selection, runs a command or offers a key is not subscribed to a popup hook’s own open signal;
• the child observers (rinch_core::dom::on_child_inserted / on_child_removed), which every for reconcile, if branch swap and component re-render reaches from inside its effect;
• the selection and selection-sync callbacks (query_selection_ranges, fire_selection_sync), the keyboard and paste interceptors (dispatch_keyboard_event, dispatch_paste_event), the dismiss stack (dispatch_dismiss) and Drag::cancel’s on_cancel.

Editor plugin code is untracked the same way (issue #943): apply, init_state, decorations, handle_paste, a plugin’s commands and input rules run under the editor’s own borrow, inside whatever effect called the handle, so a spellchecker whose decorations() reads an app spellcheck_on signal does not subscribe every effect that moves the selection. A plugin that should react to a signal needs something that re-asks it — an effect of its own that dispatches a transaction when the signal changes. Plugin code your own update closure calls (below) is part of that closure, and tracked. The collaboration outbound sink runs untracked too (issue #948): a transport closure that reads a connected signal does not subscribe the effect that made the edit.

A closure you pass as the call itself is not one of these: the build closure of EditorHandle::update(|state| …) runs as part of your own code, and a signal it reads is your effect’s dependency like any other.

If you write a component or library that stores an app’s callback and calls it later, call it through rinch_core::untracked_handler(|| cb(..)) for the same reason. The five callback types do this in their invoke; a bare Rc<dyn Fn()> does not. A closure a component stores and calls itself — an Rc<dyn Fn()>, a render_fn — is an ordinary call and is tracked like any other code in the effect; that is what a _fn prop such as value_fn relies on, and why the choice is yours.

Memory Management with Scopes

Reactive resources continue to exist until something disposes them. Usually that something is implicit: a Scope::run(f) makes that scope the ambient owner for f, so every Signal, Memo, Effect and event handler created inside is attributed to it and freed when it is disposed. Rendering runs under a scope, so component state is cleaned up without you asking.

#![allow(unused)]
fn main() {
let scope = Scope::new();

scope.run(|| {
    let count = Signal::new(0);          // owned by `scope`
    Effect::new(move || { count.get(); }); // owned by `scope`
});

scope.dispose(); // both are freed
}

scope.add_effect(effect) is the manual path, for an effect built outside the scope that should still die with it.

With no ambient owner, a resource has app lifetime — which is why signals created in main() or in startup code keep working untouched. Because handles are Copy and can outlive their values, reads of a freed handle panic while writes are warn-once no-ops; use try_get() / is_alive() when a handle may legitimately be gone. See Lifetimes for the full story.

Next Steps

• Signals - Reactive state containers
• Memos - Cached computed values
• Stores - Shared state with action methods
• Effects - Advanced: side-effects that track dependencies

Signals

A Signal holds a value and tells everyone who cares when it changes. Signals are the foundation of everything reactive in Rinch.

Creating Signals

#![allow(unused)]
fn main() {
let count = Signal::new(0);
let name = Signal::new(String::from("Alice"));
let items = Signal::new(vec![1, 2, 3]);
}

Signals can hold any 'static type. They’re cheap — a Signal<T> is an index and a generation counter into a thread-local slot map, not a smart pointer. The generation is what lets a handle outlive its value safely: a recycled slot carries a generation no stale handle holds, so a freed signal is detected, never silently confused with a new one.

Signal is Copy

This is the single most important thing about Rinch’s reactive system. Signal<T> implements Copy. You never need .clone() before passing a signal into a closure:

#![allow(unused)]
fn main() {
let count = Signal::new(0);

// Use count in as many closures as you want — it's Copy
Effect::new(move || println!("count = {}", count.get()));
rsx! {
    button { onclick: move || count.update(|n| *n += 1), "+" }
    span { {|| count.get().to_string()} }
}
}

Same for Memo<T> — also Copy.

Reading Values

.get() — Clone and Return

#![allow(unused)]
fn main() {
let count = Signal::new(0);
let value = count.get(); // Returns 0 (cloned)
}

Inside an Effect or Memo, calling .get() automatically subscribes to the signal. When the signal changes, the Effect re-runs. No dependency arrays. No manual tracking.

.with() — Access by Reference

For types that are expensive to clone:

#![allow(unused)]
fn main() {
let items = Signal::new(vec![1, 2, 3, 4, 5]);

let length = items.with(|v| v.len());
let first = items.with(|v| v.first().copied());
}

Writing Values

.set() — Replace

#![allow(unused)]
fn main() {
count.set(5); // Notifies all subscribers
}

.update() — Modify in Place

#![allow(unused)]
fn main() {
count.update(|n| *n += 1);
items.update(|v| v.push(4));
}

Liveness

A signal created during a render is owned by that render and is freed when it goes away (see Lifetimes). Because Signal<T> is Copy, a handle can easily outlive the value:

Reads assert and writes forgive, because a write can come from somewhere that cannot be asked to check — a background thread mid-send(), a timer that has not fired its last tick yet — while a read has nothing to return.

#![allow(unused)]
fn main() {
// From a long-lived callback or a worker holding a Copy handle:
if let Some(n) = count.try_get() {
    println!("still here: {n}");
}
}

is_alive() does not subscribe the current observer. Liveness is not reactive, and tracking it would resurrect the dependency you are trying to drop.

If a signal is deliberately meant to outlive its component, say so explicitly with Signal::new(0).leak() rather than relying on it accidentally surviving.

Automatic Dependency Tracking

Read a signal inside an Effect or Memo and the dependency is tracked automatically:

#![allow(unused)]
fn main() {
let first_name = Signal::new("Alice".to_string());
let last_name = Signal::new("Smith".to_string());

// This effect depends on BOTH signals — discovered at runtime
Effect::new(move || {
    println!("{} {}", first_name.get(), last_name.get());
});

first_name.set("Bob".to_string());   // Effect re-runs
last_name.set("Jones".to_string());  // Effect re-runs
}

Dependencies are dynamic. If a signal is only read conditionally, the subscription only exists when that branch executes.

Cross-Thread Dispatch

set() and update() panic if called from a non-main thread (with a helpful message). For background threads, use send() and update_send():

#![allow(unused)]
fn main() {
let progress = Signal::new(0);

std::thread::spawn(move || {
    for i in 0..100 {
        std::thread::sleep(std::time::Duration::from_millis(50));
        progress.send(i);  // Dispatches to main thread
    }
});
}

send() requires T: Send. update_send() requires the closure to be Send + 'static.

A worker may start sending before the app does — spawned in main() ahead of App::run(). Such a write is queued and applied once the app has started (issue #1541); it used to be dropped. That holds for a thread that has created no signals of its own: rinch tells the thread that owns a signal from a worker by whether it has ever created one, until the host registers its main thread.

Best Practices

Keep signals focused. One signal per concern, not one giant state bag:

#![allow(unused)]
fn main() {
// Good
let name = Signal::new(String::new());
let age = Signal::new(0);

// Less good — changing name re-runs everything that reads age too
let state = Signal::new(AppState { name, age });
}

Read once before loops:

#![allow(unused)]
fn main() {
// Read once, loop over the snapshot
let val = items.get();
for item in &val {
    // use item
}
}

Use {|| expr} in RSX, not raw Effects. The RSX closure syntax is the right tool for DOM updates. Reserve Effect::new() for side effects outside the DOM (logging, network calls, syncing external state).

Effects

An Effect is a side-effect that runs when its dependencies change. It tracks which signals it reads and re-runs when any of them update. No dependency arrays, no manual subscription — just read a signal and you’re subscribed.

You probably don’t need this. For reactive DOM updates, use {|| expr} closures in RSX. For state mutations, use store methods. Effect is for the rare case where you need to react to signal changes outside of both — logging, syncing to external systems, etc.

Effect is intentionally excluded from the prelude. Import explicitly:

#![allow(unused)]
fn main() {
use rinch::reactive::Effect;
}

Creating Effects

#![allow(unused)]
fn main() {
let count = Signal::new(0);

// Runs immediately, then re-runs when count changes
Effect::new(move || {
    println!("Count is: {}", count.get());
});

count.set(1); // Prints: "Count is: 1"
count.set(2); // Prints: "Count is: 2"
}

Signal is Copy, so you can use count in the closure and still use it elsewhere. No .clone().

When Effects Run

1. Immediately on creation — the effect runs once right away
2. When dependencies change — whenever a tracked signal is updated

#![allow(unused)]
fn main() {
let a = Signal::new(1);
let b = Signal::new(2);

Effect::new(move || {
    println!("a = {}, b = {}", a.get(), b.get());
});
// Prints: "a = 1, b = 2"

a.set(10); // Prints: "a = 10, b = 2"
b.set(20); // Prints: "a = 10, b = 20"
}

Conditional Dependencies

Dependencies are discovered at runtime, not declared statically. If a signal is only read in one branch, the subscription only exists when that branch executes:

#![allow(unused)]
fn main() {
let show_details = Signal::new(false);
let name = Signal::new("Alice".to_string());
let age = Signal::new(30);

Effect::new(move || {
    println!("Name: {}", name.get());
    if show_details.get() {
        println!("Age: {}", age.get()); // only tracked when show_details is true
    }
});

age.set(31);           // Nothing happens — age isn't tracked yet
show_details.set(true); // Re-runs, now age IS tracked
age.set(32);           // Re-runs — age is tracked now
}

Common Patterns

Logging

#![allow(unused)]
fn main() {
let count = Signal::new(0);
Effect::new(move || {
    println!("[DEBUG] count = {}", count.get());
});
}

Syncing to External Systems

#![allow(unused)]
fn main() {
let theme = Signal::new("light".to_string());
Effect::new(move || {
    update_css_theme(&theme.get());
});
}

Derived Side Effects

#![allow(unused)]
fn main() {
let items = Signal::new(vec![1, 2, 3]);
Effect::new(move || {
    let count = items.with(|v| v.len());
    update_badge(count);
});
}

Disposing Effects

An effect stops when it is disposed — explicitly, or by the scope that owns it:

#![allow(unused)]
fn main() {
let effect = Effect::new(move || {
    println!("Count: {}", count.get());
});

effect.dispose(); // Effect stops running
count.set(1);     // Nothing happens
}

Dropping the handle does not dispose the effect. This is deliberate and it is what every example on this page relies on: Effect::new(move || …); with no let drops the returned handle immediately, and the effect keeps running anyway. The closure lives in a registry keyed by id, not in the handle, because an effect is queued and run by id long after the caller has forgotten it.

So an effect has exactly two ends:

• Explicit — effect.dispose().
• Owned — an effect created during a render belongs to that render, and is disposed when the component unmounts, the if branch flips, or the for row is reconciled away. This is the usual case, and it is why RSX closures never need cleaning up by hand.

An effect created with no ambient owner and no retained handle — from main(), from startup code, from a detached callback — runs for the life of the thread. That is the right default for app-wide wiring and a leak everywhere else, so prefer creating effects during a render, where something owns them.

Disposal is what reclaims the registry entry, not merely what silences it: everything the closure captured is dropped with it.

Pitfalls

Don’t create effects inside effects. The inner effect gets recreated every time the outer one re-runs.

Don’t modify a signal you read in the same effect. That’s an infinite loop. Use untracked(|| signal.get()) if you need to read without subscribing.

#![allow(unused)]
fn main() {
// BAD: infinite loop
Effect::new(move || {
    let val = count.get();
    count.set(val + 1); // triggers re-run -> reads count -> triggers re-run -> ...
});

// OK: read without subscribing
Effect::new(move || {
    let val = untracked(|| count.get());
    do_something(val);
});
}

Memos

A Memo is a cached computed value that only recomputes when its dependencies change. Think of it as a signal you can’t write to — it derives its value from other signals.

Creating Memos

#![allow(unused)]
fn main() {
let count = Signal::new(2);

let doubled = Memo::new(move || count.get() * 2);

doubled.get(); // 4
count.set(3);
doubled.get(); // 6 (recomputed)
doubled.get(); // 6 (cached — no recomputation)
}

Memo<T> is Copy, just like Signal<T>. Use it in multiple closures without .clone().

The value type must be Clone + PartialEq. PartialEq is what the equality cut-off below compares with; a type that cannot implement it meaningfully can implement it as “never equal” (fn eq(&self, _: &Self) -> bool { false }), which gives back the old behaviour of waking every dependent on every recompute.

How Memos Work

1. Lazy — only computes when you call .get()
2. Cached — returns the cached result if dependencies haven’t changed
3. Tracked — automatically discovers which signals it reads
4. Composable — memos can depend on other memos
5. Cut off on equality — a recompute that produces a value equal to the previous one wakes none of the memo’s dependents
6. Always current — a read straight after a write to one of its sources sees the new value, even inside a batch() or an event handler that has not returned yet

Signal(count) ──► Memo(doubled) ──► cached value
    │                   │
  .set(3)            .get()
    │                   │
    ▼                   ▼
 marks memo       recomputes if
 as "dirty"          dirty

The equality cut-off

The pattern it exists for is per-row derived state:

#![allow(unused)]
fn main() {
let selected = Signal::new(3);

for row in rows.get() {
    let id = row.id;
    let is_selected = Memo::new(move || selected.get() == id);
    div { key: id, class: {move || if is_selected.get() { "row selected" } else { "row" }} }
}
}

Every row’s memo reads selected, so a selection change recomputes all of them — a comparison each. But only two answers change (the row that lost the selection and the row that gained it), so only those two rows’ class effects run. Without the cut-off every row’s effect ran on every click.

How it works: a write marks the memos that read it stale at once (so a read straight after the write is current), and a memo’s dependents are woken as maybes. Before running a maybe, the flush brings the memos it read up to date and compares each one’s version — a counter that moves only when a recompute produces an unequal value — with the version the dependent saw last time. None moved: it is skipped. An effect that also reads a signal that changed is not a maybe, and runs as usual; signals have no cut-off (set notifies whether or not the value changed — use set_if_changed for that).

The cut-off chains: a memo that reads a memo which recomputed to an equal value is re-validated without running its own computation. A source memo that has been freed (its scope disposed) counts as changed, so a reader that falls back with try_get() recomputes once and sees None rather than keeping a value computed from a memo that no longer exists.

Memos vs Effects

Use a Memo when you need a computed value. Use an Effect when you need to perform an action.

Chaining Memos

Memos can depend on other memos:

#![allow(unused)]
fn main() {
let count = Signal::new(2);
let doubled = Memo::new(move || count.get() * 2);
let quadrupled = Memo::new(move || doubled.get() * 2);

assert_eq!(quadrupled.get(), 8);
count.set(3);
assert_eq!(quadrupled.get(), 12);
}

The derived() Helper

Syntactic sugar for Memo::new():

#![allow(unused)]
fn main() {
let count = Signal::new(5);

// These are equivalent:
let doubled = Memo::new(move || count.get() * 2);
let doubled = derived(move || count.get() * 2);
}

Common Patterns

Computed Strings

#![allow(unused)]
fn main() {
let first = Signal::new("Alice".to_string());
let last = Signal::new("Smith".to_string());

let full = Memo::new(move || format!("{} {}", first.get(), last.get()));
}

Filtering Lists

#![allow(unused)]
fn main() {
let items = Signal::new(vec![1, 2, 3, 4, 5, 6]);
let show_even = Signal::new(true);

let filtered = Memo::new(move || {
    let all = items.get();
    if show_even.get() {
        all.into_iter().filter(|n| n % 2 == 0).collect()
    } else {
        all
    }
});
}

Expensive Computations

#![allow(unused)]
fn main() {
let data = Signal::new(large_dataset);

// Only recomputes when data changes, no matter how many times you .get()
let analysis = Memo::new(move || {
    data.with(|d| perform_analysis(d))
});
}

Memos in RSX

Memos work in reactive closures exactly like signals:

#![allow(unused)]
fn main() {
let count = Signal::new(0);
let doubled = Memo::new(move || count.get() * 2);

rsx! {
    p { "Count: " {|| count.get().to_string()} }
    p { "Doubled: " {|| doubled.get().to_string()} }
}
}

Both count and doubled are Copy. Both create subscriptions when read in {|| ...} closures. The doubled text node updates only when the memo’s value actually changes.

State Management with Stores

Stores are the recommended way to manage shared state in rinch. A store is a plain struct with Signal fields and methods that encapsulate state mutations.

The Store Pattern

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[derive(Clone, Copy)]
struct CounterStore {
    count: Signal<i32>,
}

impl CounterStore {
    fn new() -> Self {
        Self { count: Signal::new(0) }
    }

    fn increment(&self) {
        self.count.update(|n| *n += 1);
    }

    fn decrement(&self) {
        self.count.update(|n| *n -= 1);
    }

    fn reset(&self) {
        self.count.set(0);
    }
}
}

Why this works well:

• State and mutations live together — no scattered signal updates across components
• Signal<T> is Copy, so the store struct is Copy when all fields are signals
• Methods are the single source of truth for how state changes
• Easy to test, easy to reason about

Providing and Consuming Stores

Call create_store() in a parent component to make the store available to all descendants. Call use_store::<T>() in any descendant to retrieve it.

#![allow(unused)]
fn main() {
#[component]
fn app() -> NodeHandle {
    create_store(CounterStore::new());

    rsx! {
        div {
            CounterDisplay {}
            CounterControls {}
        }
    }
}

#[component]
fn counter_display() -> NodeHandle {
    let store = use_store::<CounterStore>();

    rsx! {
        p { "Count: " {|| store.count.get().to_string()} }
    }
}

#[component]
fn counter_controls() -> NodeHandle {
    let store = use_store::<CounterStore>();

    rsx! {
        div {
            button { onclick: move || store.decrement(), "-" }
            button { onclick: move || store.reset(), "Reset" }
            button { onclick: move || store.increment(), "+" }
        }
    }
}
}

use_store::<T>() panics with a helpful message if no store of that type exists:

Store not found: CounterStore
Did you forget to call create_store() in a parent component?

Use try_use_store::<T>() when a store may legitimately be absent — it returns Option<T>.

A Larger Example: Todo Store

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[derive(Clone, PartialEq)]
struct Todo {
    id: u32,
    text: String,
    done: bool,
}

#[derive(Clone, Copy)]
struct TodoStore {
    todos: Signal<Vec<Todo>>,
    next_id: Signal<u32>,
    filter: Signal<Filter>,
}

#[derive(Clone, Copy, PartialEq)]
enum Filter { All, Active, Completed }

impl TodoStore {
    fn new() -> Self {
        Self {
            todos: Signal::new(Vec::new()),
            next_id: Signal::new(1),
            filter: Signal::new(Filter::All),
        }
    }

    fn add(&self, text: String) {
        let id = self.next_id.get();
        self.next_id.set(id + 1);
        self.todos.update(|t| t.push(Todo { id, text, done: false }));
    }

    fn toggle(&self, id: u32) {
        self.todos.update(|todos| {
            if let Some(todo) = todos.iter_mut().find(|t| t.id == id) {
                todo.done = !todo.done;
            }
        });
    }

    fn remove(&self, id: u32) {
        self.todos.update(|t| t.retain(|todo| todo.id != id));
    }

    fn visible_todos(&self) -> Vec<Todo> {
        let todos = self.todos.get();
        match self.filter.get() {
            Filter::All => todos,
            Filter::Active => todos.into_iter().filter(|t| !t.done).collect(),
            Filter::Completed => todos.into_iter().filter(|t| t.done).collect(),
        }
    }

    fn remaining_count(&self) -> usize {
        self.todos.with(|t| t.iter().filter(|t| !t.done).count())
    }
}
}

Components consume the store and call its methods:

#![allow(unused)]
fn main() {
#[component]
fn todo_app() -> NodeHandle {
    create_store(TodoStore::new());
    let store = use_store::<TodoStore>();
    let input = Signal::new(String::new());

    rsx! {
        div {
            TextInput {
                placeholder: "What needs to be done?",
                value_fn: move || input.get(),
                oninput: move |val: String| input.set(val),
                onsubmit: move || {
                    let text = input.get();
                    if !text.is_empty() {
                        store.add(text);
                        input.set(String::new());
                    }
                },
            }

            p { {|| format!("{} items left", store.remaining_count())} }

            for todo in store.visible_todos() {
                div { key: todo.id,
                    Checkbox {
                        label: todo.text.clone(),
                        checked_fn: {
                            let done = todo.done;
                            move || done
                        },
                        on_change: {
                            let id = todo.id;
                            move || store.toggle(id)
                        },
                    }
                    button {
                        onclick: { let id = todo.id; move || store.remove(id) },
                        "Delete"
                    }
                }
            }
        }
    }
}
}

Side Effects Belong in Store Methods

Keep side effects (logging, persistence, validation) inside store methods rather than scattered across components:

#![allow(unused)]
fn main() {
impl TodoStore {
    fn add(&self, text: String) {
        let id = self.next_id.get();
        self.next_id.set(id + 1);
        self.todos.update(|t| t.push(Todo { id, text: text.clone(), done: false }));

        // Side effect lives here, not in 5 different components
        println!("Added todo #{id}: {text}");
    }
}
}

This keeps components focused on rendering and event handling.

When You Don’t Need a Store

For component-local state that no other component needs, just use Signal::new() directly:

#![allow(unused)]
fn main() {
#[component]
fn toggle_button() -> NodeHandle {
    let expanded = Signal::new(false);

    rsx! {
        button {
            onclick: move || expanded.update(|v| *v = !*v),
            {|| if expanded.get() { "Collapse" } else { "Expand" }}
        }
    }
}
}

No store needed — expanded is only used by this one component.

Use a store when:

• Multiple components need to read or write the same state
• You want to centralize mutation logic (validation, side effects)
• State has complex update rules that benefit from named methods

Use a plain Signal when:

• State is local to a single component (toggles, input text, hover state)
• No other component cares about this value

Advanced: Explicit Effects

Most reactive DOM updates use {|| expr} closures in rsx — you rarely need Effect directly. For advanced cases like syncing state to an external system, import it explicitly:

#![allow(unused)]
fn main() {
use rinch::reactive::Effect;

let count = Signal::new(0);

// Sync to an external system whenever count changes
Effect::new(move || {
    update_external_dashboard(count.get());
});
}

You probably don’t need Effect. If you’re updating the DOM, use {|| expr} in rsx. If you’re updating state, put the logic in a store method. Effect is for the rare case where you need to react to signal changes outside of both rendering and user actions.

Sharing State

There are three ways to share state between components in Rinch: stores (recommended), lifting state up (passing signals as props), and context (low-level implicit sharing).

Recommended: For most shared state, use the store pattern — a struct with Signal fields shared via create_store() / use_store().

Stores (Recommended)

See the full Stores guide. Quick summary:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy)]
struct AppStore {
    count: Signal<i32>,
}

impl AppStore {
    fn new() -> Self { Self { count: Signal::new(0) } }
    fn increment(&self) { self.count.update(|n| *n += 1); }
}

#[component]
fn app() -> NodeHandle {
    create_store(AppStore::new());
    rsx! { div { Counter {} } }
}

#[component]
fn counter() -> NodeHandle {
    let store = use_store::<AppStore>();
    rsx! {
        p { {|| store.count.get().to_string()} }
        button { onclick: move || store.increment(), "+" }
    }
}
}

Lifting State Up

The simplest approach — move state to the nearest common ancestor and pass it down as props.

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
pub fn Counter(count: Signal<i32>, children: &[NodeHandle]) -> NodeHandle {
    rsx! {
        div {
            p { "Count: " {|| count.get().to_string()} }
            {children}
        }
    }
}

#[component]
fn app() -> NodeHandle {
    // State lives here, shared with both children
    let count = Signal::new(0);

    rsx! {
        div {
            Counter { count,
                button { onclick: move || count.update(|n| *n += 1), "+" }
                button { onclick: move || count.update(|n| *n -= 1), "-" }
            }
        }
    }
}
}

Signal<T> implements Copy, so you can pass it to multiple children without .clone().

When to use: When only a small number of nearby components need the same state.

Context

Context lets you share state without explicitly threading it through props. Call create_context() in an ancestor component, then use_context::<T>() in any descendant.

Creating Context

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct Theme {
    primary: String,
    dark_mode: bool,
}

#[component]
fn app() -> NodeHandle {
    create_context(Theme {
        primary: "#007bff".into(),
        dark_mode: false,
    });

    rsx! {
        div {
            // All descendants can access Theme
            Toolbar {}
            MainContent {}
        }
    }
}
}

Consuming Context

use_context::<T>() returns T directly. It panics with a helpful message if the context is absent:

Context not found: Theme
Did you forget to call create_context() in a parent component?

#![allow(unused)]
fn main() {
#[component]
fn toolbar() -> NodeHandle {
    let theme = use_context::<Theme>();

    rsx! {
        nav { style: {|| format!("background: {}", theme.primary)},
            "Toolbar"
        }
    }
}
}

Fallible Access

Use try_use_context::<T>() when a context may legitimately be absent — it returns Option<T> instead of panicking:

#![allow(unused)]
fn main() {
#[component]
fn themed_button() -> NodeHandle {
    let theme = try_use_context::<Theme>();
    let bg = theme.map(|t| t.primary).unwrap_or("#ccc".into());

    rsx! {
        button { style: {|| format!("background: {}", bg)},
            "Click me"
        }
    }
}
}

When to use: When a component can render sensibly with or without the context (e.g., a component used both inside and outside a theme provider).

Reactive Context with Signals

For context that changes over time, store a Signal<T> in context so descendants can both read and update it:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy)]
struct AppState {
    dark_mode: Signal<bool>,
    user_name: Signal<String>,
}

#[component]
fn app() -> NodeHandle {
    create_context(AppState {
        dark_mode: Signal::new(false),
        user_name: Signal::new("Guest".into()),
    });

    rsx! {
        div {
            Header {}
            MainContent {}
        }
    }
}

#[component]
fn header() -> NodeHandle {
    let state = use_context::<AppState>();

    rsx! {
        header {
            span { {|| state.user_name.get()} }
            button {
                onclick: move || state.dark_mode.update(|v| *v = !*v),
                {|| if state.dark_mode.get() { "Light mode" } else { "Dark mode" }}
            }
        }
    }
}
}

Because Signal<T> is Copy, the AppState struct itself is Copy when all its fields are signals, making it cheap to access from any descendant.

Which Approach to Use?

Writing Your Own Components

You have two options. The first one is almost always what you want.

Option 1: PascalCase Component Functions

Write a function with a PascalCase name and #[component]. The macro generates a struct, a Default impl, and a Component trait impl. Parameters become props. Done.

The name’s case is what makes it a component. rsx! reads it to tell markup from a component, so MyThing { … } calls your function while my_thing { … } is looked up as an HTML tag. A lowercase #[component] function is still perfectly good Rust — it just has to be called as one: { my_thing(__scope) }. Writing my_thing { … } is a compile error that says so (issue #528); before that it rendered an empty <my_thing> element and never called the function.

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
pub fn UserCard(
    name: String,
    email: String,
    avatar_url: String,
    online: bool,
    onclick: Option<Callback>,
) -> NodeHandle {
    rsx! {
        Paper { shadow: "sm", p: "md",
            Group { gap: "md",
                Avatar { src: avatar_url.clone(), size: "lg" }
                Stack { gap: "xs",
                    Text { fw: "bold", {name.clone()} }
                    Text { size: "sm", color: "dimmed", {email.clone()} }
                }
                if online {
                    Badge { color: "green", variant: "dot", "Online" }
                }
            }
        }
    }
}
}

Use it:

#![allow(unused)]
fn main() {
rsx! {
    UserCard {
        name: "Alice",
        email: "alice@example.com",
        avatar_url: "/avatars/alice.png",
        online: true,
        onclick: || println!("clicked!"),
    }
}
}

The Rules

Prop types must be owned. String, not &str. Vec<T>, not &[T]. The macro will give you a clear error if you use a reference type.

The macro wraps things for you. Don’t fight it:

Don’t manually wrap. Writing onclick: Some(Callback::new(|| ...)) double-wraps and you’ll get confusing type errors.

children: &[NodeHandle] is special. It’s not a struct field — it captures child elements passed in RSX:

#![allow(unused)]
fn main() {
#[component]
pub fn Card(title: String, children: &[NodeHandle]) -> NodeHandle {
    rsx! {
        Paper { shadow: "sm", p: "md",
            Title { order: 3, {title.clone()} }
            // children are automatically appended
        }
    }
}

// Usage:
rsx! {
    Card { title: "My Card",
        Text { "This is a child" }
        Button { "So is this" }
    }
}
}

Option 2: Manual Component Trait

For full control, implement Component directly:

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[derive(Debug, Default)]
pub struct Countdown {
    pub from: i32,
}

impl Component for Countdown {
    fn render(&self, scope: &mut RenderScope, _children: &[NodeHandle]) -> NodeHandle {
        let remaining = Signal::new(self.from);

        // rsx! works inside Component::render too — __scope is just `scope` here
        let __scope = scope;
        rsx! {
            div {
                Text { size: "xl", {|| remaining.get().to_string()} }
                Button {
                    disabled: {|| remaining.get() <= 0},
                    onclick: move || remaining.update(|n| *n -= 1),
                    "Count down"
                }
            }
        }
    }
}
}

You probably don’t need this. The PascalCase function covers 95% of use cases. But it’s there for when you need custom Debug, or want to store state on the struct itself, or are doing something the macro can’t express.

Lowercase Component Functions

Not everything needs to be a reusable component with props. For private helper functions, use a lowercase name:

#![allow(unused)]
fn main() {
#[component]
fn sidebar_link(label: &str, active: bool) -> NodeHandle {
    rsx! {
        div { class: {|| if active { "nav-link active" } else { "nav-link" }},
            {label}
        }
    }
}
}

Lowercase functions get __scope injected but don’t generate a struct. Call them directly:

#![allow(unused)]
fn main() {
rsx! {
    div {
        {sidebar_link(__scope, "Home", true)}
        {sidebar_link(__scope, "Settings", false)}
    }
}
}

Making Props Reactive

Any component prop accepts a closure {|| expr} for reactive updates:

#![allow(unused)]
fn main() {
let active = Signal::new(false);
rsx! {
    Button {
        variant: {|| if active.get() { "filled" } else { "outline" }},
        onclick: move || active.update(|v| *v = !*v),
        "Toggle"
    }
}
}

When the signal changes, the component re-renders with the new prop value. For the built-in components, style: and class: props get surgical DOM updates without re-rendering the component.

_fn Props for Surgical Updates

Some components offer _fn suffix props that bypass full re-render:

#![allow(unused)]
fn main() {
let text = Signal::new(String::new());
rsx! {
    TextInput {
        value_fn: move || text.get(),           // Updates the DOM input value directly
        oninput: move |v: String| text.set(v),  // Feeds changes back to the signal
    }
}
}

value_fn updates the input’s value attribute without re-rendering the entire TextInput component. Use this for controlled inputs — without it, programmatic signal.set("") won’t clear the input visually.

Style and Class on Components

All components support style: and class: props:

#![allow(unused)]
fn main() {
Button {
    variant: "filled",
    style: "margin-top: 8px",
    class: "my-custom-button",
    onclick: || do_something(),
    "Click me"
}
}

class: is additive — it merges with the component’s own CSS classes, it doesn’t replace them. Both accept reactive closures:

#![allow(unused)]
fn main() {
Text {
    style: {|| if highlighted.get() { "background: yellow" } else { "" }},
    "Dynamic styling"
}
}

CSS Shorthand Props

All HTML elements and components support CSS shorthand props. These expand to set_style() calls:

#![allow(unused)]
fn main() {
rsx! {
    div { p: "md", m: "sm", maw: "600px",    // padding, margin, max-width
        Stack { w: "100%", h: "auto",          // width, height
            Text { px: "lg", my: "xs", "Spaced text" }  // padding-x, margin-y
        }
    }
}
}

Spacing scale values (xs, sm, md, lg, xl) auto-resolve to var(--rinch-spacing-{value}).

Keyboard Focus

Exactly one thing in a rinch window owns the keyboard at a time. The runtime calls that the focus arbiter: an <input>, a <select> with its popup open, a rich-text editor, a render surface, or a generic focusable DOM node. Moving focus tears the previous owner down before installing the next, so two widgets can never both believe they are typing.

Most of the time you never touch this — put tabindex="0" on an element and it joins the Tab order, paints :focus, and activates on Enter/Space. This page is about the other case: a custom component that takes keyboard input of its own (a code editor, a canvas grid, a keyboard-driven list) and needs to know when it gained the keyboard, when it lost it, and what keys arrived meanwhile.

Making an element focusable

#![allow(unused)]
fn main() {
rsx! {
    div { tabindex: "0", "I can be tabbed to" }
}
}

Focusability comes from the tag or from an explicit tabindex, and an explicit one always wins — the browser rule. The value is read the browser’s way too (HTML’s rules for parsing integers): leading whitespace is skipped and the number ends at the first non-digit, so " 3", "2.5" and "3abc" are all tab indices (3, 2, 3); a value with no leading digits, or past the 32-bit range, is not a tabindex at all.

<summary> is deliberately not in the set: rinch has no <details> disclosure behaviour, so a focusable <summary> would be a Tab stop that does nothing.

A focusable element that is visually hidden but laid out — opacity: 0, or position: absolute off-screen — is in the Tab order, and that is correct: .sr-only text and skip links depend on exactly that, as they do in a browser. What leaves the order is a zero-sized box, display: none, and visibility: hidden/collapse. Neither is data-rid a focusability signal — the DropdownMenu’s full-screen dismissal backdrop carries one, and so do clickable cards, table rows and list items; none of those should be Tab stops.

All five are boolean attributes: their presence is their value, so disabled, disabled="" and disabled="disabled" say the same thing. To say enabled, remove the attribute — a bool in rsx! does that for you (button { disabled: {move || busy.get()} }).

The two HTML attributes, disabled and readonly, are read by presence alone, exactly as a browser reads them: disabled="false" disables and readonly="false" is read-only, on desktop and on the web alike (issue #612). That applies to every tag the attribute reaches, so a <textarea readonly="false"> is read-only too.

rinch’s own data-disabled, data-nofocus, data-trap-focus, data-backdrop (an overlay backdrop that answers a press of any button, #1093) and data-scroll-lock-exempt (a scroll container an overlay’s scroll lock leaves alone, below) are the exception, and the only one: there the literal "false" turns the attribute off. data-nofocus, data-trap-focus and data-backdrop are read that way on both backends; data-disabled is a desktop attribute with no web reader, because the browser does not know it, and so is data-scroll-lock-exempt, because the web’s lock has nothing to exempt. Only "false" is excused — "0" is on, matching the web’s [data-nofocus="false" i] selector. Reach for the escape when you are writing the attribute by hand with set_attribute and would otherwise have to branch between writing and removing it; a bool in rsx! already removes it for you.

A disabled <fieldset> disables every control below it, which is what the element is for. HTML’s carve-out is honoured: controls inside the fieldset’s first <legend> stay enabled, so the control that re-enables the section can live there. No other tag’s disabled reaches its subtree — a disabled <button> does not disable a <span> inside it.

A press on a disabled control also paints no DOM :focus, so a focus ring never appears on something that owns no keyboard.

The same rule drives the CSS :disabled and :enabled pseudo-classes, so a control that refuses input also looks disabled — input:disabled { ... } matches, and a control below a disabled <fieldset> matches with it (the first <legend> exemption included). Styling is deliberately narrower than focus in one way: HTML defines both pseudo-classes over form elements only, so a <div data-disabled> is still removed from the Tab order but does not match :disabled — matching it would style on desktop what a browser, and therefore rinch-web, leaves alone.

A native <select> refuses the whole popup interaction, not just the last step: a disabled one opens no popup, and one disabled while its popup is already up dismisses it and commits nothing rather than firing oninput / onchange.

Disabled is re-checked at edit time, not only at focus time, so a field that goes disabled while focused — a reactive disabled prop re-rendering under a live caret — stops accepting keys immediately, and releases the keyboard, the way a browser moves focus to the body. The one thing that release does not do is fire the field’s data-onchange commit: everywhere else that commit is load-bearing (a window blur deliberately keeps the claim so alt-tabbing cannot fire it), but a control going disabled is not the user committing an edit, and browsers dispatch no change for it either.

Focus arrives three ways, and all three go through the same arbiter:

• Tab / Shift+Tab — walks the focusable elements in the browser’s sequential order, and paints the :focus-visible keyboard ring: every positive tabindex first, in ascending order, then everything at 0 or focusable by its tag, ties in DOM order — tabindex="2" before "3" before a plain <button>, wherever each sits in the document. Inside a trap_focus overlay the same order applies to the overlay’s own controls. Tab from an element that is not in that order (a clicked tabindex="-1" node, even one inside another Tab stop, or one whose box has just gone) goes to the next Tab stop after it in DOM order, and Shift+Tab to the previous one, as Chrome does. What an opening dialog focuses is still its first control in DOM order, not the first in Tab order — HTML picks it that way.

• A mouse press — claims the nearest focusable ancestor-or-self of whatever was hit, exactly as a browser does, and with any button: a right or middle press focuses too, as a browser’s mousedown does (measured in Chrome 153), and it does so before a data-oncontextmenu handler or the built-in text menu runs. Only :active is the primary button’s alone, and a press inside a focused rich-text editor leaves the keyboard with the editor whatever the button. Pointer focus does not paint the :focus-visible ring. A press that resolves to something other than the current claim holder moves the keyboard there — a nested focusable inside a focused node counts as “somewhere else” — and a press that resolves to nothing releases it.

  This applies to tabindex="-1" too — it keeps an element out of the Tab order, but it does not keep a click from focusing it, in rinch or in a browser. A control that must not steal focus from the field it sits beside — a toolbar button over a rich-text editor, a spinner next to a number input — needs data-nofocus.

• node.focus() / request_focus(node_id) — programmatic, also no ring.

Selecting a text control’s text programmatically

NodeHandle::select() and NodeHandle::set_selection_range(start, end, direction) (issue #552) are focus()’s selection counterparts, for the “a rename box opens with its name filled in and selected, so the first keystroke replaces it” shape — set_selection_range matches the DOM’s own HTMLInputElement.setSelectionRange(start, end, direction) exactly, including its units: start/end are UTF-16 code units, not bytes and not chars, so a component written once targets desktop and rinch-web with the same offsets ("🙂".encode_utf16().count() is 2, not 1). direction is SelectionDirection::Forward (the anchor is start), Backward (the anchor is end), or None (unspecified, applied the same way Forward is). select() selects the control’s whole text — exactly set_selection_range(0, <the UTF-16 length>, Forward).

#![allow(unused)]
fn main() {
// `name_input` is the captured `NodeHandle` for the rename `<input>` (built
// once, outside the handler, the way `email_field` is above).
button { onclick: move || {
    editing.set(true);   // an `if` effect mounts the rename input
    name_input.focus();
    name_input.select(); // the whole name, ready to be typed over
}, "Rename" }
}

That ordering works because touching the DOM inside a handler flushes the queued effects first: by the time name_input.focus() runs, the if effect has already mounted the input editing.set(true) asked for.

Both calls work on a control that does not hold the keyboard yet, the same way a browser’s own setSelectionRange()/select() do: the range is set immediately and simply shows up the first time the control is focused — a component does not need to call focus() first, or in any particular order relative to select()/set_selection_range(). Like focus(), both are no-ops before this handle is mounted — and, on desktop, also a no-op on a node that is not a text control (a checkbox, a <select>, a generic tabindex node): such a node never installs the state a selection would apply to, so there is nothing to apply it to or hold it for, the same divergence a browser’s own thrown-and-discarded InvalidStateError would be papering over. A mouse click that focuses a field places its own caret and clears a selection that was pre-armed for it but never applied — calling set_selection_range() on a field and then clicking somewhere else in it does what you would expect: the click wins.

A focused <select> is closed, like a browser’s: Enter, Space or Alt+Down opens its popup, and the popup then owns the keyboard until it commits or is dismissed — at which point focus returns to the closed control, so Tab carries on from there rather than restarting. (A click outside the popup is the exception: it belongs to whatever it landed on.) The pointer opens and picks with the primary button only, as in a browser: a right or middle press on the closed control does not open it, and one on an option picks nothing and leaves the list open — but a press of any button outside the list dismisses it. Everything else focusable activates the nearest ancestor-or-self data-rid on Enter/Space, which is what makes div { tabindex: "0", onclick: … } behave like a button — and what makes Space on a Checkbox’s visually hidden <input> toggle the <label> that wraps it.

The Select component (not a native <select>) behaves the same way on both backends (issue #434): its trigger keeps the focus while the list is open, ArrowUp/ArrowDown move a highlight (wrapping at the ends), Home/End jump, Enter commits the highlighted option, Escape closes without committing, Tab closes and moves on, and typing jumps to the first option whose label starts with what was typed. Space commits like Enter, except while a type-ahead prefix is being typed, when it extends it (“new y” finds New York). The highlight starts at the selected option and is announced through aria-activedescendant. A key with Ctrl, Alt or Meta held is left to the app. The list owns keys only while the focus is in the Select: if something moves the focus elsewhere while it is open (a shortcut focusing a search box, a script), the list closes and the keys go to wherever the focus went.

Taking the click without the keyboard

An editor toolbar has a problem every GUI toolkit has to answer: pressing Bold must run the command without blurring the editor, or the command reads a selection that is no longer there. Browsers answer it with preventDefault() on mousedown, which suppresses the focus change while still delivering the click.

data-nofocus is that mechanism:

#![allow(unused)]
fn main() {
rsx! {
    // The whole toolbar opts out at once — every control inside it takes its
    // click without taking the keyboard.
    div { data-nofocus: "", class: "toolbar",
        button { tabindex: "0", onclick: move || ed.command("toggleBold"), "B" }
        button { tabindex: "0", onclick: move || ed.command("toggleItalic"), "I" }
    }
    Editor { editor: ed.clone() }
}
}

The rules:

• It can be written on a component: Group { data-nofocus: "", … } or Paper { data-nofocus: "", … } puts it on the component’s root element, so a toolbar built from components needs no wrapper div (Attributes on a component).
• It is read anywhere on the pressed element’s ancestor chain, so a toolbar carries it once instead of every button in it. Put it on the toolbar, not on a big content region — a press inside it suppresses the browser’s default, which includes starting a text selection.
• It protects whatever holds the keyboard — the rich-text editor, an <input>, a render surface, another focusable node — not just the editor.
• The click still fires. data-rid dispatch is untouched.
• A text field inside a data-nofocus region still focuses normally. A link-URL field in a toolbar has to be usable, so the field’s own claim wins over the region’s opt-out.
• Boolean attribute, same rule as data-disabled: present means on whatever the value, and the explicit "false" opts out — one of rinch’s own three attributes where that escape exists.
• It works on both backends. On the web it becomes preventDefault() on the pointerdown.

Containing Tab inside an overlay

A dialog that lets Tab walk out into the page behind it is not really a dialog: the keyboard user ends up editing a form they cannot see. Modal, Drawer and Popover all take a trap_focus prop for this — true by default on the first two, false on Popover, which is not modal.

#![allow(unused)]
fn main() {
rsx! {
    Modal {
        opened_fn: move || open.get(),
        onclose: move || open.set(false),
        trap_focus: true,          // the default; `false` lets Tab out
        TextInput { placeholder: "Name" }
        Button { onclick: move || save(), "Save" }
    }
}
}

While the overlay is open its root carries data-trap-focus, and both backends read it: Tab and Shift+Tab cycle the focusable elements inside that element and wrap at its ends, instead of walking the whole document. When it closes the attribute is removed and Tab goes back to the page.

You can put the attribute on anything, not just these three components — it is a plain contract, the way data-nofocus is:

#![allow(unused)]
fn main() {
div { data-trap-focus: "", class: "command-palette",
    input { }
    button { "Run" }
}
}

The rules:

• Which trap wins. Whichever one currently holds the keyboard; if none does, the last one in document order. Nesting therefore resolves inside-out — a modal opened from a modal is rendered deeper, so later — and when the inner one closes the outer takes over with focus unmoved. z-index is not consulted, so a raised-but-earlier overlay loses to a later one; that matches the dismiss stack, which answers Escape in the same order.
• A trap with no box is not a trap. A closed Modal’s root is display: none, so it is skipped even if the attribute were left on it. Both guards are real, and the component relies on the first: it removes the attribute rather than writing "false" into it.
• Only Tab is contained. A click outside the overlay still moves focus out of it, and so does a scripted focus(). That is what a non-modal <dialog> does; a browser’s showModal() goes further and marks the rest of the page inert, so even a scripted focus behind it is refused — measured in Chrome 150. rinch has no inert and no showModal semantics, so trap_focus is a Tab rule, not a modality barrier. The backdrop’s close_on_click_outside is what an outside click is for; full modality would need inert, which rinch does not have.
• A trap with nothing focusable inside it swallows Tab. That is what containment means when there is nowhere to go — and on the web the same is true of a trap whose every control the browser refuses to focus (all of them inside a <fieldset disabled>, say): the key is consumed and focus stays put, rather than the stepping-on above running forever.
• Boolean attribute, same rule as data-nofocus: present means on whatever the value, and the explicit "false" opts out.
• Both backends, different code. Desktop starts its own focusable walk at the trap; rinch-web collects the trap’s focusable descendants with a CSS selector and calls focus() itself. The two sets are therefore computed separately and agree only as far as each is written to — desktop’s notion of focusable is already documented as broader than HTML’s in places. Trapping inherits that difference rather than creating it. On the web the browser is the authority, not rinch’s selector: a focus() it declines (a control inside a <fieldset disabled>, a tabindex it parsed differently) is stepped over rather than trusted, so an element rinch listed and the browser will not focus cannot stall the cycle.
• Some browser Tab stops are not rinch Tab stops, on either backend: contenteditable elements, <iframe>, <summary>, <audio controls> and <area href> are reachable by Tab in a browser and are in neither backend’s focusable set. An overlay containing one loses it while trapped — and outside a trap those elements are not desktop Tab stops either, so this is the focusable set’s shape rather than something trapping introduces. Give such an element an explicit tabindex="0" if it has to be reachable.

Moving focus in, and giving it back

Containment is half of what a dialog does. The other half is that opening one takes the keyboard and closing it gives it back (issue #695), and both are tied to the same trap_focus prop — trap_focus is rinch’s spelling of “this overlay is modal”, and a browser moves focus for showModal() and not for show(). An overlay that wants one without the other cannot ask for it.

On open, the overlay remembers whatever holds the keyboard — usually the button that was clicked — and then focuses inside itself:

Popover’s rule is the HTML popover API’s, not the dialog’s: an auto popover runs its focusing steps only for an element that asked. A popover that grabbed the keyboard on every open would interrupt whatever the user was typing in.

On close — and on unmount while still open, which is what if show { Modal { … } } does — the keyboard goes back to the remembered element, provided it can still take it (see below). If it cannot, the claim is released rather than left inside the overlay that has just gone. Focus the user moved out of the overlay before it closed is left alone entirely: neither released nor restored over, which is HTML’s own dialog rule.

Nesting needs no special case: an inner overlay remembers whatever the outer one focused, so closing the inner restores into the outer and closing the outer restores to the page.

Three things to know about the machinery:

• Desktop decides both a turn later. An overlay opening or closing is a class change in the same effect flush, so at that instant its children still carry the zero-size boxes their display: none ancestor gave them — and on a close, whether the remembered opener can still take the keyboard is the same kind of question about boxes. The desktop backend therefore parks the request and resolves it after the next layout, which is the turn a signal write already triggers. rinch-web answers on the spot, because the browser lays out on demand and refuses a focus() it should refuse. The browser’s focus listeners run inside these focus moves (NodeHandle::focus, an overlay opening or closing) with the document free: a blur, focusin or onchange handler of yours that they run may use any NodeHandle. The same holds when a NodeHandle verb takes the focused element out of place (see When the focused element goes).
• “Still there” means it can still take focus, not merely that it is attached. An opener that went disabled while the dialog worked, or one that lives inside an outer overlay closed before this one, is connected and unreachable; the keyboard is released instead. What is not checked is identity: a node id freed and handed to a different, attached node would still be focused — the recycled-slot hazard of issue #304, which desktop has independently of this.
• A Popover that declines the move is still a Tab trap when trap_focus is on. Focus stays where it was, and the next Tab enters the popover and is contained there. That is containment’s own rule (the last visible trap wins), not a consequence of the move policy.

The portable API this rests on is three DomDocument methods, reachable on any NodeHandle: active_element(), focus_into(policy) and restore_focus(opener). A component that builds its own overlay can use them directly. There is deliberately no bare blur(): releasing the keyboard is never the whole answer, only the fallback half of a restore, and a caller that could only blur would have to make the decision restore_focus exists to make.

Registering a focus target

register_focus_target attaches callbacks to a focusable node. It does not change who can be focused — it changes what your component is told about it.

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
fn key_grid() -> NodeHandle {
    let focused = Signal::new(false);
    let cursor = Signal::new(0usize);

    let grid = rsx! {
        div {
            tabindex: "0",
            class: {move || if focused.get() { "grid focused" } else { "grid" }},
            "cell "
            {move || cursor.get().to_string()}
        }
    };

    register_focus_target(
        &grid,
        FocusEntry::new()
            .on_focus_gained(move || focused.set(true))
            .on_focus_lost(move || focused.set(false))
            .on_key(move |k| match k.key.as_str() {
                "ArrowRight" => {
                    cursor.update(|c| *c += 1);
                    true // consumed
                }
                "ArrowLeft" => {
                    cursor.update(|c| *c = c.saturating_sub(1));
                    true
                }
                _ => false, // let the runtime have it
            }),
    );

    grid
}
}

Every callback is optional; FocusEntry::new() with none of them is legal and registers the node without asking for anything back.

What fires, and when

Presses and releases

k.kind is KeyEventKind::Down or Up; k.is_down() / k.is_up() are the shorthands. OS auto-repeat arrives as Down, and KeyEventData does not yet distinguish it from a fresh press. The platform event does, since issue #463 — PlatformEvent::KeyDown carries a three-state KeyRepeat (Fresh / Repeat / Unknown), filled in by winit on desktop and by repeat_count() on Android, and that is what the runtime’s own once-per-press Enter/Space activation reads. Surfacing it to on_key needs the same three-state answer (a plain bool would report a held key as fresh wherever a backend cannot see, which is the divergence a document-level hook exists to avoid) and so needs a home for the type that rinch-core can reach. Tracked as #797.

A press and its release are spelled by the same rule, from the same fields, so pairing them by k.key works by construction — which is what “is W still held” needs. Concretely: the platform event’s logical_key carries the full layout-produced KeyboardEvent.key value on the press and the release alike, case included. On AZERTY, the key labelled A is "a" on the way down and on the way up, not "a" down and "q" up; Shift+A is "A" both ways, and Shift+1 is "!" both ways — the same strings a browser reports, so the same consumer code works against rinch-web. Case is identity, so a Shift pressed mid-hold changes what the eventual release spells ("w" down, "W" up) — exactly as in a browser; track held keys by the physical k.code, or fold case at the comparison, if that matters to you.

On Android a hardware key’s release is spelled as its press was reported, whatever happened in between: "W" down with Shift held comes up as "W" even if Shift went up first, and a letter that combined with a dead key ("é") comes up as that same string. A release whose press the app never saw (a key already held when the app came to the front) is spelled from the layout with the modifiers held at the release. An auto-repeat is still spelled from what it types: after a dead key the press is "é", the repeats are "e" and the release is "é", so track held keys by k.code there too (#1418). Text the soft keyboard commits goes through InputConnection and has no key events; a raw key event an IME sends (sendKeyEvent, typically Backspace and Enter) comes through the same translation as a hardware key, release included.

Two things to know:

• A release is delivered to whoever holds the claim at release time. A focus change mid-chord can therefore hand a target a release it never saw pressed — treat on_focus_lost as “everything is up” if you track held keys.
• A release’s return value is ignored. There is nothing downstream of it to suppress, and the runtime’s own release work (clearing the Enter/Space activation latch) must happen whatever a handler thinks — otherwise a consumed release would strand the latch and swallow the next press.

on_key returns true to consume the key. A consumed key stops there: no Tab navigation, no Enter/Space activation, no DevTools shortcut. Returning false (or not setting on_key at all) leaves every one of those working exactly as it would for an unregistered node, so registering costs you nothing you did not ask for.

k.key is spelled the way the browser spells KeyboardEvent.key, on desktop as on rinch-web (which forwards event.key() unchanged), and k.code the way it spells KeyboardEvent.code. That includes the spacebar: k.key is " " and k.code is "Space", and k.is_space() answers it on every backend. (Desktop reported k.key == "Space" until issue #1161; code that matched that should match k.code == "Space" or k.is_space() instead.) The key is resolved in four steps:

1. A key with a fixed spelling wins over the text it would insert — "ArrowLeft", "Enter", "Escape", "Tab", "PageUp", "F1"…"F12", "Shift", and the spacebar’s " ", so a release (no text) and a chord (text suppressed) spell it like a plain press.
2. Otherwise the inserted text wins, so a non-QWERTY layout reports the letter actually typed rather than the physical QWERTY position: the AZERTY key at the QWERTY-Q position is k.key == "a", and Shift+A is "A".
3. Otherwise the layout’s key value. A modifier suppresses the inserted text, but the layout-produced KeyboardEvent.key value survives it — so a chord keeps step 2’s promise: on AZERTY, Ctrl plus the key labelled A is k.key == "a" (and Ctrl+Shift makes it "A" — the value is case-accurate), the same letter the editor’s own keymap acts on. It also names shifted punctuation (Ctrl+Shift+1 is "!" where the layout puts one), a dead key ("Dead"), and keys rinch has no KeyCode of its own for but the platform names — CapsLock, media keys.
4. Otherwise the physical key’s US-layout character, for events that carry no layout value at all (the debug channel, injected and embedded events): Ctrl+S is "s", Cmd+1 is "1", Ctrl+- is "-".

k.code is always the physical key ("KeyS", "Digit1").

Two things to know. k.key is case-accurate, browser-style — Ctrl+S is "s", Ctrl+Shift+S is "S" — and a press and its release spell alike (both read the modifier state of their own moment), which is what pairing them by k.key relies on. And a key bound to a native menu accelerator is consumed by the menu before the document sees it — but only the press: the release still arrives (the menu consumes nothing on the way up), so it is one more source of a release with no visible press.

The one key that still reports nothing is one rinch has no KeyCode for (k.code == "Other") arriving with no layout value and no inserted text. A real keystroke carries the layout value (unless the platform itself cannot identify the key), so this is mostly the injected regime: the debug channel names only single characters and the named keys, so an injected Ctrl+/ has no spelling to fall back to and never reaches the hook. From the keyboard those keys are fine: Ctrl+/ reports "/" through step 3, and unmodified the character arrives as the inserted text.

Both focus callbacks run after the transition is complete: the arbiter and the DOM :focus state are already installed, so a callback may re-enter the runtime freely — move focus again, mutate the DOM, save a document.

Enter and Space

A focused node that does not consume Enter/Space gets the runtime’s default: they dispatch the onclick handler of the nearest ancestor-or-self that has one, once per physical press. That is what makes div { tabindex: "0", onclick: … } behave like a button. If your widget wants Enter for itself, consume it in on_key.

Unmounting

Unmounting the component deregisters silently. on_focus_lost does not fire, even if the node held the keyboard at the time — by then the component’s scope has been disposed and its signals freed, and calling back into it would panic. Do your teardown in the component’s own cleanup path, not in on_focus_lost.

The arbiter notices the vanished target on its next key dispatch and drops the claim, so keys fall back to the global handlers rather than disappearing.

Window focus

When the window loses OS focus, the focused widget keeps its claim — it is only notified, and notified again when the window comes back. This is browser behaviour, and it is deliberate: releasing focus on every alt-tab would fire onchange on whatever field the user was typing in each time they switched windows.

So the pair to expect is on_focus_lost on window blur, on_focus_gained on window refocus, with no key routing in between. Use it to hide a caret and idle a blink timer. While the window is blurred, rinch reports the OS IME disabled, so a candidate box follows the window that actually has the keyboard.

The runtime does the same for its own caret: the rich-text editor’s caret stops blinking while the window is blurred and shows solid, resuming from the solid phase on refocus. The blink is the event loop’s only timed wake, so a backgrounded rinch app now idles completely instead of waking twice a second to animate a caret nobody can type into. The selection highlight is unaffected — the claim is still held, so a blurred window still shows what is selected.

IME

A widget with its own text model can take IME composition — CJK conversion, autocorrect, dead keys, a swipe keyboard — by registering on_ime. That is what declares the target a text target: the runtime then switches the platform input method on while the widget holds the keyboard, and routes every one of the five portable ImeEvent variants to it — the same contract the rich-text editor and a built-in <input> consume. A registration without on_ime turns nothing on, so a focusable card or a custom checkbox never pops a candidate window.

#![allow(unused)]
fn main() {
use rinch::prelude::*;

register_focus_target(
    &node,
    FocusEntry::new()
        // Where the OS puts its candidate box, in logical window pixels.
        .caret_rect(move || Some(caret.get()))
        .on_ime(move |e| match e {
            // A transient overlay you render and discard — never document text.
            ImeEvent::Preedit { text, cursor } => model.set_preedit(text, *cursor),
            // The conversion the user chose. Insert it as one edit.
            ImeEvent::Commit(text) => model.insert(text),
            // Composition ended with nothing committed.
            ImeEvent::Disabled => model.clear_preedit(),
            _ => {}
        })
        .on_focus_lost(move || model.clear_preedit()),
);
}

caret_rect is (x, y, w, h) in logical window space — CSS pixels from the window’s top-left, the same space layout bounds are reported in. Do not pre-multiply by the display scale factor; the shell hands the rect to the platform as a logical size and the platform scales it. Return None when there is no caret; placement then falls back to the platform’s default. The provider is polled every time rinch reconciles the window’s IME state (once per event-loop iteration), so the candidate box follows the caret with nothing to notify — keep it cheap, and do not mutate the DOM from it.

Two things the runtime deliberately does not do:

• It never fabricates an event. It holds no preedit on your behalf, so a focus change is not an ImeEvent::Disabled. When another target claims the keyboard the window’s input method may stay enabled throughout and nothing ends your composition — clear the preedit in on_focus_lost, as above.
• ImeEvent::DeleteSurrounding is inert on desktop today. Rinch asks winit only for cursor-area support, so no desktop backend advertises surrounding-text and the variant never arrives. Android’s InputConnection does send it.

Everything under Window focus applies: while the window is blurred, IME reports disabled and no composition is routed, but the claim — and on_ime with it — comes back on refocus.

The dismiss stack

Escape is the one key an overlay has to answer without holding the keyboard: a Modal is dismissed by Escape whether the focus is on a field inside it, on the modal itself, or nowhere at all. That is a different job from both APIs above, and it has its own registry (issue #474).

#![allow(unused)]
fn main() {
use rinch::prelude::*;

let opened = Signal::new(true);
let handle = push_dismiss_handler(root.doc_key(), move || {
    if opened.get() {
        opened.set(false);
        true            // consumed: the key stops here
    } else {
        false           // not open: pass it to the overlay below, then the app
    }
});
__scope.on_cleanup(move || drop(handle));
}

• It is a stack, last in first out. The most recently registered handler is asked first, so two nested modals close innermost-first. The first handler that returns true consumes the key and the ones beneath it are never asked.
• Answer false while you are closed. An overlay usually stays mounted when it closes — opened_fn only toggles a class — so the check belongs inside the handler, at dispatch time, not at registration. A handler that always returns true swallows Escape for the rest of the session.
• It is released on unmount, twice over: the DismissHandle releases it when it drops, and an entry whose owning scope has been disposed is dropped as the scan passes it rather than run (issue #183 — its captured signals are already freed).
• It is scoped per document, on desktop and embed. Two RinchContexts on one thread do not answer each other’s Escape (issues #134, #139). On rinch-web there is nothing to scope and nothing doing the scoping: a page dispatches with no document marked, and the rule is deliberately permissive when either side is unmarked, so every handler is reached. The explicit key you pass at registration is what carries the distinction where one exists.
• Both backends, no branch. Dispatch lives inside dispatch_keyboard_event, which desktop calls ahead of the focus arbiter and rinch-web calls from its document keydown listener.

Some things are dispatched before the stack and will take Escape from it: a set_keyboard_interceptor that consumes the key, and an in-progress drag, which Escape cancels. Both apply on either backend. rinch-web has one more — a focused RenderSurface swallows every key there, where on desktop a surface is routed by the arbiter, i.e. after the stack. That asymmetry is older than the stack (the interceptor already had it) and is not something this API changed.

Register at mount, or at open

The snippet above registers once, when the overlay mounts, and answers false while it is closed. That is what Modal, Drawer and Popover do, and it is right for an overlay whose open state arrives as a prop: render runs once, so there is no later moment to hang a registration on.

It is the wrong choice for an overlay statically nested inside another one. A component renders after its children, so Modal { ColorInput { … } } pushes the input’s entry first and the modal’s on top of it — and the stack is LIFO, so the modal answers Escape while the colour picker is the thing on screen.

An overlay that owns its open state avoids that by pushing when it opens and releasing when it closes. Opening happens after every ancestor has mounted, so LIFO puts the entry where the user expects it with no precedence rule anywhere. This is what the native <select> popup does (issue #671) and what ColorInput’s dropdown does (issue #465); in a component, rinch_components::overlay_dismiss::arm_close_on_escape_while_open is that policy written out. Such a handler consumes unconditionally — it exists only while the overlay is open, so it has no closed state to decline in — and the release must cover unmount-while-open as well as close.

Modal, Drawer and Popover already do all of this for you through their close_on_escape prop — reach for push_dismiss_handler when you are building an overlay of your own. Prefer it over set_keyboard_interceptor for Escape: the interceptor is a single slot per document, so a second overlay registering there silently disables the first, and when it unmounts it clears the slot rather than restoring what it displaced.

A popup that owns every key while it is open and focused

#![allow(unused)]
fn main() {
let handle = push_key_handler(
    &root,                                   // the owner: the popup's component root
    move |k: &KeyEventData| k.key == "ArrowDown" && { step(); true },
    move || opened.set(false),               // focus left the owner
);
}

push_key_handler puts an entry on the same stack that is offered every key press (never a release), ahead of the Escape scan; true consumes the key, which on rinch-web also preventDefaults it. It is for a popup whose focus stays on something outside the popup’s list — the Select component’s option list, whose combobox trigger keeps the focus while the arrows move a highlight.

It is offered a key only while the focused element is the owner or inside it. A field focused while the popup is open — by a shortcut, a script, an autofocus — keeps its own keys, and on the web a key typed outside the rinch mount is never touched. When focus moves and is no longer inside the owner, the entry’s on_focus_leave runs (the backends report every focus move), which is where a listbox closes; pass || {} if yours should stay open.

Register it at open and release it at close and on unmount — rinch_components::overlay_dismiss::arm_keys_while_open is that policy. Decline Escape in it and give Escape its own dismiss entry, so “which overlay is on top” stays one question.

When the focused element goes

On the web, a NodeHandle verb that removes or moves the focused element, or an element around it, lets the focus go first: remove, discard, remove_child, replace_with (for either node), set_inner_html and set_text over it, and append_child / insert_before / insert_after of a node that is already in the document. That covers a reactive if hiding a panel, a keyed for moving a row, and unmounting a root. The focused element is blurred, with the document free, and then the node goes. So:

• a key entry whose owner is in the part that goes gets its on_focus_leave (an open Select in a hidden panel closes). Chrome fires the focus events by itself when a focused node is removed; Firefox fires nothing, and rinch’s own blur() makes the two agree;
• a modified field in it gets its onchange only while its handler is still alive: a field removed directly, or a captured one a branch hides (if show { {field} }). A field the hidden branch built (if show { input { onchange: … } }) has had its handlers freed before it goes, and commits nothing;
• a handler those events run may use any NodeHandle, and the node it is about is still where it was. A handler that keeps putting the focus back inside the part that goes is stopped the fourth time: that part is held inert for the last blur, so the focus cannot return to it;
• a verb the browser refuses (an insert_before whose reference is not a child of the parent, a node appended into itself) moves nothing and keeps the focus;
• a node moved inside the document keeps the focus where the browser has Node.moveBefore (Chrome 133 and later; check your other target browsers), as it always has on desktop. append_child, insert_before and insert_after of a node that is already in the document — a keyed for moving a row — are then that call: no focus event fires, an open Select in the row stays open and an <iframe> in it is not reloaded (measured in Chrome 153 and Firefox 157); a scroller in it keeps its offset in Chrome and is reset to the top in Firefox 157. A running CSS animation or transition in the row carries on and an IME composition in its <input> is not ended (measured in Chrome 153). One exception to “keeps the focus”: a node moved under a parent where it cannot be focused (display: none, hidden, inert, visibility: hidden, a disabled <fieldset>, a closed <details> or <dialog>) keeps it through the move and the browser blurs it afterwards, so a key entry’s on_focus_leave runs then, once. A page’s own moveBefore polyfill written over insertBefore is recognised and not used. In a browser without the method the move is a removal and an insertion, the moved node loses the focus and the list above applies; call focus() on it again after the move if it must keep the keyboard there. A move into or out of a detached subtree, and replace_with, take that path in every browser.

Three attribute writes can cost the focused element its focus in place: hidden on it, and removing the tabindex or contenteditable that made it focusable (Chrome blurs inside the write; disabled, inert and display: none fire nothing there). set_attribute, write_attribute and remove_attribute make those writes with the document free too. A tabindex write that leaves the element focusable (a roving tabindex) keeps the focus.

Not covered: UpdateBatch::apply, which is handed the document already borrowed, and any other code that calls a DomDocument method directly. A SetText or attribute write there that unfocuses an element still runs the browser’s listeners under that borrow.

Locking the page behind an overlay

The other thing an open dialog owes the page behind it is stillness. Modal and Drawer do it for you through their lock_scroll prop (default on, issue #474); a custom overlay takes the same lock on its own root:

#![allow(unused)]
fn main() {
// On open — the node matters: it names the subtree that stays scrollable.
root.set_scroll_locked(true);
// On close, and again on unmount, or the page never scrolls again.
root.set_scroll_locked(false);
}

• Locks are counted. Two overlays open and the inner one closing leaves the page locked. Every true must be matched by exactly one false.
• Release it on unmount as well as on close. An overlay can be taken out of the tree while still open, which is what if show { Modal { .. } } does. The effect that would have unlocked it never runs again, so the release belongs in an on_cleanup too. Modal and Drawer already do both.
• The two backends do different things, and this is the one overlay behaviour where that is visible. Desktop refuses the gesture: a wheel (which is what a touch scroll arrives as too) and a scrollbar-thumb press are rejected for any container that is not inside a locking overlay, so the dialog’s own overflow: auto body still scrolls. rinch-web sets overflow: hidden on the real <html>, because rinch cannot gate the browser’s own wheel.
• So web also removes the page’s scrollbar and desktop does not. A web page with a classic (non-overlay) scrollbar shifts sideways when an overlay opens. Desktop’s bars are overlays with no gutter, and a locked page’s bar stays painted — visible, and inert.
• Input only. Programmatic scrolling (set_scroll_top, a list the app scrolls itself) is untouched on both.
• A drag already in flight ends when a lock arrives. A scrollbar thumb the user is holding when something else opens a dialog is released rather than left to go on scrolling the page.
• In island mode the lock is still the whole page. There is one <html>, so a rinch Modal inside an island freezes the host page, not just rinch’s own region — one lock, counted across every island on the page. That is what every web overlay library does, but an embedder should know it before shipping a dialog into someone else’s page.
• On iOS Safari, overflow: hidden on <html> is not always enough to stop rubber-band scrolling; libraries there add a position: fixed body trick. We have not tested it and rinch does not do it, so treat the web half as “the page stops scrolling in every browser we have measured” rather than as universal.

Do not reach for RenderScope::body_handle() and set overflow: hidden there: on the web that handle is <div id="rinch-body">, a descendant of the real <body>, and styling it does not stop the page scrolling.

A scroll container outside the overlay: data-scroll-lock-exempt

On desktop the lock refuses every scroll container that is not inside a locking overlay’s root. That is the page behind the overlay, which is the point, but it is also any scroll container of yours that sits outside the overlay in the tree and is still meant to be used while it is open: a popup portalled to <body>, a menu hanging from window chrome, a panel that paints over the dialog. Mark it:

#![allow(unused)]
fn main() {
div {
    class: "my-popup-list",
    style: "max-height: 300px; overflow-y: auto;",
    data-scroll-lock-exempt: "",
    // ...
}
}

• The attribute exempts its subtree, so a popup carries it once on its root and every scroller inside scrolls. On a component, write it the same way: a hyphenated attribute goes on the component’s root element.
• It exempts everything under the marked node and nothing else: an unmarked scroll container outside the overlay stays locked.
• It cannot unlock the page. A mark on a node that contains the locking overlay — <body>, an app root, a wrapper around the dialog — is ignored, so the page behind the overlay stays locked whatever its ancestors carry. Mark the popup, not something above it.
• It is not checked against paint order. A marked scroller that the overlay covers also scrolls when the wheel is over it (the pointer is on the backdrop, and the wheel finds the scroller underneath). Mark only what is shown above the overlay.
• It is one of rinch’s data- boolean attributes: on unless its value is "false", and a reactive data-scroll-lock-exempt: {|| flag.get()} removes it when flag is false. rinch_core::events::SCROLL_LOCK_EXEMPT_ATTRIBUTE is the name, for code that writes it through a NodeHandle.
• There is nothing to release: the exemption goes with the node.
• Desktop only, and the web needs none. The web’s lock is overflow: hidden on <html>, which stops the page and leaves every scroll container inside it scrolling, so the attribute is inert there.

The DOM menu bar (the in-app bar of a Linux window) marks its own dropdowns and submenu flyouts, so a menu too long for the window scrolls while a dialog is open (issue #701). The runtime’s native <select> popup, which it appends to <body>, is exempt the same way through the runtime’s own list (NodeTree::push_scroll_lock_exempt); you do not need to mark a <select>.

Undo and redo in a text field

A focused <input> or <textarea> undoes with Ctrl+Z and redoes with Ctrl+Shift+Z or Ctrl+Y (Cmd on macOS) on desktop, as a browser field does on the web (issue #288).

• oninput fires with the restored text, exactly as for a keystroke, so a controlled field’s signal follows the undo. The eventual onchange compares what the field shows at the commit with what it showed when focus arrived, so undoing back to the starting text commits nothing.
• A readonly field refuses both, like every other text-changing command, and a field that goes disabled while focused releases the keyboard instead.
• One key press is one undo step. Each typed character is its own step — desktop does not merge a run of typing into one the way a browser does. Typing over a selection is one step: the selected text comes back whole.
• A keystroke and the rewrite its own oninput made are one step. A normalizing field (upper-casing, say) therefore undoes to the text before the keystroke, never to the raw text the handler is about to rewrite again. A keystroke the handler rejects — writes the field back to what it showed, as a digits-only filter does with a letter — leaves no step at all. This is where desktop and the web differ: a browser treats that rewrite as a script write to .value and drops the field’s whole undo history, so a normalizing field has no undo on the web.
• Any other write to the field’s value clears its undo and redo history — a value_fn reset, a clear after onsubmit, a write from a timer or another handler. It is the app’s change, not the user’s, so Ctrl+Z cannot bring back text the app replaced. That is what a browser does for a script write to .value, so for a write made outside a keystroke desktop and the web agree.
• Not with Alt, and not mid-composition. Ctrl+Alt+Z is left alone (it is AltGr on Windows, which types a character on some layouts), and Ctrl+Z does nothing while an input method is showing a composition.
• The built-in right-click menu (below) has no Undo row; the chords are the way in.

Right-clicking a text field

A right press on a text target — an <input> of a text-like type (text, search, url, tel, email, password, number, or no type at all), a <textarea>, or the rich-text Editor — opens a built-in Cut / Copy / Paste / Select all menu on desktop (issue #813). It is a menu the runtime draws itself, as a DOM overlay in the same shape as the native <select> popup, so it is the same on Linux, macOS and Windows, works in a borderless or transparent window, and follows the theme’s palette when there is one.

• A data-oncontextmenu handler still wins. If the pressed node or any ancestor carries a live one, it runs exactly as before and the built-in menu stays shut. Attach one to a field to give it a menu of your own.
• Each item runs the code its chord runs — Ctrl+X / Ctrl+C / Ctrl+V / Ctrl+A (Cmd on macOS), including the editor’s asynchronous, anchored paste. Today that is literally one function per operation on both paths, and a fixture pins item and chord to the same value, selection and clipboard; nothing in the code enforces it, so a check added to one path alone would drift the other silently.
• Enabled states follow the field. Cut and Copy need a non-empty selection; a readonly field greys Cut and Paste; a password field greys Cut and Copy; Select all needs content; a disabled field takes no focus and gets no menu. Without the clipboard feature Cut, Copy and Paste are all greyed — there is no clipboard for them to reach, and an enabled Cut would delete text it never copied. Paste is not decided by reading the clipboard — a read can block for up to four seconds on X11 — so it stays enabled over an empty clipboard, where a native menu would grey it out; pasting nothing does nothing.
• The press places the caret like a native editor’s. Outside the current selection it moves the caret to the press point; inside it, the selection is kept, so Cut and Copy act on what you selected.
• The field keeps the keyboard while the menu is open and after an item runs. Up / Down / Home / End move over the enabled rows (wrapping), Enter or Space runs the highlighted one, and Escape closes through the dismiss stack — the menu pushes its entry at open time, above an enclosing Modal’s, and releases it on close. Any press outside the menu closes it without acting and is swallowed; a wheel closes it too.
• It goes with its target. The menu closes when the field’s claim moves (a click elsewhere, a programmatic focus), when the window loses focus, and when the field leaves the document — the last is checked on every event rather than waiting for a second event that might never arrive.

On rinch-web the browser’s own menu covers text fields and the runtime draws none (issue #812). On Android a long press in a field arrives as the same right press; which presentation the Android shell uses is that platform’s half of #813 — the runtime exposes the state and the actions (RinchApp::text_edit_state, perform_text_edit) for a native toolbar to build on, with this menu as the fallback.

Where this does not apply

• The browser backend (rinch-web). There is no arbiter there because the browser is one: register_focus_target is a desktop / Android / embed API. On web, give the element a real tabindex and use the DOM’s own focus, blur and keydown events. data-trap-focus is the exception — it works on both backends, because it is a contract the backend reads rather than a registration against the arbiter.
• The document-level keyboard hook. set_keyboard_interceptor is a capture-phase hook for the whole document, dispatched before the arbiter and regardless of focus. It is for global shortcuts; on_key is for a focused widget. They are different jobs and both still exist. It routes per document (issue #340): a hook registered while a document’s code is running — its event dispatch, its mount (issue #295), or an effect it owns, wherever that effect happens to be flushed — intercepts only that document’s keys, and one registered from main is the thread-global fallback that intercepts for every document without its own — so two windows that each register at mount or from their own event handling no longer clobber each other. Registrations made outside any document (from main, a timer or run_on_main_thread closure armed there, or on rinch-web, which marks no document) still share the single fallback slot, last-wins. A timer, run_on_main_thread closure or http/ws completion armed inside a document runs as that document’s code (issue #963), so what it registers or clears is that document’s. A document is served whichever of its own hook and the fallback was registered later, so a single-window app keeps last-registration-wins wherever it registers from; clear_keyboard_interceptor from outside any document clears every entry, and from inside one leaves that document with none. The cost with several documents on one thread (two embedded contexts, an app and its DevTools): code outside any document — main, a timer armed there, a closure queued from a worker thread, a native menu or tray callback — cannot say which document it belongs to, so its registration overrides every document’s own hook and its clear wipes every document’s. Registrations made inside documents stay isolated from each other. Its lifetime does match the arbiter’s, though: registering it during a render releases it when that component unmounts, exactly as a FocusEntry is deregistered (issue #183). Registering it from main keeps app lifetime. For Escape, use the dismiss stack instead — one slot cannot nest.
• IME on the browser backend. on_ime is desktop / Android / embed only, like the rest of this API. On web, attach compositionstart / compositionupdate / compositionend to your element yourself — the browser delivers composition to whatever it considers focused.
• The Android soft keyboard. A registered target participates in desktop IME, but does not yet raise Android’s on-screen keyboard: the shell still watches for a focused <input> or the rich-text editor.
• Modality. Tab is contained by an open Modal or Drawer — see Containing Tab inside an overlay — but a click still reaches controls behind the backdrop wherever the backdrop itself does not cover them, and a click or a scripted focus() outside an overlay moves focus out of it. A browser’s showModal() refuses both, because it marks the rest of the page inert; rinch has no inert and models no showModal. DropdownMenu has no trap_focus prop and contains nothing.

Components

Rinch provides a comprehensive component library with 60+ styled, themeable UI components inspired by Mantine. Enable with the components feature (which also enables theme):

[dependencies]
rinch = { workspace = true, features = ["desktop", "components", "theme"] }

Note: The workspace dependency uses default-features = false, so features must be listed explicitly:

• "desktop" — enables run(), window management, and the software renderer (tiny-skia)
• "gpu" — (optional) adds GPU rendering via Vello/wgpu beside the software renderer, chosen at run time
• "components" — enables the component library (Button, TextInput, Stack, etc.)
• "theme" — enables automatic theme CSS loading and CSS variables

Using Components

Components are used directly in RSX with a declarative syntax:

use rinch::prelude::*;

#[component]
fn app() -> NodeHandle {
    rsx! {
        Stack { gap: "md",
            Title { order: 1, "Welcome" }
            Text { size: "lg", color: "dimmed", "Get started with Rinch components." }

            Group { gap: "sm",
                Button { variant: "filled", "Get Started" }
                Button { variant: "outline", "Learn More" }
            }
        }
    }
}

fn main() {
    let theme = ThemeProviderProps {
        primary_color: Some("cyan".into()),
        ..Default::default()
    };
    App::new(app)
        .title("My App")
        .size(800, 600)
        .theme(theme)
        .run();
}

Component Categories

Layout Components

#![allow(unused)]
fn main() {
// Stack - vertical layout
Stack { gap: "md",
    Text { "Item 1" }
    Text { "Item 2" }
}

// Group - horizontal layout
Group { gap: "sm", justify: "space-between",
    Button { "Left" }
    Button { "Right" }
}

// Center content
Center {
    Loader {}
}

// Add spacing
Space { h: "xl" }  // height
Space { w: "md" }  // width
}

Buttons

#![allow(unused)]
fn main() {
// Button variants
Button { variant: "filled", "Primary" }
Button { variant: "outline", "Secondary" }
Button { variant: "light", "Light" }
Button { variant: "subtle", "Subtle" }

// Button sizes
Button { size: "xs", "Extra Small" }
Button { size: "sm", "Small" }
Button { size: "md", "Medium" }  // default
Button { size: "lg", "Large" }
Button { size: "xl", "Extra Large" }

// Button colors
Button { color: "red", "Delete" }
Button { color: "green", "Success" }

// Button states
Button { disabled: true, "Disabled" }
Button { loading: true, "Loading..." }
Button { full_width: true, "Full Width" }

// With click handler
Button { onclick: move || count.update(|n| *n += 1), "Click Me" }

// ActionIcon - for icon buttons
ActionIcon { variant: "filled", "+" }
ActionIcon { size: "lg", variant: "light", "?" }

// CloseButton
CloseButton { onclick: move || modal_open.set(false) }
}

Form Inputs

#![allow(unused)]
fn main() {
// TextInput with label and description
TextInput {
    label: "Email",
    placeholder: "you@example.com",
    description: "We'll never share your email."
}

// TextInput with error
TextInput {
    label: "Password",
    input_type: "password",
    error: "Password must be at least 8 characters"
}

// Controlled input (value_fn + oninput)
let input_text = Signal::new(String::new());
TextInput {
    placeholder: "Type here...",
    value_fn: move || input_text.get(),
    oninput: move |value: String| input_text.set(value),
}

// TextInput with onsubmit (fires on Enter key)
let search = Signal::new(String::new());
TextInput {
    placeholder: "Search...",
    value_fn: move || search.get(),
    oninput: move |value: String| search.set(value),
    onsubmit: move || println!("Searching: {}", search.get()),
}

// PasswordInput with visibility toggle
PasswordInput {
    label: "Password",
    placeholder: "Enter password"
}

// NumberInput — uncontrolled: the component owns the number, so the
// +/- steppers step, clamp to [min, max] and format it themselves,
// reporting each written value through `oninput` (#501)
NumberInput {
    label: "Quantity",
    value: Some(1.0),
    min: Some(0.0),
    step: Some(1.0)
}

// NumberInput — controlled: pass `value_fn` and the signal becomes the
// field's single write path; the steppers stay callback-only, so write
// the signal in `onincrement`/`ondecrement` (#264)
let quantity = Signal::new(1.0);
NumberInput {
    label: "Quantity",
    value_fn: move || quantity.get().to_string(),
    min: Some(0.0),
    step: Some(1.0),
    onincrement: move || quantity.update(|v| *v += 1.0),
    ondecrement: move || quantity.update(|v| *v = (*v - 1.0).max(0.0))
}

// Textarea
Textarea {
    label: "Description",
    placeholder: "Enter your message...",
    min_rows: 4          // visible rows; defaults to 2
}

// Checkbox
let checked = Signal::new(false);
Checkbox {
    label: "Accept terms",
    checked: checked.get(),
    onchange: move || checked.update(|v| *v = !*v)
}

// Switch
Switch {
    label: "Enable notifications",
    checked: enabled.get(),
    onchange: move || enabled.update(|v| *v = !*v)
}

// Select
Select {
    label: "Country",
    placeholder: "Select a country",
    option { value: "us", "United States" }
    option { value: "uk", "United Kingdom" }
    option { value: "ca", "Canada" }
}

// RadioGroup
RadioGroup { label: "Plan",
    Radio { value: "free", label: "Free" }
    Radio { value: "pro", label: "Pro" }
    Radio { value: "enterprise", label: "Enterprise" }
}

// Slider
Slider { color: "cyan" }

// Fieldset
Fieldset { legend: "Personal Info",
    Stack { gap: "sm",
        TextInput { placeholder: "First name" }
        TextInput { placeholder: "Last name" }
    }
}
}

Typography

// Text sizes and weights
Text { size: "lg", weight: "bold", "Large Bold Text" }
Text { size: "sm", color: "dimmed", "Small dimmed text" }

// Titles (h1-h6)
Title { order: 1, "Main Heading" }
Title { order: 2, "Subheading" }
Title { order: 3, "Section Title" }

// Code
Text { "Run " Code { "npm install" } " to install." }
Code { block: true, "fn main() {\n    println!(\"Hello!\");\n}" }

// Keyboard keys
Group { gap: "xs",
    Kbd { "Ctrl" }
    Text { "+" }
    Kbd { "C" }
}

// Anchor (link)
Anchor { href: "https://example.com", "Visit site" }
Anchor { href: "#", underline: true, "Always underlined" }

// Blockquote
Blockquote { cite: "— Albert Einstein",
    "Imagination is more important than knowledge."
}

// Mark (highlight)
Text { "This has " Mark { "marked text" } " inline." }

// Highlight (search highlighting)
Highlight { highlight: "quick brown", "The quick brown fox jumps" }

Feedback

#![allow(unused)]
fn main() {
// Alert variants
Alert { color: "blue", title: "Info", "This is informational." }
Alert { color: "green", title: "Success", "Operation completed!" }
Alert { color: "yellow", title: "Warning", "Please review." }
Alert { color: "red", title: "Error", "Something went wrong." }

Alert { variant: "filled", color: "blue", "Filled style" }
Alert { variant: "light", color: "blue", "Light style" }
Alert { variant: "outline", color: "blue", "Outline style" }

// Loader
Loader {}
Loader { size: "lg", color: "cyan" }

// Progress
Progress { color: "blue" }
Progress { color: "green", striped: true }
Progress { striped: true, animated: true }

// Skeleton (loading placeholders)
Skeleton { height: "12px", width: "80%" }
Skeleton { height: "40px", width: "40px", circle: true }

// Tooltip
Tooltip { label: "This is a tooltip!",
    Button { "Hover me" }
}
Tooltip { label: "Top tooltip", position: "top",
    Button { "Top" }
}
}

Data Display

#![allow(unused)]
fn main() {
// Avatar
Avatar { name: "John Doe" }  // Shows "JD"
Avatar { size: "lg", color: "cyan", name: "Jane Smith" }
Avatar { src: "https://example.com/photo.jpg" }

// Badge
Badge { "New" }
Badge { variant: "light", color: "green", "Active" }
Badge { variant: "outline", color: "red", "Error" }
Badge { variant: "dot", "With dot" }

// Card
Card { shadow: "sm",
    CardSection { with_border: true,
        div { style: "padding: var(--rinch-spacing-sm);",
            Text { weight: "bold", "Card Title" }
        }
    }
    div { style: "padding: var(--rinch-spacing-md);",
        Text { "Card content goes here." }
    }
}

// Paper
Paper { shadow: "md", p: "lg",
    "Simple paper container"
}
Paper { shadow: "sm", p: "md", with_border: true,
    "Paper with border"
}

// Divider
Divider {}
Divider { label: "OR" }

// Image (local file or URL with image-network feature)
Image {
    src: "photo.png",
    width: "200",
    height: "150",
    fit: "cover",
    radius: "md",
}

// Avatar with image
Avatar { src: "photo.png", size: "lg" }

// List
List {
    ListItem { "First item" }
    ListItem { "Second item" }
    ListItem { "Third item" }
}
}

Navigation

#![allow(unused)]
fn main() {
// Tabs
Tabs {
    TabsList {
        Tab { value: "gallery", "Gallery" }
        Tab { value: "messages", "Messages" }
        Tab { value: "settings", "Settings" }
    }
    TabsPanel { value: "gallery",
        Text { "Gallery content" }
    }
    TabsPanel { value: "messages",
        Text { "Messages content" }
    }
}

// Tab variants
Tabs { variant: "outline", /* ... */ }
Tabs { variant: "pills", /* ... */ }

// Accordion
Accordion {
    AccordionItem { value: "item-1",
        AccordionControl { "What is Rinch?" }
        AccordionPanel {
            Text { "A reactive GUI framework for Rust." }
        }
    }
    AccordionItem { value: "item-2",
        AccordionControl { "How do I get started?" }
        AccordionPanel {
            Text { "Add rinch to your Cargo.toml!" }
        }
    }
}

// Breadcrumbs
Breadcrumbs {
    BreadcrumbsItem { "Home" }
    BreadcrumbsItem { "Products" }
    BreadcrumbsItem { "Component" }
}
Breadcrumbs { separator: ">",
    BreadcrumbsItem { "Docs" }
    BreadcrumbsItem { "API" }
}

// Pagination
Pagination {}
Pagination { with_edges: true }

// NavLink
NavLink { label: "Dashboard", active: true }
NavLink { label: "Settings", description: "App configuration" }
NavLink { label: "Disabled", disabled: true }
NavLink { label: "With handler", onclick: move || navigate("/page") }

// Stepper. Each step's state follows its position against `active`, and
// `{|| …}` makes the whole stepper follow the signal.
let step = Signal::new(1u32);
Stepper { active: {|| step.get()},
    StepperStep { label: "Account", description: "Create account" }
    StepperStep { label: "Verify", description: "Verify email" }
    StepperStep { label: "Complete", description: "Get started" }
}
}

Overlays

Modal, Drawer, and the top-anchored Notification positions automatically clear any window chrome rinch draws (the Linux in-app menu bar, the BorderlessWindow titlebar) by offsetting with --rinch-window-top-inset. The invisible click-catching backdrops behind DropdownMenu and Select deliberately do not — they must catch clicks on the chrome too.

If you hand-roll a position: fixed overlay, offset it the same way (top: var(--rinch-window-top-inset, 0px)); fixed resolves against the real viewport, so a bare top: 0 renders underneath the chrome. See Theming → Window Chrome Inset.

An overlay that animates must stay rendered. Hide it with visibility or opacity and animate transform; do not toggle display. An element that was not being rendered has no before-change style, so un-hiding it and retargeting a transitioned property in the same style pass animates nothing — on desktop and in the browser, which refuses the same shape (that is what @starting-style and transition-behavior: allow-discrete exist for). Drawer and Popover are the two worked examples: both keep their panel rendered while closed, Drawer slides its transform and Popover fades its opacity. See the transitions section of the rendering pipeline.

To animate the close as well, delay the hide. Put transition: visibility 0s linear <duration> on the hidden state only: the box stays visible through the transition’s delay, then hides, and the shown state — which declares no visibility transition — cancels a pending hide if the overlay reopens first. Drawer and Popover both do this. visibility is transitionable on desktop since issue #759, interpolated as CSS says (every step strictly inside a transition with a visible end is visible), and unlike any other property there its animated value reaches the descendants that inherit it, so the panel’s content stays on screen with it.

A visibility: hidden subtree is excluded from paint, from hit testing and from the Tab order, which is most of what display: none was doing — but not all of it, and the difference is that the box is still there. Two consequences to know before you reach for it are below.

On desktop, “excluded from paint” covers the box’s background, border and shadow, and also its text, underline (wavy too) and line-through, text-shadow, inline backgrounds, SVG shapes, scrollbar thumbs, RenderSurface frame, filter overlay and read-only selection highlight (desktop drew the text until issue #829). Three known exceptions remain: a hidden span inside a nowrap or pre root that text-overflow: ellipsis cuts is still drawn (#853; a wrapping root holding one is clipped without a “…” instead), a hidden data-viewport still cuts its hole in its ancestors’ backgrounds (#854), and a ligature that straddles a visibility boundary follows the wrong end of it (#852). As in CSS, a descendant that declares visibility: visible is painted again.

• It still takes part in layout, so a hidden overlay that is an in-flow child of an overflow: auto container contributes its box to that container’s scrollable extent, and the container grows a scrollbar for content nobody can see — as it would in a browser. A position: fixed overlay (Modal, Drawer) is exempt, since #765: a fixed box is no part of any scroll range below the viewport.
• A descendant may declare visibility: visible, and the three readers do not agree about what that means. Paint honours it (the node is drawn), the Tab order honours it (collect_focusable_nodes_from tests each node on its own), and hit testing does not — it rejects the whole subtree at the hidden ancestor before it ever reaches the descendant. So such a node is painted and tabbable but not clickable (#843).

Neither is a reason to go back to display, which cannot animate at all. They are the two places to look when a closed overlay misbehaves.

#![allow(unused)]
fn main() {
// Modal
let modal_open = Signal::new(false);

Button { onclick: move || modal_open.set(true), "Open Modal" }

Modal {
    opened: modal_open.get(),
    onclose: move || modal_open.set(false),
    title: "Confirm Action",
    size: "md",

    Text { "Are you sure you want to proceed?" }
    Space { h: "lg" }
    Group { justify: "end", gap: "sm",
        Button { variant: "outline", "Cancel" }
        Button { "Confirm" }
    }
}

// Drawer
Drawer {
    opened: drawer_open.get(),
    onclose: move || drawer_close.set(false),
    title: "Settings",
    position: "right",  // left, right, top, bottom
    size: "sm",

    // Drawer content
}

// Notification
Notification {
    opened: show_notification.get(),
    title: "Success!",
    color: "green",
    position: "top-right",
    onclose: move || close_notification.set(false),
    "Your changes have been saved."
}

// Popover
Popover { position: "bottom",
    PopoverTarget {
        Button { "Click me" }
    }
    PopoverDropdown {
        Text { "Popover content!" }
        Button { size: "xs", "Action" }
    }
}

// DropdownMenu
DropdownMenu {
    DropdownMenuTarget {
        Button { "Menu" }
    }
    DropdownMenuDropdown {
        DropdownMenuLabel { "Application" }
        DropdownMenuItem { "Settings" }
        DropdownMenuItem { "Profile" }
        DropdownMenuDivider {}
        DropdownMenuItem { color: "red", "Delete" }
    }
}

// HoverCard
HoverCard { position: "bottom",
    HoverCardTarget {
        Text { weight: "bold", "@username" }
    }
    HoverCardDropdown {
        Group { gap: "sm",
            Avatar { name: "User Name" }
            Stack { gap: "xs",
                Text { weight: "bold", "User Name" }
                Text { size: "sm", color: "dimmed", "Bio here" }
            }
        }
    }
}

// LoadingOverlay — the `position: relative` on the container is REQUIRED.
// Without it the overlay's containing block is the nearest positioned ancestor
// further up — or the viewport, and it covers the whole window (the CSS rule,
// and what rinch-web has always done).
div { style: "position: relative; height: 200px;",
    // Your content
    LoadingOverlay { visible: is_loading.get() }
}
}

Window Components

use rinch::prelude::*;
use std::rc::Rc;

#[component]
fn app() -> NodeHandle {
    // For custom left section (e.g., menu button)
    let menu_open = Signal::new(false);
    let left_section: SectionRenderer = Rc::new(move |__scope| {
        rsx! {
            ActionIcon { onclick: move || menu_open.update(|v| *v = !*v),
                "☰"
            }
        }
    });

    rsx! {
        BorderlessWindow {
            title: "My App",
            radius: "md",  // none, xs, sm, md, lg, xl
            left_section: Some(left_section),
            on_minimize: || minimize_current_window(),
            on_maximize: || toggle_maximize_current_window(),
            on_close: || close_current_window(),

            // Your content here
            Stack { gap: "md",
                Title { order: 2, "Welcome!" }
                Text { "This is a borderless window." }
            }
        }
    }
}

fn main() {
    let window_props = WindowProps {
        title: "My App".into(),
        borderless: true,
        transparent: true,
        resize_inset: Some(8.0),
        ..Default::default()
    };

    App::new(app).window_props(window_props).run();
}

BorderlessWindow Props:

The component provides:

• Rounded corners with configurable radius
• Draggable titlebar (via app-region: drag)
• Window control buttons with hover effects
• Left/right custom sections for menu buttons or additional controls
• Proper theming via CSS variables
• --rinch-window-top-inset published for overlays (36px for the titlebar, plus the menu bar height when one sits below it)

The titlebar is an in-flow element, so your content sits below it automatically. A position: fixed overlay does not — it resolves against the real viewport and would cover the titlebar and its close button. Offset such overlays by var(--rinch-window-top-inset, 0px); see Theming → Window Chrome Inset.

Building Custom Components

See the dedicated Writing Components guide for the recommended approach using #[component] PascalCase functions. The manual Component trait approach below is only needed for advanced use cases.

Building Custom Component Crates (Advanced)

You can create your own component library crate that integrates with Rinch’s theme system.

1. Create the Crate

# Cargo.toml
[package]
name = "my-components"
version = "0.1.0"
edition = "2021"

[dependencies]
rinch-core = { path = "../rinch-core" }

2. Implement the Component Trait

Each component must implement the Component trait from rinch-core. Components receive a RenderScope for DOM construction and return a NodeHandle:

#![allow(unused)]
fn main() {
use rinch_core::{Component, NodeHandle, RenderScope};

/// A custom card component.
#[derive(Debug, Default)]
pub struct MyCard {
    /// Card title.
    pub title: Option<String>,
    /// Card variant.
    pub variant: Option<String>,
    /// Whether to show shadow.
    pub shadow: bool,
}

impl Component for MyCard {
    fn render(&self, scope: &mut RenderScope, children: &[NodeHandle]) -> NodeHandle {
        // Create the card element
        let card = scope.create_element("div");

        // Build CSS classes
        let mut classes = vec!["my-card".to_string()];

        if let Some(ref v) = self.variant {
            match v.as_str() {
                "elevated" => classes.push("my-card--elevated".to_string()),
                "outlined" => classes.push("my-card--outlined".to_string()),
                _ => {}
            }
        }

        if self.shadow {
            classes.push("my-card--shadow".to_string());
        }

        card.set_attribute("class", &classes.join(" "));

        // Add title if provided
        if let Some(ref title) = self.title {
            let title_div = scope.create_element("div");
            title_div.set_attribute("class", "my-card__title");
            title_div.set_text(title);
            card.append_child(&title_div);
        }

        // Append children
        for child in children {
            card.append_child(child);
        }

        card
    }
}
}

3. Add Event Handlers

For interactive components, add event listeners directly to DOM nodes:

#![allow(unused)]
fn main() {
use rinch_core::Callback;

pub struct MyButton {
    pub onclick: Option<Callback>,
}

impl Component for MyButton {
    fn render(&self, scope: &mut RenderScope, children: &[NodeHandle]) -> NodeHandle {
        let button = scope.create_element("button");
        button.set_attribute("class", "my-button");

        // Add click handler if provided
        if let Some(ref cb) = self.onclick {
            let cb = cb.clone();
            button.add_event_listener("click", move |_| cb.invoke());
        }

        // Append children
        for child in children {
            button.append_child(child);
        }

        button
    }
}
}

invoke runs the app’s handler untracked, so it is safe to call from inside one of your component’s effects too: whatever signals the handler reads, your effect is not subscribed to them. See Reactivity.

4. Create CSS Styles

Create a styles module that generates CSS for your components:

#![allow(unused)]
fn main() {
// src/styles/mod.rs
mod card;
mod button;

pub fn generate_all_styles() -> String {
    let mut css = String::new();
    css.push_str(&card::styles());
    css.push_str(&button::styles());
    css
}

// src/styles/card.rs
pub fn styles() -> String {
    r#"
.my-card {
    background: var(--rinch-color-body);
    border-radius: var(--rinch-radius-default);
    padding: var(--rinch-spacing-md);
}

.my-card--elevated {
    box-shadow: var(--rinch-shadow-md);
}

.my-card--outlined {
    border: 1px solid var(--rinch-color-border);
}

.my-card__title {
    font-size: var(--rinch-font-size-lg);
    font-weight: 600;
    margin-bottom: var(--rinch-spacing-sm);
}
"#.to_string()
}
}

5. Export Your Components

#![allow(unused)]
fn main() {
// src/lib.rs
pub mod styles;

mod card;
mod button;

pub use card::MyCard;
pub use button::MyButton;

// Re-export Component trait for convenience
pub use rinch_core::Component;

/// Generate all component CSS.
pub fn generate_css() -> String {
    styles::generate_all_styles()
}
}

6. Use Theme CSS Variables

Leverage Rinch’s theme variables for consistency:

7. Use Your Component Crate

use rinch::prelude::*;
use my_components::{MyCard, MyButton};

#[component]
fn app() -> NodeHandle {
    rsx! {
        MyCard { title: "Hello", variant: "elevated", shadow: true,
            Text { "Card content here" }
            MyButton { onclick: move || println!("Clicked!"),
                "Click Me"
            }
        }
    }
}

fn main() {
    let theme = ThemeProviderProps {
        primary_color: Some("blue".into()),
        ..Default::default()
    };
    App::new(app)
        .title("Custom Components")
        .size(800, 600)
        .theme(theme)
        .run();
}

Component CSS Injection

Component CSS is automatically injected when you use ThemeProvider. If you need the CSS separately:

#![allow(unused)]
fn main() {
use rinch::components::generate_component_css;

let css = generate_component_css();
}

For custom component crates, inject your CSS alongside the theme:

#![allow(unused)]
fn main() {
use my_components::generate_css;

// Add to your HTML head or inject via ThemeProvider
let custom_css = generate_css();
}

Custom Components with #[component]

You can create reusable custom components using the #[component] macro. Components written in PascalCase become usable components in RSX:

#![allow(unused)]
fn main() {
use rinch::prelude::*;

#[component]
pub fn MyCard(
    title: String,
    color: String,
    children: &[NodeHandle],
) -> NodeHandle {
    rsx! {
        div { class: "my-card",
            h2 { {title.clone()} }
            div { class: "card-body", style: {move || format!("color: {}", color.clone())},
                children
            }
        }
    }
}

// Use in RSX:
#[component]
fn app() -> NodeHandle {
    rsx! {
        MyCard { title: "Hello", color: "blue",
            Text { "Card content here" }
        }
    }
}
}

Key points:

• PascalCase function names become components in RSX
• children: &[NodeHandle] is a special parameter that receives child content
• Use children in the body to render child elements
• #[component] auto-injects __scope: &mut RenderScope as the first parameter
• Props are regular Rust function parameters

Without children:

#![allow(unused)]
fn main() {
#[component]
pub fn StatusBadge(label: String, status: String) -> NodeHandle {
    rsx! {
        div { class: "badge",
            style: {move || format!("background: {}",
                if status == "success" { "green" } else { "red" })},
            {label.clone()}
        }
    }
}

// Use:
StatusBadge { label: "Active", status: "success" }
}

With callback props:

Callback and InputCallback have built-in defaults (no-op), so they work as direct props without Option wrapping:

#![allow(unused)]
fn main() {
#[component]
pub fn TodoItem(
    label: String,
    completed: bool,
    on_toggle: Callback,
    on_delete: Callback,
) -> NodeHandle {
    rsx! {
        Group { gap: "sm", align: "center",
            Checkbox {
                checked: completed,
                onchange: on_toggle,  // Forward directly — no Option unwrapping needed
            }
            Text { {label.clone()} }
            ActionIcon { variant: "subtle", color: "red",
                onclick: on_delete,
                "X"
            }
        }
    }
}

// Use — closures are auto-wrapped into Callback:
TodoItem {
    label: "Buy groceries",
    completed: false,
    on_toggle: move || toggle(id),
    on_delete: move || delete(id),
}
}

Prop type defaults:

The #[component] macro generates a Default impl for the component struct. Known types get sensible defaults automatically:

Other types (e.g., custom structs) fall back to Default::default(), so they must implement Default.

Icon System

Rinch provides a type-safe icon system built on Tabler Icons. Instead of passing arbitrary HTML strings, components accept TablerIcon enum values for discoverability and consistency.

TablerIcon lives in the rinch-tabler-icons crate and is not re-exported through the rinch prelude, so add it alongside rinch:

rinch-tabler-icons = { workspace = true }

Older snippets may show a curated Icon enum from rinch-core. That enum no longer exists — every icon prop takes Option<TablerIcon>. A few names were spelled differently: Icon::CheckCircle is now TablerIcon::CircleCheck, and Icon::XCircle is TablerIcon::CircleX.

Basic Usage

#![allow(unused)]
fn main() {
use rinch::prelude::*;
use rinch_tabler_icons::TablerIcon;

#[component]
fn app() -> NodeHandle {
    rsx! {
        Alert { icon: TablerIcon::InfoCircle, color: "blue", title: "Information",
            "This is an informational message."
        }

        Alert { icon: TablerIcon::CircleCheck, color: "green", title: "Success",
            "Operation completed successfully."
        }

        Alert { icon: TablerIcon::AlertTriangle, color: "yellow", title: "Warning",
            "Please review this carefully."
        }

        Alert { icon: TablerIcon::CircleX, color: "red", title: "Error",
            "Something went wrong."
        }
    }
}
}

Available Icons

All 4,983 Tabler icons are available as enum variants — browse them at tabler.io/icons, or iterate ALL_ICONS (with ICON_COUNT) to build a picker. A sample of the common ones:

Every icon has an Outline form; roughly a thousand also have real Filled artwork, and asking for TablerIconStyle::Filled on one that doesn’t falls back to its outline paths. See Icon System in CLAUDE.md for rendering icons standalone with render_tabler_icon.

Components with Icon Support

Every prop below is Option<TablerIcon>; rsx! supplies the Some(...), so write icon: TablerIcon::Check, not icon: Some(TablerIcon::Check).

Tree takes its icons through data instead: TreeNodeData::icon, set with the with_icon(TablerIcon) builder.

List::icon and the two Stepper icons are container defaults for the items that set none — the item’s own icon always wins — and were declared but wired to nothing until #707. The container patches its items after they have rendered, because a parent component renders after its children, and it patches whatever lands beneath it afterwards too: an item a for reconcile appends, a show_dom branch reveals, or a hand-rolled append_child adds takes the default as it lands (issue #716). An item moved from one container into another re-resolves against the one it now belongs to. Stepper goes one further and re-derives when an item leaves as well (issue #745), because its answer is a step’s position: dropping a step, or moving one out, renumbers and restates every step behind it. Stepper::progress_icon stands in for the progress_icon a step did not set, so it outranks that step’s plain icon, exactly as the step’s own progress_icon would have.

Examples

#![allow(unused)]
fn main() {
// NavLink with icons
NavLink {
    label: "Dashboard",
    left_section: TablerIcon::Settings,
    active: true
}

// Tab with icon
Tabs {
    TabsList {
        Tab { value: "home", left_section: TablerIcon::User, "Profile" }
        Tab { value: "settings", left_section: TablerIcon::Settings, "Settings" }
    }
}

// Dropdown menu items with icons
DropdownMenu {
    DropdownMenuTarget {
        Button { "Actions" }
    }
    DropdownMenuDropdown {
        DropdownMenuItem { left_section: TablerIcon::Edit, "Edit" }
        DropdownMenuItem { left_section: TablerIcon::Trash, color: "red", "Delete" }
    }
}

// Blockquote with quote icon
Blockquote { icon: TablerIcon::Quote, cite: "— Unknown",
    "The best code is no code at all."
}

// Stepper with custom icons. Each step's state comes from its position
// against `active`, so "Account" is completed and draws the CircleCheck,
// "Verify" is in progress and draws `2`, and "Complete" draws `3`.
Stepper { active: 1, completed_icon: TablerIcon::CircleCheck,
    StepperStep { label: "Account" }
    StepperStep { label: "Verify" }
    StepperStep { label: "Complete" }
}
}

Benefits of the Icon System

1. Type Safety: Compiler catches typos and invalid icon names
2. Discoverability: IDE autocomplete shows all available icons
3. Consistency: All icons use the same SVG style and sizing
4. Performance: Icons render as structured nodes, enabling differential updates instead of full re-renders

Reactive Component Props

Rinch supports two mechanisms for making component props reactive:

1. Reactive Closures on Any Prop (Re-renders Component)

Pass a closure {|| expr} to any component prop (like variant, color, size, disabled). When signals inside the closure change, the entire component re-renders with the new prop values:

#![allow(unused)]
fn main() {
let active = Signal::new(false);

rsx! {
    Button {
        variant: {|| if active.get() { "filled" } else { "light" }},
        color: {|| if active.get() { "green" } else { "gray" }},
        onclick: move || active.update(|v| *v = !*v),
        "Toggle me"
    }
}
}

This works on all component props — the macro detects closures and wraps the component in a reactive scope automatically.

2. _fn Props (Surgical DOM Updates)

For components that support _fn props, these provide more efficient updates that only touch the specific DOM node, without re-rendering the entire component. The rsx! macro auto-wraps _fn props — just pass a closure directly:

#![allow(unused)]
fn main() {
let is_checked = Signal::new(false);
let input_text = Signal::new(String::new());

rsx! {
    // Auto-wrapped: just pass a closure, no Rc::new() needed
    Checkbox {
        label: "Enable feature",
        checked_fn: move || is_checked.get(),
        onchange: move || is_checked.update(|v| *v = !*v),
    }

    TextInput {
        placeholder: "Type here...",
        value_fn: move || input_text.get(),
        oninput: move |value: String| input_text.set(value),
    }
}
}

Reactive Props Summary

| Prop Type | Accepts {|| ...} | Update Strategy | |—|—|—| | HTML element attributes | Yes | Surgical DOM update | | Component style:/class:, style shorthands, hyphenated attributes | Yes | Surgical DOM update (also on a component that re-renders for a struct prop) | | Component _fn props | Yes (auto-wrapped) | Surgical DOM update | | Component props (all others) | Yes | Full component re-render |

Components with _fn Props

Controlled Input Pattern

For controlled inputs, use value_fn + oninput together. value_fn keeps the DOM in sync with your signal; oninput updates the signal from user input. Without value_fn, programmatic signal.set("") won’t clear the input visually:

#![allow(unused)]
fn main() {
let text = Signal::new(String::new());

rsx! {
    TextInput {
        value_fn: move || text.get(),
        oninput: move |value: String| text.set(value),
        onsubmit: move || {
            println!("Submitted: {}", text.get());
            text.set(String::new());  // Clears the input thanks to value_fn
        },
    }
}
}

The echo is not written back. In this pattern every keystroke runs oninput → signal → value_fn, which returns the very text the field already shows. TextInput, PasswordInput, Textarea and NumberInput compare value_fn’s result with the field’s live text (NodeHandle::live_value, issue #238) and write only when they differ — a normalising handler’s rewrite, or a programmatic change. The comparison is against the live text, not the value attribute, which on the web still holds the last programmatic write while the user types.

Writing to the field the user is typing in. A value_fn write (or any set_attribute("value")) that lands on the focused field is adopted by the field on both backends (issue #238): it becomes the text the next keystroke edits, the caret keeps its logical position through the rewrite (a kept prefix or suffix keeps the caret with it, a same-length rewrite such as a case change leaves it in place, a resized rewrite puts it after the new text), a selection survives, and the write is deferred while an IME composition is in flight (applied when the composition ends). A programmatic write never commits onchange by itself — only a user edit in the gesture does. So a normalizing or rejecting oninput is safe to write back on every keystroke:

#![allow(unused)]
fn main() {
let digits = Signal::new(String::new());

rsx! {
    TextInput {
        value_fn: move || digits.get(),
        // Digits only: the rejected character never sticks, and the caret
        // stays put — on desktop as well as on the web.
        oninput: move |value: String| {
            digits.set(value.chars().filter(char::is_ascii_digit).collect())
        },
    }
}
}

Text inputs (TextInput, Textarea, PasswordInput, NumberInput) also take an onchange prop — the commit boundary (issue #226): it fires once with the final value when the typed gesture ends (focus leaves the control after a modification, or Enter — blur-only for Textarea), and only if the user modified it during the gesture — a programmatic write to a still-untouched field moves the reference point with it, matching the browser’s dirty flag. Keep oninput for the controlled-input signal sync; use onchange for validate-on-commit and autosave-on-leave.

Customization

Components automatically respond to theme settings:

#![allow(unused)]
fn main() {
let theme = ThemeProviderProps {
    primary_color: Some("violet".into()),  // All primary-colored components use violet
    default_radius: Some("lg".into()),     // Larger border radius everywhere
    dark_mode: true,                       // Dark theme colors
    ..Default::default()
};

// Components automatically adapt to the theme
App::new(app)
    .title("My App")
    .size(800, 600)
    .theme(theme)
    .run();
}

Component Props Reference

This page lists every prop for every component in rinch-components. All components use #[derive(Default)] unless noted, meaning Option<T> defaults to None and bool defaults to false.

Keeping this page honest: this file is hand-maintained (prose, worked examples, and “Custom Default” callouts don’t survive mechanical regeneration), so it will drift from the component structs again. Before trusting or editing a prop table, run python3 scripts/audit_component_props_doc.py from the repo root — it cross-references every row here against the real pub struct fields in crates/rinch-components/src/*.rs and prints every type mismatch, missing row, and stray row it finds (see the script’s own docstring for the handful of known non-issues it also reports, e.g. Callback vs a fully-qualified rinch_core::Callback spelling that source uses in a few files — same type, not a bug).

String props: All text/string component props are now String type (not Option<String>). Empty string "" means “not set/use default”. The RSX macro auto-converts string literals: variant: "filled" becomes String::from("filled").

Float literals: Float literals are auto-wrapped: value: 30.0 becomes Some(30.0) for Option<f32> fields.

Universal props: All components support style: and class: in RSX, which are applied to the component’s root DOM element. These support reactive closures {|| expr}. So does any hyphenated attribute — data-nofocus: "", aria-label: "…" — which is written on the root the way it would be on an HTML element; see Attributes on a component.

Both merge with what the component itself put on that root rather than replacing it: class: is added to the component’s own classes, and style: is laid over the component’s own inline declarations, last-wins per property. That matters because a component’s inline style is not decoration — it is how a component publishes a prop to its own stylesheet, and every overlay’s z_index is a custom property written there. style: used to write the whole attribute, which erased all of them (issue #647).

A reactive style: takes its own previous declarations back on each re-run, so it never accumulates: a property the closure has stopped naming is removed, or restored to the value it had been overriding. It overwrites a property it still names where that property stands rather than re-appending it, and it leaves alone one whose current value somebody else has since written. The one case it does not settle is a same-property collision with a style shorthand — see Application Order.

A reactive class: has the same memory: it takes off the words it last wrote before adding the new ones, so it never accumulates its own old values. It does not reach a class it has never named — but naming one is enough to own it. A word the closure emits is the closure’s to remove, so a re-run that stops naming it takes it off and nothing puts it back, and that holds for a class the component itself wrote, its base class included: class: {|| if p.get() { "rinch-checkbox marker" } else { "marker" }} strips rinch-checkbox off the element permanently. That is issue #647’s mechanism and the rule the reactive style: follows too — don’t name a class the component owns.

The merge only holds if the component keeps its side of it. A class: prop is applied to the handle Component::render returned, which is after the component has built its tree and registered its effects. A component effect that then rewrote the whole class attribute — from a base string captured during render — therefore discarded the caller’s class on its first run, and there was no way to get it back short of a re-render. Checkbox { class: "compact", checked_fn: … } styled correctly until the user clicked it once (issue #717). So a component effect adds and removes the one class it is responsible for (NodeHandle::add_class / remove_class) and never writes class wholesale. add_class is idempotent, as DOMTokenList.add is, so an effect that re-runs without changing its answer leaves the attribute alone.

Style shorthands: All elements and components support CSS shorthand props like w, h, m, p, maw, etc. These expand to set_style() calls and compose with component styles. Spacing scale values (xs, sm, md, lg, xl) auto-resolve to var(--rinch-spacing-{value}):

#![allow(unused)]
fn main() {
// Shorthands work on both HTML elements and components
div { p: "md", m: "lg", w: "200px", "Styled div" }
Stack { gap: "md", p: "xl", maw: "600px",
    Text { "Content" }
}
}

See Style Shorthands for the full list.

Prop auto-wrapping: The rsx! macro automatically wraps prop values. See RSX Prop Transformation Rules — do NOT manually wrap in Some(...).

All props are reactive: Every component prop accepts a reactive closure {|| expr} in addition to a static value. When any prop uses a closure, the component automatically re-renders when the signals inside change:

#![allow(unused)]
fn main() {
let active = Signal::new(false);

// Static prop value
Button { variant: "filled", "Always filled" }

// Reactive prop value — re-renders when `active` changes
Button { variant: {|| if active.get() { "filled" } else { "outline" }}, "Toggle" }
}

For more efficient surgical updates (no full re-render), use _fn suffix props where available (e.g., value_fn, checked_fn, opened_fn).

A value_fn write to the text field that currently holds focus is adopted by the field (issue #238): the next keystroke edits the written text, the caret and selection keep their logical position through the rewrite, the write is deferred during an IME composition, and it never commits onchange by itself. See Controlled Input Pattern.

Layout

Stack

Vertical flex container.

Group

Horizontal flex container.

SimpleGrid

Auto-layout grid.

Container

Centered max-width wrapper.

Center

Centers content horizontally and vertically.

Space

Empty spacing element.

Buttons

Button

ActionIcon

Icon-only button. For text-based action buttons, use Button with compact styling.

CloseButton

Draws a stroked X, sized by icon_size or by size. Until issue #474 it drew nothing at all: the glyph was an empty <span class="rinch-icon rinch-icon--close"> and no stylesheet in the workspace matches that class.

Form Inputs

TextInput

Textarea

PasswordInput

Custom Default: toggle_visibility defaults to true.

NumberInput

Checkbox

Switch

Select

Keyboard (#251, #434). The trigger is focusable; Enter or Space opens the list, and while it is open ArrowUp/ArrowDown move the highlight (wrapping), Home/End jump, Enter commits (Space too, unless it is part of a type-ahead prefix), Escape closes without committing, Tab closes, and typing jumps to the first matching label. The trigger keeps the focus throughout, a pointer pick included; focus moving anywhere else closes the list.

Options are passed via data, not as children — the trigger’s _children param is unused. Build a Vec<SelectOption> with SelectOption::new(value, label) (a SelectOption is { value: String, label: String }; an empty label falls back to displaying value):

#![allow(unused)]
fn main() {
Select {
    data: vec![
        SelectOption::new("us", "United States"),
        SelectOption::new("ca", "Canada"),
    ],
    value_fn: move || country.get(),
    onchange: move |v: String| country.set(v),
}
}

The trigger is a Tab stop (tabindex="0", role="combobox", aria-haspopup="listbox", and an aria-expanded that tracks the open state). Enter and Space on it toggle the dropdown; the open list’s keys are above.

Radio / RadioGroup

Radio:

RadioGroup:

Slider

Color

ColorSwatch

A colored square with checkerboard transparency indication.

ColorPicker

Interactive color picker with saturation panel, hue/alpha sliders, hex input, and swatches.

onchange reports author edits only. A value arriving through value_fn — a peer’s edit, a programmatic set — is adopted silently: the picker applies all four of its internal components (hue, saturation, value, alpha) as one batched transition and fires nothing, because the caller already has that value. Only a drag, a typed hex or a swatch click reports — once per act, with the completed colour, never a partially-applied mixture. This is what lets a consumer bind value_fn to the same store onchange writes without the two chasing each other.

The picker’s state survives its own round trip. An echoing binding — a store that value_fn reads and onchange writes back into — no longer degrades the picker’s hue, saturation, or alpha. Emitted colour strings quantize — to 8-bit RGB under the hex and rgb formats, to whole degrees and percents under hsl — so the echo of the picker’s own emission routinely parses to a slightly different hue/saturation than the internal state it was formatted from (and to no hue at grey, or no alpha under an alpha-less format like hex); the picker recognises such an echo as its own state and leaves the internal signals untouched, so dragging saturation down to grey and back resumes the original hue, and the alpha slider works under the default hex format. A genuinely foreign value (one that denotes a different colour, alpha included) still applies — and even then, channels the value cannot carry are kept rather than fabricated: a grey keeps the current hue (unless it states one, as any hsl() value does — hsl(240, 0%, 50%), the sub-percent hsl(205, 0.3%, 49%), and hsl(0, 0%, 50%) alike — a stated hue is adopted; note that a store which re-spells an RGB grey as hsl() writes hue 0, and the picker adopts it), a black keeps hue and saturation, judged by what the value renders at 8-bit rather than by exact parse floats. One corner is deliberately conceded: under an alpha-dropping display format, an inbound value that restates the picker’s current RGB with an explicitly opaque alpha (rgba(r, g, b, 1)) is indistinguishable from a normalizing store’s echo of the emission and does not apply — bind an alpha-carrying format (hexa, rgba, hsla) when external writes need to drive alpha. More generally, the echo test judges identity at the resolution of the picker’s own emission in the notation the inbound value is written in — 8-bit channels for a hex, named or rgb() value, whole degrees and whole percents for an hsl() value, alpha at two decimals under rgb()/hsl() — never finer than that notation’s serializer writes, whatever finer channels the parser accepts. A difference the emission could not have spelled folds as an echo, in both directions: on an hsl-format wire a stated-hue move of a whole degree applies even at very low chroma, where it does not move the rendered colour by an 8-bit step, while an inbound hsl() value that shares a spelling with the picker’s current colour folds even where 8-bit could tell them apart (a normalizing store re-spelling the picker’s own hex emission as hsl() is indistinguishable from it). A store that re-spells the emission in another notation may also round a tie its own way — #797e81’s hue is exactly 202.5°, which rinch writes as 202 and an exact converter as 203 — so an inbound value compared against what the picker emits (not what it holds) is accepted at either rounding of the emission’s exact value, and at nothing farther: #797e82’s hue is 206⅔°, so a peer’s hsl(206, …) under a hex display still applies. The text field’s write-back guard judges at the same resolution, so field, thumbs and store stay in step.

Accepted colour notations (everywhere a colour string is read — value, value_fn, typed text, swatches): hex in 3, 4, 6, or 8 digits (#rgb, #rgba, #rrggbb, #rrggbbaa, with or without the #), rgb()/rgba() and hsl()/hsla() in both the legacy comma syntax and the modern space-separated syntax (rgb(51 51 102 / 0.5); alpha as a number or a percentage), and the CSS named colours (red, rebeccapurple, transparent). Named colours and function names are case-insensitive, as in CSS. Out-of-range channels clamp to their CSS ranges; hue wraps (#243).

The text field is the author’s while they type. The hex field parses on every keystroke, and a valid prefix of the colour being typed (#336 on the way to #3366cc) is already a parseable colour — it updates the preview and reports through onchange live, but the picker never rewrites the field under the author’s caret while its text denotes the colour the picker already holds. The field text is normalized to the output format when the colour actually moves away from it (a drag, a swatch click, an external value_fn change) — and, since issue #226, when the typed gesture commits (focus leaves the field, or Enter): a committed shorthand like 336 normalizes to #333366, and committed text that parses as no colour reverts to the colour the picker holds, so an attribute-reading consumer never sees a stale shorthand outlive the gesture that typed it. ColorInput’s text field follows the same contract.

“The field’s text” here is the field’s live text, read through NodeHandle::live_value (issue #238) — on the web the .value property the user types into, never the value attribute, which there holds only what was last written programmatically. It is the same read the value_fn binding of TextInput, PasswordInput, Textarea and NumberInput makes before writing, so the echo of a keystroke is not written back there either.

ColorInput

Text input with inline color preview and dropdown ColorPicker.

size and radius were declared but unread until #263. size always resolves to a step, radius does not: an unrecognised size falls back to md — matching TextInput, whose size parses with unwrap_or_default() — and md reproduces the geometry the field was hard-coded to before, so nothing resizes by upgrading. An unrecognised radius emits no class at all and leaves the base --rinch-radius-sm standing, which is what DropdownMenu, Modal and Card do.

The dropdown is dismissed three ways (#465): clicking the field again, clicking anywhere outside it, and Escape. The outside click is the one that is optional — close_on_click_outside is true by default, matching every other popover in the library, and turning it off mounts no backdrop at all, so the field is the only thing a click dismisses the dropdown with. Escape is not gated by it, so false is the pointer half of the behaviour ColorInput had until #465 rather than a return to it in full. (The prop was declared and read by nothing before that; #263 removed it rather than wire it, because unlike size and radius there was no behaviour behind it to connect, and it came back here with the interaction it names.)

Two details follow from what the trigger is. The field stays clickable while the picker is open — it is a text input, not a button, so a click into it places a caret rather than being swallowed by the dismissal, and it still toggles the dropdown shut. And Escape joins the dismiss stack when the dropdown opens, not when the input mounts, so a ColorInput inside a Modal answers Escape first while its picker is open and leaves the key to the modal the moment it is closed.

The dropdown picker is bound to the input’s current colour (#237). Typed text previews in it live (a parseable keystroke moves its panel and thumbs, at the typed notation’s own grid — a typed hsl(205, 3%, 49%) lands the hue thumb on 205° whatever the display format, and a typed #228be680 moves the alpha thumb), an external value_fn change moves it, and a slider nudge derives from the colour the input currently holds — never from the colour it mounted with. An external arrival is silent all the way through: the picker applies it without reporting, and the input’s onchange fires nothing the caller did not author.

The field shows the colour in the format output spelling. A value or value_fn written in another notation (red, hsl(200, 3%, 49%)) is displayed re-spelled (#ff0000, #797e81 under hex); the field is rewritten only when the colour moves away from its text, so the author’s mid-typing text is left alone as before, and an unparseable commit reverts it to the last committed colour in that same spelling. Under an alpha-dropping format (hex, rgb, hsl) an alpha typed into the field previews in the picker but is dropped at the commit boundary, and an alpha arriving through value_fn is only half-honoured: the dropdown picker adopts it (its alpha thumb moves when alpha is on) and the swatch renders it translucent, but the field cannot spell it and every change the input reports drops it. The corner ColorPicker concedes above applies here too: a later value_fn value restating the colour opaque (#ff0000, rgba(255, 0, 0, 1)) is indistinguishable from the input’s own echo and does not apply, so the picker keeps the alpha — and the swatch snaps opaque on the next reported change while the picker’s alpha thumb does not — until a value carrying a different, non-opaque alpha arrives. Bind hexa/rgba/hsla when alpha must be externally drivable.

Typography

Text

Title

Code

Kbd

Anchor

Blockquote

Mark

Highlight

Custom Default: ignore_case defaults to true.

Data Display

Avatar

AvatarGroup: spacing: String — overlap spacing.

Badge

Card