Documentation menu

State and Bindings

Give each piece of data a clear owner and pass shared editing access through bindings.

A view often needs data that survives reevaluation, such as a counter value or an unfinished edit. Hera Kit stores that data in the UI runtime and associates mounted storage with the view's identity. A binding gives controls shared access to the storage, so they can read and edit one value without copying it into separate state cells.

Local State Ownership

Create local state inside a body with cx.state("name", initializer). The returned Binding<T> refers to a slot initialized when that identity first mounts. Subsequent evaluations reuse the slot, which means that changing a prop used by the initializer does not automatically replace the existing state.

The slot name identifies the value within its body independently of call order, so each name must be unique and retain a stable value type. When state belongs to repeated or conditional content, put it in a child view whose identity expresses when that storage should exist.

Explicit Reads and Writes

During evaluation, cx.read(&binding) supplies the value used to describe the interface. An action can then change that same value with binding.set(ctx.runtime, value) or binding.update(ctx.runtime, |value| ...). If writing an equal value should leave dependencies unchanged, use set_if_changed to suppress the redundant write.

use hera_kit::{text, toggle, v_stack, view_fn};

let preferences = view_fn(|cx| {
    let enabled = cx.state("enabled", || true);
    let status = if cx.read(&enabled) { "Enabled" } else { "Disabled" };
    Ok(v_stack()
        .spacing(12.0)
        .child(text(status))
        .child(toggle("Notifications", enabled)))
});

Shared Editing Access

A child that edits parent-owned data should receive a Binding<T> from the parent. Cloning the binding shares access to the same source, while Binding::map can expose one field of a larger value. A mapped binding still invalidates at the parent cell's granularity, which matters when unrelated fields change independently.

A read-only child usually needs an owned prop, not another state slot. Duplicating a model field into child-owned state creates a synchronization problem unless independent editing is an intentional feature.

State Lifetime

Mounted storage remains alive through ownership leases held by bindings and accepted tree nodes. When a removal is accepted, the tree releases its lease, though callbacks or other binding clones can keep the value alive. If removal is rejected, the accepted tree continues to own the original storage.

Data whose lifetime belongs to the application host can instead be allocated as State<T> in the runtime factory. That handle identifies runtime-owned storage without the mounted ownership lease used by a local view slot. Both forms still belong to their creating runtime and must be read or written through it.

Model and Scene Outcomes

Rejecting a scene candidate preserves the previous accepted tree; it does not roll back model writes. A later evaluation can describe the new model against that earlier accepted baseline.

See attribute graph for propagation and reconciliation for accepted-tree publication.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/view/context.rs
  • crates/kit/src/ag/binding.rs
  • crates/kit/src/ag/reactive.rs