Environment and Shared Models
Provide typed configuration and shared objects to a subtree without threading every dependency through every initializer.
The environment supplies values to descendants through an inherited, client-local scope. It is useful when a subtree shares configuration, such as control appearance, or when many views need access to the same model. A descendant can read the nearest provider without every intermediate initializer forwarding the value.
Typed Environment Keys
use hera_kit::{EnvKey, View, ViewExt, text, view_fn};
struct Compact;
impl EnvKey for Compact {
type Value = bool;
fn default() -> bool { false }
}
fn heading() -> impl View {
view_fn(|cx| {
let compact = cx.environment::<Compact>();
Ok(text("Library").ui_font(if compact { 18.0 } else { 28.0 }))
})
}
let content = heading().environment::<Compact>(true);In this example, the Compact provider overrides the key's default for the heading's subtree. If another provider is introduced closer to the heading, that nearer value takes precedence. A key always has an explicit default, so reading it without a provider remains different from requesting a missing required model object.
Shared Model Objects
For a shared model, attach .environment_object(Rc<Model>) to the subtree and read it inside a body with cx.object::<Model>()?. The read is fallible because the model is a required dependency: if no provider exists, evaluation returns ViewError.
Store observable model fields in state or bindings. An Rc gives shared ownership; it does not make an ordinary struct's fields observable or wake the host when they change.
Accepted Callback Scopes
Environment scope follows the tree through publication. Built nodes retain the providers used to evaluate them, allowing accepted callbacks to keep their accepted scope if a speculative replacement is rejected. The captured bindings still reach live model values, and root environment bindings remain shared, so this preserves scope ownership without freezing the entire model.
Provider identity also affects reuse. An unchanged provider can retain its runtime binding, whereas replacing a provider invalidates dependent reads. Object providers compare Rc identity, allowing the runtime to distinguish reuse of the same model instance from an intentional replacement.
Surface Geometry
cx.environment::<SurfaceSize>() exposes the current root proposal and participates in dependency tracking. Use it when application structure truly depends on surface size; ordinary layout should prefer parent constraints and content sizing.
Control Appearance
Built-in controls read ControlStyleKey, so one provider can give a group of controls a consistent appearance. Use ControlStyle::compact() for a denser style, or provide a value with the desired foreground, background, pressed background, padding, and corner radius.
A system-wide preference needs a service or protocol that updates each application's model. The environment alone is not a cross-process settings channel.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/kit/src/env/mod.rscrates/kit/src/view/modifiers.rscrates/kit/src/view/controls.rs