Documentation menu

View Modifiers

Reference for every common ViewExt modifier, including layout, appearance, clipping, interaction, environment, and identity.

A view modifier refines an existing description by changing its layout, appearance, inherited configuration, or identity. Import ViewExt to use these methods on primitives, controls, closure views, and custom View implementations. Each method consumes its receiver and returns a new description, so the returned value must be chained, assigned, or passed to a parent.

This reference covers all 17 methods on the public ViewExt trait. Geometry uses logical pixels unless an entry states otherwise. Modifier order matters because a layout or decoration wrapper establishes the region to which later modifiers apply.

Modifier Index

CategoryModifiers
Layout and scrolling
Appearance
Visual geometry and clipping
Interaction
Inherited configuration
Identity and evaluation

Modifier Order

Read a modifier chain from its content outward. Padding, frames, and backgrounds create surrounding regions, so moving a modifier across one of those boundaries can change which region it affects.

use hera_kit::{text, Color, ViewExt};

let paint = Color::rgba(0.92, 0.94, 0.97, 1.0);
let painted_insets = text("Ready").padding(16.0).background(paint);
let clear_insets = text("Ready").background(paint).padding(16.0);

The first description paints the padded region; the second reserves unpainted space around an already decorated label. Similarly, an opacity or clip applied before a background affects the content at that stage, while applying it afterward affects the enclosing composition.

Concrete component methods belong before common modifiers that change the return type. For example, .radius(12.0) is available on a Rectangle, but .padding(8.0) returns a Modified<Rectangle>. Configure the rectangle's radius before padding rather than expecting the wrapper to expose rectangle-specific methods.

Layout and Scrolling

padding

fn padding(self, insets: impl Into<Insets>) -> Modified<Self>

Reserves space around the content by placing it inside a padding wrapper. The wrapper subtracts the insets from the proposal offered to its child, then includes those insets in its own measured size. A single f32 applies the same inset to every edge; Insets::symmetric(horizontal, vertical) or an Insets value provides independent distances.

Every inset must be finite and nonnegative. Invalid values produce a layout error during evaluation rather than a usable padded region.

use hera_kit::{text, Insets, ViewExt};

let label = text("Library")
    .padding(Insets::symmetric(20.0, 12.0));

The label has 20 logical pixels of padding on its leading and trailing edges and 12 on its top and bottom edges. Padding changes the space reserved by layout; offset changes visual placement instead.

frame

fn frame(self, width: f32, height: f32) -> Modified<Self>

Places the content inside a wrapper with an explicit width and height. Both dimensions must be finite and nonnegative, and the parent's constraints can limit the resolved frame. The default alignment centers the content within that region.

use hera_kit::{text, ViewExt};

let status = text("Connected").frame(240.0, 48.0);

The frame defines a surrounding layout region. It does not overwrite the child's layout kind or automatically clip content that extends beyond its bounds. Add clipped when the region should also act as a visual boundary.

frame_constraints

fn frame_constraints(self, frame: Frame) -> Modified<Self>

Places the content inside a frame whose axes can be configured independently. A dimension with neither an explicit size nor fill behavior hugs the content. A fill dimension consumes a finite parent offer and hugs the content when that offer is unbounded.

Frame configurationBehavior
width(value), height(value)Supplies an explicit, finite, nonnegative dimension.
min_width(value), min_height(value)Sets a finite, nonnegative minimum.
max_width(value), max_height(value)Sets a maximum at least as large as the corresponding minimum; positive infinity permits an unbounded maximum.
fill_width(), fill_height()Uses the available finite extent on that axis.
alignment(value)Positions content within the resolved frame; the default is Alignment::Center.
use hera_kit::{text, Alignment, Frame, ViewExt};

let heading = text("Library").frame_constraints(
    Frame::new()
        .fill_width()
        .min_height(44.0)
        .alignment(Alignment::Leading),
);

