Documentation menu

Attribute View Authoring

Use the optional view macro to declare mounted state, inherited dependencies, and explicit action captures.

The optional #[hera_kit::view] macro lets a function declare mounted state, inherited dependencies, and action captures close to the code that uses them. It generates an ordinary closure view, so the resulting interface follows the same runtime semantics as handwritten authoring. The macro is included by the default macros feature; disable default features if you prefer to use the toolkit without it.

View Declarations

use hera_kit::{button, text, view, View, ViewContext, ViewExt};

#[view]
fn counter(cx: &mut ViewContext<'_>, initial: u32) -> impl View {
    #[state]
    let count: u32 = initial;

    #[action(count)]
    let increment = |ctx| {
        count.update(ctx.runtime, |value| *value += 1);
    };

    button(text(format!("Count: {}", cx.read(&count))), increment)
        .padding(16.0)
}

let content = counter(0);

The macro supplies the function's first parameter during evaluation, so callers construct the counter with counter(0) rather than passing a context themselves. Declare that parameter as a mutable reference to ViewContext with an immutable binding name. The remaining parameters become owned props that require Clone + 'static, allowing the generated body to clone them for each evaluation.

Mounted State Declarations

The state declaration #[state] let count: u32 = initial names a stored u32 but gives the body a Binding<u32> through which to access it. Reads and writes remain explicit, as in cx.read and count.update; assigning to an ordinary local variable does not become a reactive mutation.

By default, the declaration's name supplies its state slot ID. If a rename should preserve the existing slot, retain the ID explicitly with #[state(id = "counter")]. The initializer runs when that identity mounts, so neither reconstructing the view nor changing its props reinitializes existing state.

Inherited Dependencies

Inherited values use declarations without initializers. Write #[environment(Key)] let value: T; to read a typed key, or #[environment_object] let model: Rc<Model>; to request a required model. Their explicit types identify the dependency, while ordinary environment modifiers continue to supply the providers.

Providers remain ordinary environment modifiers. Missing objects fail evaluation; constructing the view description remains infallible.

Explicit Action Captures

An action declaration such as #[action(count)] clones the listed handle into a typed synchronous move closure. Capturing the binding lets the action access live state when it runs; capturing an ordinary value instead retains the snapshot from that body evaluation.

Actions take one input context parameter. Start asynchronous work through an application service and return results through the host update mechanism rather than making the action itself async.

Declaration Identity

State ownership stays predictable when helper attributes appear on direct let statements in the outer body. Put repeated or conditional state in a child view so each instance has its own identity. The macro checks these declarations at compile time and rejects duplicate slot IDs, borrowed props, async actions, and invalid return signatures.

If the authored body needs to return an explicit Result<impl View, ViewError>, mark it with #[view(fallible)]. Callers still receive a view description from the generated constructor, with errors resolved during evaluation. When the dependency itself has been renamed, #[view(crate_path = my_kit)] identifies the import path used by the expansion.

Source Reference

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

  • crates/kit-macros/src/lib.rs
  • crates/kit/docs/ATTRIBUTES.md
  • crates/kit-macros/tests/ui.rs