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.
| Field | Behavior |
|---|---|
background | Paints the control in its normal state. |
pressed_background | Paints the control while activation is pressed. |
foreground | Provides inherited foreground paint to the label. |
padding | Reserves insets around the label inside the control. |
corner_radius | Sets 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.rscrates/kit/src/input/activation.rs