Documentation menu

button

Present a view label with semantic activation, pressed state, cancellation, and focus.

Use button(label, action) -> Button<V> to associate an application action with a view label. The label can be a single string view or a larger composition, while the synchronous callback receives &mut InputContext on the UI thread when activation occurs.

Button Construction

use hera_kit::{button, text, view_fn};

let control = view_fn(|cx| {
    let count = cx.state("count", || 0u32);
    Ok(button(text("Add item"), move |ctx| {
        count.update(ctx.runtime, |value| *value += 1);
    }))
});

Capture a binding when the action needs live model access. Clone that binding first if another action or child also needs it.

Semantic Activation

A button keeps the pressed state, focus state, and focus target needed to follow an interaction across several events. It invokes its action through the toolkit's shared activation and cancellation machinery, ensuring that a raw pointer release is interpreted in the context of the interaction that preceded it.

This gives keyboard and pointer activation a shared control path. Use the built-in control instead of duplicating those rules with low-level pointer handlers.

Control Styling

Appearance comes from the button's inherited ControlStyleKey. Its value supplies the normal and pressed backgrounds, foreground, padding, and corner radius, allowing related buttons to share one style provider. A focused button adds a border to make its current keyboard focus visible.

Provide .environment::<ControlStyleKey>(style) on a subtree when its controls should share an appearance, and use .disabled(true) when their action is unavailable. The label remains a view, so you can combine an icon and text within the same control.

Action Execution

Keep the callback focused on changing state or initiating application work. For slow operations, let a service task perform the work and return its result through AppHandle. Waiting synchronously for that result on the UI thread could prevent the update queue from progressing.

See hosting, toggle, and input.

Component-Specific Reference

fn button<V: View + 'static>(
    label: V,
    action: impl Fn(&mut InputContext) + 'static,
) -> Button<V>

Button<V> has no additional component-specific builder methods. Its label and synchronous action are construction inputs, while appearance comes from the inherited ControlStyleKey and interaction configuration comes from common modifiers such as disabled. The action can run repeatedly, so capture live model bindings when activation should observe current state.

ControlStyle

Supply a ControlStyle through .environment::<ControlStyleKey>(style) on the button or an enclosing subtree. These are fields of the style value, rather than methods on Button.

FieldBehavior
backgroundPaints the control in its normal state.
pressed_backgroundPaints the control while activation is pressed.
foregroundProvides inherited foreground paint to the label.
paddingReserves insets around the label inside the control.
corner_radiusSets the control background’s uniform corner radius.

The default style uses a dark normal background, a darker pressed background, a white foreground, 16-by-10 logical pixel horizontal and vertical insets, and a zero corner radius. ControlStyle::compact() -> ControlStyle keeps the default paints while selecting 10-by-5 insets and a corner radius of six. Set individual fields on either returned value when the application needs a different appearance.

Configuration Example

use hera_kit::{button, text, ControlStyle, ControlStyleKey, ViewExt};

let save = button(text("Save"), |_ctx| {})
    .environment::<ControlStyleKey>(ControlStyle::compact())
    .disabled(false);

The environment modifier supplies the button’s concrete appearance, while disabled remains part of the shared View Modifiers API. A real action can update a model or initiate work through an application service.

Source Reference

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

  • crates/kit/src/view/controls.rs
  • crates/kit/src/input/activation.rs