The heading fills the offered width and aligns its content at the leading edge. Invalid dimensions or minimum/maximum combinations fail layout evaluation. See Layout Fundamentals for proposals, parent constraints, and wrapper sizing.

scrollable

fn scrollable(self) -> ScrollView<Self>

Places an existing view inside a clipped, interactive scroll viewport. Scrolling is vertical by default, and overflow indicators are initially enabled. The returned ScrollView supports .axis(ScrollAxis), .indicators(bool), and .scroll_position(Binding<Point>) before common modifiers wrap it again.

use hera_kit::{text, v_stack, ViewExt};

let rows = v_stack()
    .spacing(8.0)
    .children((0..40).map(|index| text(format!("Item {index}"))));

let viewport = rows
    .scrollable()
    .indicators(true)
    .frame(320.0, 240.0);

The outer frame gives the viewport a finite extent while its content can grow along the scrolling axis. Content is constructed eagerly; this modifier does not virtualize a collection. The scrollable reference describes wheel input, draggable indicators, and programmatic position.

Appearance

background

fn background(self, paint: impl Into<Paint>) -> Modified<Self>

Draws a noninteractive background behind the bounds of the description at that point in the chain. The background is a decoration whose size follows its content; it does not contribute an independent intrinsic size.

use hera_kit::{text, Color, ViewExt};

let card = text("Ready")
    .padding(16.0)
    .background(Color::rgba(0.92, 0.94, 0.97, 1.0));

Here, the background covers the padded bounds. Applying it before padding leaves the outer insets unpainted. Paint also represents gradients, so callers can supply a prepared paint instead of a solid color.

foreground

fn foreground(self, paint: impl Into<Paint>)
    -> EnvironmentView<Self, ForegroundColor>

Overrides the inherited text foreground paint for the subtree. It is a convenience for an environment override using ForegroundColor, so text descendants can share a paint without each receiving a separate style argument.

use hera_kit::{text, v_stack, Color, ViewExt};

let labels = v_stack()
    .child(text("Library"))
    .child(text("Recently opened"))
    .foreground(Color::rgba(0.18, 0.25, 0.36, 1.0));

This configures inherited text paint. A rectangle's fill remains its own content configuration, and a nearer foreground provider can override the inherited value for its descendants.

opacity

fn opacity(self, value: f32) -> Modified<Self>

Multiplies the view's opacity. Repeated modifiers multiply together, and opacity also composes through the retained scene hierarchy. Use finite values from zero through one; the final scene property must satisfy server validation.

use hera_kit::{text, ViewExt};

let subdued = text("Archived")
    .opacity(0.8)
    .opacity(0.5);

The resulting node opacity is 0.4 before inherited opacity is applied. Opacity changes appearance without changing the space reserved by layout. Use disabled to express disabled interaction explicitly.

box_style

fn box_style(self, style: BoxStyle) -> Modified<Self>

Assigns box appearance with independent corner radii, edge borders, and inset or outset shadows. Corner arrays use top-left, top-right, bottom-right, and bottom-left order. Border arrays use top, right, bottom, and left order, and border widths lie inside the outer box.

use hera_kit::{rectangle, BoxStyle, Color, ViewExt};

let panel = rectangle(Color::rgba(0.96, 0.97, 0.99, 1.0))
    .box_style(BoxStyle {
        radii: [12.0; 4],
        border_widths: [1.0; 4],
        border_colors: [Color::rgba(0.75, 0.78, 0.84, 1.0); 4],
        ..BoxStyle::default()
    })
    .frame(240.0, 120.0);

BoxStyle overrides the node's uniform radius and border configuration. Its fixed shadow array holds up to four BoxShadow values, with shadow_count identifying the active entries. Outset shadows precede the box; inset shadows follow its fill and border but precede its children. Styling a box does not by itself establish a descendant clip; use a clipping modifier for that boundary.

Visual Geometry and Clipping

offset

