Documentation menu

scrollable

Place eager content in a clipped viewport with wheel scrolling and draggable indicators.

A scroll container separates a visible viewport from content that can extend beyond it. The scrollable() builder supplies a vertical VStack for repeated content, while the .scrollable() extension can wrap another view when you need a different content arrangement.

Viewport Bounds

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

let list = scrollable()
    .spacing(12.0)
    .children((1..=40).map(|index| text(format!("Item {index}"))))
    .frame(320.0, 240.0);

The 320-by-240 frame establishes the viewport through which the rows are visible. Within that region, the content receives unbounded height so that all 40 rows can determine their full extent. Leaving the viewport unbounded could instead let it grow with the content, removing the overflow needed for scrolling.

Scroll Axis

The default scrolling axis is vertical. Select .axis(ScrollAxis::Horizontal) when content should extend across the viewport, or ScrollAxis::Both when it can exceed the viewport in either direction. The content's arrangement still comes from its own container.

Use the column builder for vertical repeated content. For a horizontal row, compose an h_stack and call .scrollable().axis(ScrollAxis::Horizontal) before applying the viewport frame.

Position and Indicators

Provide .scroll_position(Binding<Point>) when application code needs access to the scroll position. The container resolves that position against the content and viewport extents, clamping it to the valid range. Its draggable indicators remain available by default and can be hidden with .indicators(false).

Wheel movement that cannot be consumed by a nested container passes to its parent. This allows an inner list to stop at its boundary while an outer viewport continues scrolling.

Performance and Input Scope

The container evaluates and retains all of its content, including children outside the visible viewport. For large datasets, this eager behavior can make client evaluation and retained-scene cost significant. Measure those costs before using it for an unbounded list; the current API does not virtualize rows.

Current behavior centers on wheel input and draggable scrollbars. Do not assume kinetic touch scrolling, adaptive virtualization, or platform-native scroll physics from the component name.

See layout internals and performance.

Component-Specific Reference

The axis, indicators, and scroll_position methods are available on every ScrollView<V>. The child, children, and spacing methods belong specifically to ScrollView<VStack>, the builder returned by scrollable(). They are not available on an arbitrary view wrapped through ViewExt::scrollable.

MethodPurpose
axisSelects the dimensions in which the content can scroll.
indicatorsControls the visibility of overflow indicators.
scroll_positionConnects the scroll offset to a model binding.
childAppends one child to the built-in vertical content stack.
childrenAppends an iterator to the built-in vertical content stack.
spacingSets spacing in the built-in vertical content stack.

axis

fn axis(self, axis: ScrollAxis) -> Self

Selects ScrollAxis::Vertical, Horizontal, or Both; the default is Vertical. The scroll axis determines which content dimensions may exceed the viewport, while the content’s own container determines its arrangement. A vertical stack does not become a horizontal row simply because horizontal scrolling is enabled.

indicators

fn indicators(self, visible: bool) -> Self

Controls whether overflow indicators are shown. The default is true, allowing an overflowing viewport to display draggable indicators. Passing false hides those indicators while leaving scrolling and the viewport’s clipping behavior available.

scroll_position

fn scroll_position(self, position: Binding<Point>) -> Self

Supplies the model binding used for the requested scroll offset in logical pixels. The x and y coordinates must be finite. The container resolves the requested position against its content and viewport extents and clamps it on confirmation; a binding write is therefore not an immediate guarantee of a particular displayed offset. Without this modifier, the view owns a mounted position initialized at the origin.

child

fn child(self, child: impl View) -> Self

Appends one child to the built-in VStack when the receiver is ScrollView<VStack>. Different calls can append different view types. A scroll view wrapping another content type is configured through that content before the .scrollable() modifier is applied.

children

fn children<V: View>(self, children: impl IntoIterator<Item = V>) -> Self

Appends the iterator’s views to the built-in VStack. All items share a concrete view type and remain eagerly constructed, including items outside the visible region. Add stable keys to stateful items whose sibling order can change.

spacing

fn spacing(self, spacing: f32) -> Self

Sets the finite logical gap between children in the built-in VStack, with zero as the default. This configures content spacing rather than scrollbar geometry or the viewport’s outer insets. The method is available only on ScrollView<VStack>.

Configuration Example

use hera_kit::{scrollable, text, view_fn, Point, ScrollAxis, ViewExt};

let list = view_fn(|cx| {
    let position = cx.state("position", || Point::new(0.0, 0.0));
    Ok(scrollable()
        .axis(ScrollAxis::Vertical)
        .indicators(true)
        .scroll_position(position)
        .spacing(8.0)
        .child(text("Folders"))
        .children((0..30).map(|index| text(format!("Folder {index}"))))
        .frame(320.0, 240.0))
});

The position belongs to the parent model, while the finite frame establishes the scroll viewport. Apply scroll-specific configuration before the frame returns a common view wrapper.

Source Reference

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

  • crates/kit/src/view/scroll/mod.rs
  • crates/kit/src/view/scroll/tests.rs
  • crates/kit/src/layout/mod.rs
  • crates/kit/src/view/primitives.rs