fn offset(self, x: f32, y: f32) -> Modified<Self>

Adds a visual translation without changing the space reserved by layout. Repeated offsets accumulate on the resulting node, so a positive horizontal offset moves the content to the right while its parent continues to allocate the original layout region.

use hera_kit::{text, ViewExt};

let badge = text("New").offset(8.0, -4.0);

Use padding, a frame, or container alignment when neighboring views should respond to the placement. Offsets can move content beyond an ancestor's clip, where it will no longer be visible.

clipped

fn clipped(self) -> Modified<Self>

Clips the view and its descendants to its resolved frame. The clip follows the layout result, making this suitable for content whose visible boundary should resize with its container.

use hera_kit::{text, ViewExt};

let bounded = text("A label inside a bounded region")
    .frame(180.0, 44.0)
    .clipped();

This replaces an explicit clip on the same resulting node with frame-based clipping. Ancestor clips still apply. A later clip call replaces frame-based clipping on that node with the supplied geometry.

clip

fn clip(self, clip: impl Into<Clip>) -> Modified<Self>

Assigns a rectangular, rounded rectangular, or path clip to the subtree. Clip coordinates are relative to the view's resolved origin, and the clip's transform maps its authored geometry within that local coordinate space. A Rect converts directly into an identity-transformed rectangular clip.

use hera_kit::{rectangle, Color, Point, Rect, Size, ViewExt};

let cropped = rectangle(Color::rgba(0.2, 0.4, 0.7, 1.0))
    .frame(200.0, 100.0)
    .clip(Rect::new(Point::new(10.0, 10.0), Size::new(180.0, 80.0)));

An explicit clip replaces any clip previously assigned to the same resulting node, while ancestor clips continue to intersect it. Add a layout wrapper between clips when the composition needs distinct ancestor and descendant clipping regions.

clip_path

fn clip_path(
    self,
    path: impl Into<Arc<PathData>>,
    rule: FillRule,
    transform: Transform2D,
) -> Modified<Self>

Constructs a path clip from shared, immutable geometry, a fill rule, and an explicit transform. The view description owns the path reference, allowing retained scene snapshots to keep the geometry alive independently of the caller's local variable.

use hera_kit::{
    rectangle, Color, FillRule, PathData, Transform2D, View, ViewExt,
};
use std::sync::Arc;

fn masked_panel(path: Arc<PathData>) -> impl View {
    rectangle(Color::rgba(0.2, 0.4, 0.7, 1.0))
        .frame(200.0, 100.0)
        .clip_path(path, FillRule::EvenOdd, Transform2D::IDENTITY)
}

The transform maps path coordinates relative to the resolved view origin. The frame does not automatically scale the path to fit, so prepare the contours or transform for the intended region. The same replacement and ancestor-intersection rules as clip apply.

Interaction

disabled

fn disabled(self, value: bool) -> Modified<Self>

Disables activation and input callbacks throughout the subtree when value is true. This lets a parent disable several related controls while preserving their layout and content descriptions.

use hera_kit::{button, text, v_stack, ViewExt};

let busy = true;
let actions = v_stack()
    .child(button(text("Save"), |_ctx| {}))
    .child(button(text("Publish"), |_ctx| {}))
    .disabled(busy);

Disabled behavior is separate from visual styling. Supply the intended disabled appearance through the controls or their surrounding views. Passing false leaves the subtree's existing disabled state intact; an outer .disabled(false) does not reenable callbacks removed by an inner .disabled(true).

Inherited Configuration

environment

fn environment<K: EnvKey>(self, value: K::Value) -> EnvironmentView<Self, K>
where
    K::Value: PartialEq

Overrides a typed environment key for this subtree. The key supplies its value type and default, and descendants read the nearest provider through their view context. Key values implement Clone + 'static through EnvKey, while this modifier also requires PartialEq.

use hera_kit::{text, view_fn, EnvKey, ViewExt};

struct SectionTitle;
impl EnvKey for SectionTitle {
    type Value = String;
    fn default() -> String { "Untitled".into() }
}

let heading = view_fn(|cx| {
    Ok(text(cx.environment::<SectionTitle>()))
}).environment::<SectionTitle>("Library".to_owned());

Equal overrides between builds retain their reactive provider binding. A changed value or provider scope participates in dependency tracking. The Environment guide explains provider lookup and accepted callback scopes.

environment_object

fn environment_object<T: 'static>(self, object: Rc<T>)
    -> EnvironmentObjectView<Self, T>

Provides a shared model object to descendants by its concrete type. The object stays on the UI thread, and the provider compares Rc pointer identity to determine whether the inherited object changed.

use hera_kit::{text, view_fn, ViewExt};
use std::rc::Rc;

struct Settings {
    title: String,
}

let settings = Rc::new(Settings { title: "Library".into() });
let heading = view_fn(|cx| {
    let settings = cx.object::<Settings>()?;
    Ok(text(settings.title.clone()))
}).environment_object(settings);

A required object lookup fails evaluation when no matching provider exists. Providing an object does not make its ordinary fields observable; use state or bindings for values whose changes should participate in reactivity.

Identity and Evaluation

key

fn key(self, key: impl Into<String>) -> Modified<Self>

Gives the view a stable identity within its parent. A key lets mounted state follow an item through sibling reordering, while changing the key establishes a new identity. Duplicate keys among siblings fail reconciliation.

use hera_kit::{text, v_stack, ViewExt};

let folders = v_stack().children(
    ["Inbox", "Archive"].into_iter().map(|name| text(name).key(name)),
);

Use a stable item identifier when display labels can change. Keys are scoped to the parent and do not provide a global state namespace. Structural wrappers and concrete view types still participate in mounted identity; see Mounted Identity and Lifetime.

memo

fn memo<P: Clone + PartialEq + 'static>(
    self,
    key: impl Into<String>,
    props: P,
) -> MemoView<Self, P>

Caches an evaluated subtree using a sibling-local key, explicit props, and recorded state and environment reads. The runtime can reuse the subtree when both the props and the tracked dependencies remain unchanged.

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

let remaining = 12usize;
let summary = view_fn(move |_cx| {
    Ok(text(format!("{remaining} remaining")))
}).memo("task-summary", remaining);

The plain captured count is also supplied as a prop so a changed value invalidates reuse. Include every changing nonreactive capture in the props; tracked state-backed reads need not be duplicated there. Memoization can avoid eligible body construction, but layout synchronization and reconciliation still run. See View Evaluation and Memoization for dependency recording and reuse boundaries.

Component-Specific Configuration

Methods that configure a particular component are documented with that component rather than as common ViewExt modifiers.

ComponentConfiguration reference
Layout containersChild composition, spacing, and alignment for each container.
rectangleradius, border, and fill.
textTypography, wrapping, line limits, alignment, and direction.
vector_pathfill, no_fill, fill_rule, and stroke.
scrollableaxis, indicators, and scroll_position.
text_fieldEditor dimensions, wrapping, selection, and formatting.

Backend Operations

Raw node setters such as node_frame, node_offset, and node_opacity, along with low-level filters, masks, and absolute placement, belong to the explicit backend API. They operate below ordinary view composition and are not additional methods on ViewExt.

See Backend and Migration when fixed scene geometry or a custom transport requires that interface.

Source Reference

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

  • crates/kit/src/view/modifiers.rs
  • crates/kit/src/view/visual_modifiers.rs
  • crates/kit/src/view/geometry.rs
  • crates/kit/src/view/scroll/mod.rs
  • crates/kit/src/view/primitives.rs
  • crates/kit/src/env/mod.rs
  • crates/graph/src/validation.rs
  • crates/protocol/src/scene/clip.rs
  • crates/protocol/src/scene/box_style.rs