Introduction

In this chapter, you will:

• Discover what WaterUI is and why it exists
• Understand how native rendering differs from web-view approaches
• See the full range of supported platforms and backends
• Get a taste of WaterUI with a working counter example

Pinned to upstream: every example and API name in this book is verified against waterui dev bee793e6305f (2026-05-29, “Install widget theme for webview semantics”). When the submodule bumps, the chapters bump with it.

Imagine writing your UI once in Rust and having it render as a truly native app on iOS, Android, macOS, and Linux – no web views, no custom rendering, just real platform widgets. That is what WaterUI gives you. If you have ever wished for the safety of Rust’s type system combined with the ergonomics of SwiftUI or Jetpack Compose, you are in the right place.

What is WaterUI?

WaterUI is a cross-platform, reactive, declarative UI framework for Rust. You describe what your interface should look like, and the framework takes care of how it renders – on every platform.

Unlike electron-style approaches that draw their own pixels inside a web view, WaterUI renders to native platform widgets. On Apple platforms (iOS and macOS) it bridges to SwiftUI/UIKit/AppKit through a Swift backend. On Android it bridges to Android Views via JNI/Kotlin. On Linux it delegates to GTK4. The result is an application that looks, feels, and performs like a first-class citizen on each operating system.

Rust View Tree  --->  FFI (C ABI)  --->  Native Backend  --->  Platform UI
                                          Swift / Kotlin / GTK4

Key Features

• Cross-platform: iOS, Android, macOS, and Linux from one Rust codebase. The default native backends are Apple, Android, and GTK4; Hydrolysis provides an experimental self-drawn path for macOS, Linux, Windows, and Web.
• Type-safe: Leverage Rust’s type system, ownership, and lifetimes to eliminate whole categories of runtime errors at compile time.
• Reactive: WaterUI’s Binding<T>, Computed<T>, and Signal types automatically propagate changes through the view tree so the UI stays in sync with your data.
• Declarative: Describe your UI as a composition of View values. Layout, styling, and interaction are expressed through method chaining and tuple composition rather than imperative mutation.
• Native rendering: Each backend maps Rust views to the platform’s own widgets, giving you native text rendering, accessibility, animations, and input handling for free.

Supported Backends

Note: You only need one backend to get started. Most readers begin with whichever platform they already have tooling for – macOS if you have a Mac, Linux with GTK4, or Android if you have Android Studio installed.

Framework Architecture

WaterUI is organised as a Cargo workspace. The table below lists the most important crates. You do not need to depend on them individually – the top-level waterui crate re-exports everything through waterui::prelude::*.

Backend Crates

Tip: You will rarely interact with individual crates directly. The waterui::prelude::* import gives you everything you need in day-to-day development.

Prerequisites

Before starting this book, you should be comfortable with:

• Basic Rust – ownership, borrowing, traits, generics, and closures. If you are new to Rust, we recommend working through The Rust Programming Language first.
• The command line – you will use the water CLI and cargo extensively.
• One target platform – having Xcode (for Apple targets), Android Studio (for Android), or GTK4 development libraries (for Linux) installed will let you run examples on real hardware.

How to Use This Book

The book is structured in eight parts that build on each other:

1. Getting Started – Install the toolchain, learn the CLI, create your first app, and understand the project layout.
2. Core Concepts – The View trait, WaterUI reactive state, environment-based dependency injection, and modifiers.
3. Building UIs – Text, layout, controls, forms, lists, conditional rendering, and navigation.
4. Rich Content – Media, maps, web views, and barcodes.
5. Graphics and Effects – Canvas drawing, GPU rendering, shaders, filters, particles, and gradients.
6. Advanced Patterns – Animation, gestures, async views, error handling, accessibility, internationalisation, and plugins.
7. Developer Tools – The preview system and hot reload.
8. Under the Hood – How WaterUI renders, the FFI bridge, the layout engine, and backend architecture.

Most chapters contain runnable code examples. Clone the repository and use water create "Counter" --mode playground to set up sandbox projects as you follow along. Chapters that discuss workspace-only internals call that out explicitly.

A Taste of WaterUI

Here is a minimal counter application to give you a feel for the framework:

use waterui::prelude::*;
use waterui::app::App;

pub fn main() -> impl View {
    let counter = Binding::i32(0);

    vstack((
        text!("Count: {counter}"),
        hstack((
            button("Decrement")
                .action(|State(c): State<Binding<i32>>| c.set(c.get() - 1))
                .state(&counter),
            button("Increment")
                .action(|State(c): State<Binding<i32>>| c.set(c.get() + 1))
                .state(&counter),
        )),
    ))
}

pub fn app(env: Environment) -> App {
    App::new(main, env)
}

This is the user crate’s src/lib.rs: it defines your root view and the public app(env) constructor. The CLI generates a companion FFI crate that exports the C entry points native backends need, so you do not write waterui_ffi::export!() in this file. The same Rust view code runs on the supported native targets without platform-specific #[cfg] branches.

Contributing

This book is open source. Found a typo, an unclear explanation, or want to add a chapter?

• Book source: github.com/water-rs/book
• Framework source: github.com/water-rs/waterui
• Issues and pull requests: contributions are welcome on either repository

Head to The Water CLI to install your tools and create your first project.

The Water CLI

In this chapter, you will:

• Install the water command-line tool
• Understand the difference between playground and app project modes
• Learn the key commands: create, run, build, package, and more

Every WaterUI project starts with the water CLI. It is your single entry point for creating projects, compiling Rust for mobile and desktop targets, launching apps on simulators and devices, and packaging for distribution. Think of it as cargo for cross-platform native apps – it wraps the complexity of Xcode, Gradle, and GTK4 build systems so you can focus on writing Rust.

Installation

The CLI is part of the WaterUI repository. Install it from source:

cargo install --path cli --locked

After installation, verify the tool is on your PATH:

water --help

Tip: If you are actively developing the CLI itself, use cargo build -p waterui-cli for faster iteration, then reinstall with cargo install --path cli when you need the updated binary in your PATH.

Project modes

WaterUI supports two project modes, each suited to a different stage of development. Choosing the right one upfront will save you time.

Playground mode

Playground mode is designed for quick experimentation. When you create a project with --mode playground, the CLI manages all native backend projects automatically inside the global build cache under ~/.water/build_cache/<absolute-project-path>/managed_backends/. You only write Rust.

water create "My Experiment" --mode playground

What you get on disk:

my-experiment/
  Cargo.toml
  Water.toml          # type = "playground"
  src/lib.rs
  assets/
    raw/
    images/

Playground projects:

• Auto-initialise Apple and Android backends on every water run.
• Re-scaffold backend templates automatically so manifest changes (such as permissions) are always picked up.
• Store all generated native projects in the global build cache, keeping your working directory clean and free of platform clutter.

Tip: Playground mode is what you want while following this book. It keeps the boilerplate out of your way so you can concentrate on learning WaterUI itself.

App project mode

App mode (the default) gives you explicit control over backend configuration. Native backend projects live under a backends/ directory in your project root and are checked into version control.

water create "Production App" --backends apple,android

What you get:

production-app/
  Cargo.toml
  Water.toml          # type = "app"
  src/lib.rs
  assets/
    raw/
    images/
  backends/
    apple/            # Swift Package, checked in
    android/          # Gradle project, checked in
    gtk4/             # GTK4 backend crate, checked in
    ffi/              # Generated FFI companion crate

App projects are required for:

• Customising native build settings (Xcode schemes, Gradle dependencies, etc.)
• Adding platform-specific native code
• Production deployment pipelines

Now that you understand both modes, let’s look at what the CLI can do.

Command Reference

water create

Scaffold a new WaterUI project.

# Interactive mode (prompts for name, bundle ID, backends)
water create

# Playground project
water create "Counter" --mode playground

# App project with explicit backends
water create "My App" --backends apple,android

# With custom bundle identifier
water create "My App" --bundle-id dev.waterui.myapp --backends apple

# Link to a local WaterUI checkout (for framework development)
water create "Dev App" --waterui-path ../waterui --backends apple

Arguments:

When run without arguments in an interactive terminal, the CLI prompts for each value with sensible defaults.

GTK4 app backends can only be scaffolded on Linux hosts at this checkpoint. Hydrolysis is available for macOS, Linux, Windows, and Web.

water run

This is the command you will use most often. It builds, packages, and runs the application on a target device – all in one step.

# Run on iOS Simulator (default device)
water run --platform ios

# Run on a specific iOS Simulator
water run --platform ios --device "iPhone 16 Pro"

# Run on Android (connected device or first emulator)
water run --platform android

# Run on macOS
water run --platform macos

# Run on macOS with the Hydrolysis renderer
water run --platform macos --backend hydrolysis

# Run on Linux (defaults to the GTK4 backend)
water run --platform linux

# Run on Windows
water run --platform windows

# Stream debug logs
water run --platform ios --logs debug

# Include native platform logs (verbose)
water run --platform ios --logs debug --native-logs

If you omit --platform, water run defaults to the host platform: macos on macOS, linux on Linux, and windows on Windows.

Arguments:

The default backend for each platform is:

Valid backend/platform combinations:

Note: If you have multiple simulators or emulators available, water run picks the first booted one. Use --device to target a specific device by name.

water build

Compile the Rust library for a target platform without packaging or running. This is useful in CI pipelines or when you want to check compilation without launching an app. water build only operates on app-mode projects; playground projects are built and packaged via water run and water package.

# Build for iOS device
water build --platform ios

# Build for iOS Simulator (specific architecture)
water build --platform ios-simulator --arch arm64

# Build for Android
water build --platform android --arch arm64

# Release build
water build --platform macos --release

# Build and copy to a specific output directory
water build --platform macos --output-dir ./out

Arguments:

water package

Package the application for distribution. When you are ready to ship, this is how you produce installable artifacts. --backend is required.

# Package for iOS (physical device)
water package --platform ios --backend apple

# Release build for distribution
water package --platform ios --backend apple --release --distribution

# Package for Android (must specify architecture)
water package --platform android --backend android --arch arm64

# Package for Android (multiple architectures)
water package --platform android --backend android --arch arm64,x86_64

Arguments:

water preview

Render a view function to a PNG image without launching the full application. This is useful for visual testing and documentation.

# Preview a function on macOS
water preview my_card --platform macos --path ./app

# Custom frame size
water preview dashboard --platform ios --frame 390x844

# Custom output path
water preview login_screen --platform macos --output login.png

The function must be annotated with the #[preview] attribute macro:

use waterui::prelude::*;

#[preview]
fn my_card() -> impl View {
    text("Hello Preview!")
}

Arguments:

water doctor

Not sure if your environment is set up correctly? water doctor checks everything for you.

# Check toolchain
water doctor

# Attempt to fix missing dependencies automatically
water doctor --fix

The doctor checks for:

• Rust toolchain and required targets
• Xcode and command-line tools (macOS)
• Android SDK and NDK
• GTK4 development libraries
• sccache (optional, for build caching)

Items marked [fixable] can be installed automatically with --fix.

Tip: Run water doctor any time something does not compile as expected. It often catches missing targets or outdated toolchains before you start debugging your own code.

water devices

List available simulators, emulators, and connected devices.

# List all devices across all platforms
water devices

# List only iOS simulators
water devices --platform ios

# List only Android devices and emulators
water devices --platform android

# JSON output (for scripting). --json is a global flag.
water --json devices --platform all

The output shows each device’s name, identifier, and state (booted/available).

water clean

Remove build artifacts.

# Clean all backends in the current project
water clean

# Clean only the Apple backend
water clean --backend apple

# Clean only the Android backend
water clean --backend android

# Recursively clean all WaterUI projects under a directory
water clean --recursive --path ~/projects

# Skip confirmation in recursive mode
water clean --recursive --yes

# Wipe the global managed build cache under ~/.water/build_cache
water clean --global-cache --yes

In recursive mode, the CLI finds every directory containing a valid Water.toml and clears each project’s managed build cache (for playgrounds) or target/ directory (for app projects).

water gc

Garbage-collect stale entries in the global managed build cache. Run this if playground caches under ~/.water/build_cache/ have piled up across many abandoned projects.

water gc build-cache

Next steps

With the CLI installed, continue to Installation and Setup to configure your platform toolchains, or jump straight to Your First App if you already have everything in place.

Installation and Setup

In this chapter, you will:

• Install Rust and the required cross-compilation targets
• Set up platform toolchains for Apple, Android, or Linux
• Install the Water CLI and verify everything with water doctor
• Create and run your first project to confirm the full pipeline works

Before you can build native apps with WaterUI, you need a working toolchain. This chapter walks you through every step – from installing Rust to seeing your first app launch on a real device or simulator. By the end, water doctor will give you a clean bill of health.

Note: You only need one target platform to get started. Pick the one you are most comfortable with and skip the rest for now. You can always come back and add more later.

Step 1: Install Rust

WaterUI requires Rust 1.88 or later (edition 2024). Install Rust with rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, confirm the version:

rustc --version
# rustc 1.88.0 (... 2025-...)

If your installed version is older, update:

rustup update stable

Required Rust Targets

Depending on which platforms you want to target, add the appropriate cross-compilation targets:

# iOS (physical devices)
rustup target add aarch64-apple-ios

# iOS Simulator (Apple Silicon)
rustup target add aarch64-apple-ios-sim

# iOS Simulator (Intel)
rustup target add x86_64-apple-ios

# Android (most common)
rustup target add aarch64-linux-android

# Android (emulator on Intel/AMD)
rustup target add x86_64-linux-android

# Android (older devices)
rustup target add armv7-linux-androideabi
rustup target add i686-linux-android

Tip: You do not need to add all targets right away. Start with the platform you plan to develop on first. The water doctor --fix command can install missing targets automatically.

Step 2: Editor setup

Any editor with Rust support will work. A common starting point is Visual Studio Code with the following extensions:

• rust-analyzer – code completion, inline errors, go-to-definition
• Even Better TOML – syntax highlighting for Cargo.toml and Water.toml
• CodeLLDB – native debugger for Rust

Other popular choices include RustRover (JetBrains), Zed, and Helix.

Step 3: Platform toolchains

Install the tools for every platform you intend to target. Remember, you only need one to get started – you can always add the others later.

Apple (iOS / macOS)

Requirements:

• macOS (required – Apple development tools only run on Mac)
• Xcode 16 or later
• Xcode Command Line Tools

Install Xcode from the Mac App Store, then install the command-line tools:

xcode-select --install

Verify the installation:

xcodebuild -version
# Xcode 16.x
# Build version ...

xcrun simctl list devices available
# Lists available simulators

You also need to accept the Xcode license if you have not already:

sudo xcodebuild -license accept

Warning: If you skip the license acceptance, builds will fail with a cryptic error. Save yourself the debugging and run this command now.

Android

Requirements:

• Android SDK (API level 24+)
• Android NDK (version 26+)
• Java Development Kit (JDK 17+)

The easiest path is to install Android Studio, which bundles the SDK, NDK, and an emulator. After installation:

1. Open Android Studio and go to Settings > Languages & Frameworks > Android SDK.
2. Under the SDK Platforms tab, install at least one recent API level (e.g. Android 14, API 34).
3. Under the SDK Tools tab, ensure NDK (Side by side) and Android SDK Command-line Tools are installed.

Set the required environment variables. Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ANDROID_HOME="$HOME/Library/Android/sdk"  # macOS default
# export ANDROID_HOME="$HOME/Android/Sdk"        # Linux default

export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/<version>"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools/bin:$PATH"

Verify:

adb --version
# Android Debug Bridge version ...

emulator -list-avds
# Lists available Android Virtual Devices

If you do not have an AVD yet, create one through Android Studio’s Device Manager or via the command line:

avdmanager create avd -n Pixel_9 -k "system-images;android-34;google_apis;arm64-v8a"

Linux (GTK4)

Requirements:

• GTK4 development libraries (4.x)
• pkg-config

On Debian/Ubuntu:

sudo apt install libgtk-4-dev pkg-config

On Fedora:

sudo dnf install gtk4-devel pkg-config

On Arch Linux:

sudo pacman -S gtk4 pkgconf

On macOS (for running GTK4 apps locally):

brew install gtk4 pkg-config

Verify:

pkg-config --modversion gtk4
# 4.x.x

Step 4: Install the Water CLI

Clone the WaterUI repository and install the CLI:

git clone https://github.com/water-rs/waterui.git
cd waterui
cargo install --path cli --locked

Verify the installation:

water --help

Step 5: Verify with water doctor

This is the moment of truth. Run the doctor command to check your entire toolchain at once:

water doctor

You will see output like:

Checking development environment...
  ✓ Rust toolchain
  ✓ Xcode Command Line Tools
  ✓ iOS Simulator SDK
  ✓ Android SDK
  ✓ Android NDK
  ✓ GTK4
  ✓ sccache

All checks passed!

If any checks fail, items marked [fixable] can be repaired automatically:

water doctor --fix

For items that cannot be auto-fixed, the doctor output includes instructions for manual installation.

Tip: Bookmark this command. It is your first line of defense whenever something goes wrong with your build environment.

Step 6: Discover your devices

See which simulators, emulators, and physical devices are available:

water devices

Example output:

iOS Simulators
  ● iPhone 16 Pro (A1B2C3D4-...)
  ○ iPad Air (E5F6G7H8-...)

Android
  ○ Pixel_9 (emulator)

macOS
  ● Current Machine

Booted/connected devices are marked with a filled circle. Devices that need to be launched first are marked with an open circle. The water run command handles launching automatically.

Step 7: Create your first project

With everything in place, confirm the full pipeline works end-to-end. Create a playground project and run it:

water create "Hello World" --mode playground
cd hello-world
water run --platform macos

If you have an iOS Simulator available:

water run --platform ios

Or Android:

water run --platform android

You should see the default WaterUI demo application running on your chosen platform. The demo includes a counter, a form, controls, and a progress indicator – all rendered with native platform widgets.

Tip: If the app launches successfully, your environment is fully set up. If it does not, check the terminal output for errors and re-run water doctor to diagnose the issue.

Optional: build caching with sccache

WaterUI projects cross-compile for multiple architectures, which means you often recompile the same crates. sccache caches compilation results and can significantly speed up rebuilds.

# macOS
brew install sccache

# Linux
cargo install sccache

The Water CLI detects sccache automatically and uses it when available. If it is not found, you will see a warning:

  ⚠ sccache not found. Build efficiency may be reduced. Install with: brew install sccache

Troubleshooting

“No iOS simulators available”

You need to download a simulator runtime in Xcode:

1. Open Xcode.
2. Go to Settings > Platforms.
3. Click the + button and download an iOS Simulator runtime.

“Android emulator not found”

Ensure ANDROID_HOME is set correctly and that you have at least one AVD created. See the Android section above.

“GTK4 not found”

Install the GTK4 development libraries for your operating system. See the Linux section above. On macOS, brew install gtk4 is required if you want to use the GTK4 backend.

Permission denied when running water

Make sure the cargo bin directory is on your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Next steps

Your development environment is ready. Continue to Your First App to build a counter application step by step and learn the fundamental WaterUI patterns along the way.

Your First App

In this chapter, you will:

• Build a counter application from scratch
• Learn how views, layout stacks, and reactive state work together
• Add buttons with actions that update the UI automatically
• Run the same code on macOS, iOS, Android, and Linux

There is no better way to learn a UI framework than to build something with it. In this chapter, you will create a counter app – simple enough to understand in one sitting, but rich enough to introduce the core WaterUI patterns you will use in every project: views, layout, reactive state, and user interaction.

Create the project

Scaffold a playground project:

water create "Counter" --mode playground
cd counter

This generates the following files:

counter/
  Cargo.toml
  Water.toml
  src/lib.rs
  assets/
    raw/
    images/

Open src/lib.rs in your editor. The template includes a full demo app, but you will replace it with your own code, building it up step by step.

Step 1: a minimal view

Replace the contents of src/lib.rs with the simplest possible WaterUI app:

use waterui::app::App;
use waterui::prelude::*;

fn main() -> impl View {
    "Hello, WaterUI!"
}

pub fn app(env: Environment) -> App {
    App::new(main, env)
}

Here is what each piece does:

• use waterui::prelude::* imports all commonly used items: View, Environment, Binding, layout functions, control constructors, macros, and more.
• fn main() -> impl View is the root view function. It returns any type that implements the View trait. A &'static str implements View, so a bare string literal is a valid view that renders as text.
• pub fn app(env: Environment) -> App is the application entry point. The native backends call this function through the generated FFI companion crate to obtain the App instance. The Environment is passed in by the backend and carries platform-provided services such as theme information.

You do not need to write waterui_ffi::export!() yourself. In playground mode, the CLI generates an FFI companion crate behind the scenes that calls your app(env) function and exports the C entry points the native backends expect. In app mode, the same companion lives at backends/ffi/.

Run it:

water run --platform macos

You should see a window displaying “Hello, WaterUI!” rendered with native platform text.

Tip: Try changing the string to something else and re-running water run. Each invocation rebuilds the project incrementally.

Step 2: using the text view

String literals work, but the text() function and text! macro give you control over styling and reactive interpolation. Use text() for static strings and text! whenever the displayed value depends on a reactive binding.

fn main() -> impl View {
    text("Hello, WaterUI!").bold().title()
}

The text() function creates a Text view. Method calls chain to configure it:

• .bold() sets the font weight to bold.
• .title() selects the platform’s title font preset.
• Other options include .size(24.0), .italic(true), .underline(true), .headline(), .caption(), and more.

Now that you can display styled text, arrange multiple views together.

Step 3: layout with vstack and hstack

A single text view is not much of an app. WaterUI uses stacks to arrange views:

• vstack((...)) arranges children vertically (top to bottom).
• hstack((...)) arranges children horizontally (left to right).

Children are passed as a tuple:

fn main() -> impl View {
    vstack((
        text("Counter App").bold().title(),
        "A simple counting application",
    ))
}

vstack accepts a tuple of views. Each element can be a different type – the framework composes them without forcing you to box the children.

Tip: Try nesting an hstack inside a vstack to see how stacks compose. This nesting pattern is how you build complex layouts in WaterUI.

Step 4: adding reactive state

Now for the interesting part. WaterUI uses reactive bindings to manage state. When a binding’s value changes, any view that depends on it updates automatically – no manual refresh calls, no diffing.

Create a binding with one of the typed Binding constructors:

fn main() -> impl View {
    let counter = Binding::i32(0);

    vstack((
        text("Counter App").bold().title(),
        text!("Count: {counter}"),
    ))
}

Key concepts:

• Binding::i32(0) creates a Binding<i32> initialised to 0. There are typed constructors for the common primitive shapes: Binding::i32, Binding::u32, Binding::f64, Binding::bool. For heap types such as String, use Binding::container(String::new()). There is no Binding::new.
• text!("Count: {counter}") is the text! macro. It only accepts named placeholders that match a binding in scope (or an explicit alias such as text!("Count: {n}", n = counter)). When counter changes, the text updates automatically.

Important: Do not call .get() on signals directly inside a view body. Doing so reads the value once and breaks reactivity. Instead, use text!, watch(), .map(), or .zip() to create derived signals that track changes.

The display updates, but there is no way to change the count yet. Add some buttons.

Step 5: buttons and actions

A counter needs buttons. The button() function creates a Button view:

pub fn main() -> impl View {
    let counter = Binding::i32(0);

    vstack((
        text("Counter App").bold().title(),
        text!("Count: {counter}"),
        hstack((
            button("Decrement")
                .action(|State(c): State<Binding<i32>>| c.set(c.get() - 1))
                .state(&counter),
            button("Increment")
                .action(|State(c): State<Binding<i32>>| c.set(c.get() + 1))
                .state(&counter),
        )),
    ))
}

Breaking down the button pattern:

1. button("Increment") creates a button with a text label. The label can be any View, not just a string.
2. .action(|State(c): State<Binding<i32>>| ...) runs when the button is clicked. Each State<T> parameter extracts the matching injected value from the environment, in the order it was injected.
3. .state(&counter) injects the counter binding into the button’s environment. Chain multiple .state(...) calls to inject multiple values – each becomes available to the action closure through a State<T> parameter.

Inside the action, c.get() reads the current value and c.set(...) writes a new one. The write triggers the reactive system, which updates the text!("Count: {counter}") view.

Run this and you have a working counter. Click the buttons and watch the count change in real time.

Button styles

Buttons support several visual styles:

// Primary action (filled background)
button("Submit").bordered_prominent().action(|| { /* ... */ });

// Secondary action (bordered)
button("Cancel").bordered().action(|| { /* ... */ });

// Link style (hyperlink appearance)
button("Learn more").link().action(|| { /* ... */ });

// Plain (no background or border)
button("Skip").plain().action(|| { /* ... */ });

Tip: Try changing .bordered_prominent() to .link() on one of your counter buttons to see how the style affects the appearance on your platform.

Async actions

For actions that need to perform asynchronous work, use action_async:

button("Fetch Data")
    .action_async(|| async {
        let data = fetch_from_server().await;
        process(data);
    });

Step 6: adding a spacer

Use spacer() to push views apart within a stack:

pub fn main() -> impl View {
    let counter = Binding::i32(0);

    vstack((
        text("Counter App").bold().title(),
        spacer(),
        text!("Count: {counter}").size(48.0),
        spacer(),
        hstack((
            button("Decrement")
                .bordered()
                .action(|State(c): State<Binding<i32>>| c.set(c.get() - 1))
                .state(&counter),
            spacer(),
            button("Increment")
                .bordered_prominent()
                .action(|State(c): State<Binding<i32>>| c.set(c.get() + 1))
                .state(&counter),
        )),
    ))
}

Spacers are flexible – they expand to fill all remaining space. In this layout:

• The two spacer() calls in the vstack push the title to the top and the buttons to the bottom, centering the count in between.
• The spacer() in the hstack pushes the two buttons to opposite edges.

The complete counter app

Here is the full src/lib.rs:

use waterui::app::App;
use waterui::prelude::*;

pub fn main() -> impl View {
    let counter = Binding::i32(0);

    vstack((
        text("Counter App").bold().title(),
        spacer(),
        text!("Count: {counter}").size(48.0),
        spacer(),
        hstack((
            button("Decrement")
                .bordered()
                .action(|State(c): State<Binding<i32>>| c.set(c.get() - 1))
                .state(&counter),
            spacer(),
            button("Increment")
                .bordered_prominent()
                .action(|State(c): State<Binding<i32>>| c.set(c.get() + 1))
                .state(&counter),
        )),
    ))
    .padding()
}

pub fn app(env: Environment) -> App {
    App::new(main, env)
}

Note the .padding() call at the end – this adds platform-appropriate padding around the entire stack, preventing content from touching the screen edges.

Tip: Try extending this app on your own. Add a “Reset” button that sets the counter back to zero, or make the increment step configurable with a second binding.

Running on different platforms

The same code runs on every supported platform:

# macOS
water run --platform macos

# iOS Simulator
water run --platform ios

# Android
water run --platform android

# Linux (GTK4)
water run --platform linux

Each platform renders the counter using its own native widgets. The buttons look like iOS buttons on iOS, Material buttons on Android, and GTK4 buttons on Linux. You did not write a single line of platform-specific code.

Concepts recap

Next steps

Continue to Project Structure and Water.toml to see how WaterUI projects are organised, what goes in the Water.toml manifest, and how assets and fonts are managed.

Project structure and Water.toml

In this chapter, you will:

• Understand how playground and app projects are laid out on disk
• Learn every section of the Water.toml manifest
• Discover how assets, fonts, and permissions are managed
• Know when to switch from playground to app project mode

Every WaterUI project follows a consistent layout. Understanding this structure early will save you time when you need to add assets, configure permissions, or prepare for production. This chapter covers both project modes, the Water.toml and Cargo.toml manifests, and the asset system.

Playground project layout

When you create a project with --mode playground, the on-disk layout is minimal. This is the mode you have been using throughout this tutorial:

my-app/
  Cargo.toml           # Rust crate configuration
  Water.toml           # WaterUI project manifest
  src/
    lib.rs             # Your application code
  assets/
    raw/               # Arbitrary files (JSON, fonts, data)
    images/            # Image resources

The generated native backend projects live outside your project tree, in the global managed cache at:

~/.water/build_cache/<absolute-project-path>/managed_backends/
  apple/               # Generated Apple backend (Swift Package)
  android/             # Generated Android backend (Gradle project)
  ffi/                 # Generated FFI companion crate
  preview_ffi/         # Generated preview wrapper crate

Key characteristics:

• You only edit Rust files and assets. The native backend projects in the global cache are generated and managed by the CLI.
• The cache is rebuilt on every water run. Changes to Water.toml (such as adding permissions) flow into the native projects automatically.
• Backend configuration is not allowed in Water.toml. The [backends] section must be absent for playground projects.
• Permissions are configured in Water.toml. The [permissions] section is only available in playground mode.

Tip: Playground mode is ideal for learning, prototyping, and following this book’s examples. You do not need to think about native build systems at all. To reclaim disk space across abandoned playgrounds, run water gc build-cache or water clean --global-cache --yes.

App project layout

When you need more control – custom Xcode settings, platform-specific native code, or CI/CD integration – create a project with explicit --backends. The native projects live inside your repository under a backends/ directory:

my-app/
  Cargo.toml
  Water.toml
  src/
    lib.rs
  assets/
    raw/
    images/
  backends/
    apple/             # Swift Package (checked in)
      Package.swift
      Sources/
      ...
    android/           # Gradle project (checked in)
      app/
      build.gradle.kts
      ...
    gtk4/              # GTK4 backend crate (checked in)
    ffi/               # FFI companion crate (checked in)

Key characteristics:

• Backend directories are version-controlled. You can customise native build settings, add platform-specific code, and manage backend dependencies.
• The [backends] section in Water.toml tracks which backends are configured and their per-backend settings.
• Permissions are managed in native projects directly (Info.plist for Apple, AndroidManifest.xml for Android).

Now let’s look at the configuration files that tie everything together.

Water.toml

The Water.toml file is the central configuration for a WaterUI project. It is a TOML file with the following sections.

[package]

The [package] section defines the application identity:

[package]
type = "playground"          # or "app"
name = "My Application"
bundle_identifier = "dev.waterui.myapp"

Fields:

[backends]

The [backends] section is only present in app (type = "app") projects. It is populated when you run water create with --backends, or when you add a backend to an existing project with water backend add <name>.

[backends]
path = "backends"            # Base path for backend directories (relative to project root)

[backends.apple]
# Apple backend configuration (auto-generated)

[backends.android]
# Android backend configuration (auto-generated)

[backends.gtk4]
# GTK4 backend configuration (auto-generated)

For playground projects, this section must be absent. The CLI stores backend data in the global build cache instead.

Warning: Adding a [backends] section to a playground project or a [permissions] section to an app project causes the CLI to reject the manifest with an error. Each mode has its own configuration approach.

waterui_path

For framework developers who work on WaterUI itself, the waterui_path field points to a local checkout of the WaterUI repository:

waterui_path = "../waterui"

When set, all backends use this local path instead of published crate versions. The CLI sets this automatically when you create a project with --waterui-path.

[permissions]

The [permissions] section is only available in playground mode. It provides a declarative way to request native platform permissions without editing native project files:

[permissions.camera]
enable = true
description = "Required for barcode scanning"

[permissions.location]
enable = true
description = "Used to show nearby stores"

[permissions.microphone]
enable = true
description = "Needed for voice recording"

Each permission entry has two fields:

When water run rebuilds a playground project, it reads these permissions and injects the appropriate entries into Info.plist (Apple) and AndroidManifest.xml (Android) automatically.

For app projects (type = "app"), permissions are managed directly in the native project files. Attempting to use [permissions] in an app project causes the CLI to reject the manifest with an error.

Note: Always write clear, user-facing descriptions for permissions. Vague descriptions like “We need this” will get your app rejected from app stores. Explain why the permission is needed in terms the user understands.

Cargo.toml

The Cargo.toml file is a standard Rust crate manifest. When water create scaffolds a project, it generates a Cargo.toml that:

• Defines a plain library crate (crate-type = ["lib"]). The CLI generates a separate FFI companion crate that handles staticlib/cdylib exports, so your user crate stays a normal Rust library.
• Depends on waterui with the assets, media, webview, and flow-markdown features enabled on native targets.
• Uses Rust edition 2024.

A minimal generated Cargo.toml looks like:

[package]
name = "counter"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["lib"]

[dependencies]
waterui = { version = "0.2", default-features = false }

[target."cfg(not(target_arch = \"wasm32\"))".dependencies]
waterui = { version = "0.2", default-features = false, features = ["assets", "media", "webview", "flow-markdown"] }

[features]
dev = ["waterui/dynamic_linking"]

Font management

Custom fonts are declared in Cargo.toml metadata so the build system can bundle them into native projects:

[[package.metadata.waterui.assets.font]]
name = "Inter"
local_path = "assets/raw/Inter-Variable.ttf"

[[package.metadata.waterui.assets.font]]
name = "JetBrainsMono"
local_path = "assets/raw/JetBrainsMono-Regular.ttf"

Each entry declares a font family name and either a local_path (relative to the crate root) or a remote_path URL the CLI downloads on demand. The Water CLI reads this metadata during packaging and copies the font files into the appropriate locations for each native backend. Built-in font names such as Inter, Roboto, JetBrainsMono, FiraCode, and SourceCodePro resolve from the registry automatically when neither path is provided.

Tip: Place local font files in assets/raw/ and declare them here. WaterUI handles bundling them into every platform’s app package automatically – no need to configure Xcode or Gradle font resources manually.

Asset Directory Layout

WaterUI enforces a strict asset layout to ensure cross-platform compatibility. All assets live under the directory specified by package.assets_path (default: assets/).

assets/
  raw/             # Arbitrary files: JSON, fonts, data files, etc.
    data.json
    Inter-Variable.ttf
  images/          # Image resources
    logo.png
    [email protected]

assets/raw/

Files placed here are bundled as-is into the application package. Use this for:

• Custom fonts (.ttf, .otf)
• Data files (.json, .csv, .toml)
• Shaders (.wgsl, .metal)
• Any other non-image resource

assets/images/

Image files placed here are processed by the asset pipeline. The pipeline handles:

• Resolution variants (@2x, @3x suffixes)
• Format conversion as needed per platform

The Application Entry Point

Every WaterUI application requires three things in src/lib.rs. You have seen all three in the previous chapter, but let’s formalise them here.

1. The Root View Function

A function that returns impl View:

fn main() -> impl View {
    text("Hello, World!")
}

The name main is a convention, not a requirement. You can name it anything.

2. The App Constructor

A public function named app that takes an Environment and returns an App:

pub fn app(env: Environment) -> App {
    App::new(main, env)
}

The App struct holds the application’s windows and environment. The simplest form creates a single window with a default title. You can customise:

pub fn app(env: Environment) -> App {
    App::new(main, env).title("My Counter App")
}

For multi-window applications:

use waterui::app::App;
use waterui::prelude::*;
use waterui::window::Window;
use waterui::window::WindowState;

fn main_view() -> impl View { text("Main") }
fn settings_view() -> impl View { text("Settings") }
pub fn app(env: Environment) -> App {
    App::new_with_windows(
        [
            Window::new("Main", Binding::container(WindowState::Normal), main_view),
            Window::new("Settings", Binding::container(WindowState::Normal), settings_view),
        ],
        env,
    )
}

3. The generated FFI companion

Your user crate stops at app(env). The CLI generates a separate FFI companion crate in the managed backend cache for playground projects, or in backends/ffi/ for app projects. That companion depends on your crate and waterui-ffi, calls the export macro, and exposes the C-ABI functions native backends load.

Do not add waterui_ffi::export!() to src/lib.rs; it belongs in the generated companion crate, not in your application crate.

Putting It All Together

A complete, well-structured project looks like this:

my-app/
  Cargo.toml
  Water.toml
  src/
    lib.rs             # Entry point: main(), app(), export!()
    views/
      mod.rs           # View module declarations
      home.rs          # Home screen view
      settings.rs      # Settings screen view
  assets/
    raw/
      config.json
    images/
      logo.png

# Water.toml
[package]
type = "playground"
name = "My App"
bundle_identifier = "dev.waterui.myapp"

# Cargo.toml
[package]
name = "my-app"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["lib"]

[dependencies]
waterui = { version = "0.2", default-features = false }

[target."cfg(not(target_arch = \"wasm32\"))".dependencies]
waterui = { version = "0.2", default-features = false, features = ["assets", "media", "webview", "flow-markdown"] }

[features]
dev = ["waterui/dynamic_linking"]

// src/lib.rs
use waterui::prelude::*;
use waterui::app::App;

mod views;

fn main() -> impl View {
    views::home()
}

pub fn app(env: Environment) -> App {
    App::new(main, env).title("My App")
}

Playground vs Full: When to Switch

Start with playground mode for:

• Learning and experimentation
• Prototyping ideas
• Small personal projects
• Following this book’s examples

Switch to full project mode when you need:

• Custom native build settings
• Platform-specific native code (Swift/Kotlin extensions)
• CI/CD integration with native build tools
• App Store or Play Store submission
• Fine-grained control over backend dependencies

To move from playground to app mode, create a fresh app project with the backends you want and move your src/, assets/, and manifest settings over. If you intentionally want to keep generated native projects, copy them from the managed cache at ~/.water/build_cache/<absolute-project-path>/managed_backends/, set type = "app", and add a matching [backends] section.

Tip: There is no rush to switch. Many developers stay in playground mode well into development and only convert when they are ready to customise native settings for release.

What’s Next

With a solid understanding of how WaterUI projects are structured, you are ready to dive into the framework’s core concepts. In The View System, you will learn how the View trait works, how views compose, and how the framework turns your Rust types into platform-native UI.

The view system

In this chapter, you will:

• Understand the View trait and how WaterUI builds UIs from composable pieces
• Learn to create views using functions, structs, and built-in types
• Discover how AnyView solves Rust’s type system challenges for dynamic UIs
• See how raw views and composite views work together to form the rendering tree

Every piece of UI you see on screen – a text label, a button, a card, an entire page – is a View in WaterUI. Views are composable, declarative descriptions of what the screen should look like. You describe what you want, and the framework figures out how to render it.

If you have used SwiftUI or Jetpack Compose, this will feel familiar. If not, do not worry – the concept is straightforward, and this chapter will walk you through it from the ground up.

The View trait

At the heart of WaterUI lies a single trait:

pub trait View: 'static {
    fn body(self, env: &Environment) -> impl View;
}

A View consumes itself and, given an Environment, produces another View. The framework calls body() recursively until it reaches a raw view – a leaf node that the native backend knows how to render (such as Text, Button, or Color).

Key properties:

• Consuming: body takes self by value. Views are cheap descriptors, created and consumed during rendering.
• Contextual: The Environment carries dependency-injected values such as theme tokens, locale, and your own configuration.
• Recursive: Composite views return other views, which themselves have bodies. The recursion terminates at raw views.
• 'static bound: Views own all their data. No borrowed references, which keeps the lifecycle simple.

Note: 'static does not mean “lives forever”. It means views cannot hold temporary references. Wrap shared mutable data in a Binding.

Function views

The simplest way to create a view is with a plain function. Any FnOnce() -> V where V: View automatically implements View:

use waterui::prelude::*;

fn greeting() -> impl View {
    "Hello, World!" // &'static str implements View
}

Function views are the recommended starting point. They compose naturally and work with Rust’s type inference:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn counter(count: Binding<i32>) -> impl View {
    vstack((
        text!("Count: {count}"),
        button("Increment")
            .action(|State(count): State<Binding<i32>>| count.set(count.get() + 1))
            .state(&count),
    ))
}

text!("Count: {count}") captures the count binding from scope and rebuilds the rendered text whenever it changes. There is no need to wrap text construction in Dynamic::watch – the macro already takes care of subscribing to the signal.

Tip: Start with function views. Most components never need to become structs.

Struct views

When a component needs named configuration fields or builder-pattern ergonomics, define it as a struct:

use waterui::prelude::*;
use waterui::widget::condition::when;

struct ProfileCard {
    name: Binding<String>,
    avatar_url: Str,
    show_bio: bool,
}

impl View for ProfileCard {
    fn body(self, env: &Environment) -> impl View {
        let Self { name, avatar_url, show_bio } = self;
        vstack((
            text!("{name}"),
            when(show_bio, || text!("Bio goes here")),
        ))
    }
}

Struct views shine when:

• The component has multiple configuration parameters.
• You want a clear, self-documenting API surface.
• The component is reused across many call sites with varying configurations.

Built-in view implementations

You do not always need to define your own views. Several standard types implement View directly:

Tip: Option<V> is the simplest way to conditionally render. For full if/elif/else, use when(...).or(...).otherwise(...) from waterui::widget::condition instead of branching to AnyView.

The IntoView trait

IntoView converts arbitrary types into views within a given environment:

pub trait IntoView {
    type Output: View;
    fn into_view(self, env: &Environment) -> Self::Output;
}

Every View automatically implements IntoView (returning itself). The trait is useful for APIs that want to accept “anything that can become a view” while still allowing environment-aware conversions.

The TupleViews trait

When you build layouts, you often want to pass multiple children of different types to a container. TupleViews converts tuples of views (and Vec<V> / [V; N]) into a Vec<AnyView>:

pub trait TupleViews {
    fn into_views(self) -> Vec<AnyView>;
}

It is implemented for tuples up to 15 elements:

use waterui::prelude::*;

vstack((
    text!("Title"),
    button("Click me").action(|| {}),
    Color::red().height(2.0),
))

Layout containers also accept Vec<V> and [V; N] as children of a uniform type:

use waterui::prelude::*;

let items: Vec<_> = (0..5).map(|i| text!("Row {i}").anyview()).collect();
vstack(items)

Note: Tuples allow heterogeneous children (each element can be a different type). Vec and arrays require a single element type, so erase to AnyView if needed.

AnyView: type erasure

Rust requires every branch of an if/match to return the same type. AnyView erases the concrete type so heterogeneous branches can share a return type:

pub struct AnyView(Box<dyn AnyViewImpl>);

Create one with AnyView::new or the .anyview() modifier from ViewExt:

use waterui::prelude::*;

fn conditional_view(show_detail: bool) -> AnyView {
    if show_detail {
        text!("Detailed information here").anyview()
    } else {
        text!("Summary").anyview()
    }
}

AnyView::new automatically unwraps a nested AnyView, so wrapping is idempotent. It also supports inspection and downcasting:

use core::any::TypeId;
use waterui::prelude::*;

let view = text("hello").anyview();

assert!(view.is::<waterui::text::Text>());
assert_eq!(view.type_id(), TypeId::of::<waterui::text::Text>());

if let Some(text_view) = view.downcast_ref::<waterui::text::Text>() {
    let _ = text_view;
}

Tip: Prefer when(...).otherwise(...) over if/else with .anyview(). AnyView incurs a heap allocation and dynamic dispatch – reach for it only when you really do need heterogeneous storage.

Raw views vs composite views

WaterUI distinguishes two categories of views.

Raw views (leaf nodes)

Raw views are recognized by the backend and mapped to platform widgets. Their body() wraps the value in Native<T>, which the renderer intercepts before recursion. Examples: Str, Color, Spacer, Divider, and configuration structs like ButtonConfig.

The raw_view! macro implements both NativeView and View for a type:

// Default stretch axis (None) -- content-sized
raw_view!(MyCustomLeaf);

// Explicit stretch axis -- fills available space
raw_view!(Color, StretchAxis::Both);
raw_view!(Spacer, StretchAxis::MainAxis);

Composite views

Composite views have a meaningful body() that returns other views. The framework calls body() to expand them, recursing until it reaches raw views. Every function view and every struct that implements View manually is composite.

Tip: Think HTML: raw views are native elements (<div>, <input>, <img>), composite views are your custom components.

ConfigurableView and ViewConfiguration

Some raw views support hook-based theming through ConfigurableView and ViewConfiguration. This is how WaterUI lets you restyle built-in components without modifying their source.

pub trait ConfigurableView: View {
    type Config: ViewConfiguration;
    fn config(self) -> Self::Config;
}

pub trait ViewConfiguration: 'static {
    type View: View;
    fn render(self) -> Self::View;
}

When a configurable view’s body() runs:

1. It extracts its Config.
2. It looks up Hook<Config> in the Environment.
3. If a hook is present, the hook returns the custom view.
4. Otherwise the default native rendering is used.

A theme plugin installs hooks for ButtonConfig, ToggleConfig, etc., and the rest of your app stays untouched.

The configurable! macro

configurable! generates the boilerplate for a hookable raw view:

// Basic -- content-sized view
configurable!(Button, ButtonConfig);

// With explicit stretch axis
configurable!(Slider, SliderConfig, StretchAxis::Horizontal);

// With dynamic stretch axis based on configuration
configurable!(Progress, ProgressConfig, |config| match config.style {
    ProgressStyle::Linear => StretchAxis::Horizontal,
    ProgressStyle::Circular => StretchAxis::None,
});

It generates the wrapper struct, the ConfigurableView and ViewConfiguration impls, the NativeView impl, the View impl that consults Hook<Config>, and the From<Config> conversion.

Note: You will rarely call configurable! in application code. It is primarily for building component libraries or custom backends.

Putting it together

Here is a small example combining function views, struct views, conditionals, and reactive state:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn header(title: &'static str) -> impl View {
    text(title)
        .padding()
        .background(Color::blue())
        .foreground(Color::srgb(255, 255, 255))
}

struct ItemRow {
    label: Str,
    count: Binding<i32>,
    highlighted: bool,
}

impl View for ItemRow {
    fn body(self, env: &Environment) -> impl View {
        let Self { label, count, highlighted } = self;
        hstack((
            text(label),
            Spacer::flexible(),
            text!("{count}"),
        ))
        .padding()
        .background(when(highlighted, || Color::yellow().with_opacity(0.3)))
    }
}

fn shopping_list() -> impl View {
    let apples = Binding::i32(3);
    let bananas = Binding::i32(7);

    vstack((
        header("Shopping List"),
        ItemRow { label: "Apples".into(),  count: apples,  highlighted: true  },
        ItemRow { label: "Bananas".into(), count: bananas, highlighted: false },
    ))
}

Try adding an “Oranges” row and watch the layout pick it up automatically.

Next up: reactive state. The next chapter introduces Binding, Computed, and the signal combinators that drive UI updates.

Reactive state

In this chapter, you will:

• Learn how Binding<T> gives your views mutable, reactive state
• Understand how Computed<T> and signal combinators derive new values from existing ones
• Use macros like s! and text! for reactive string formatting and localization
• Discover List<T> for reactive collections and #[derive(Project)] for struct decomposition
• Master the “golden rule” of reactivity that prevents subtle bugs

Imagine a counter app. The user taps a button and the number on screen updates instantly – no manual DOM manipulation, no message passing, no diffing algorithm. You change the data; the UI follows.

WaterUI delivers that through waterui::reactive, a fine-grained reactivity system re-exported by the top-level waterui crate. It provides signals, bindings, collections, and combinators so your views update automatically when data changes. This chapter walks through every reactive primitive you will use day to day.

The Signal trait

At the foundation of WaterUI reactivity is the Signal trait:

pub trait Signal: Clone + 'static {
    type Output;
    type Guard;

    fn get(&self) -> Self::Output;
    fn watch(&self, watcher: impl Fn(Context<Self::Output>) + 'static) -> Self::Guard;
}

• get() returns the current value synchronously.
• watch() registers a callback that fires whenever the value changes. It returns a guard – dropping the guard unsubscribes the watcher.
• Context<T> wraps the new value along with optional metadata (e.g., animation hints). Call ctx.into_value() to extract the raw value.

Every reactive type in waterui::reactive implements Signal. This uniform interface is what makes the combinator system work – any signal can be mapped, zipped, filtered, or composed with any other signal.

Binding<T>: mutable reactive state

Binding<T> is the primary mutable state container. It is readable as a Signal and writable. Think of it as a reactive variable: read the current value, write a new value, and watchers get notified automatically.

Creating bindings

use waterui::prelude::*;
use waterui::Str;

// Typed constructors for primitives
let count = Binding::i32(0);
let ratio = Binding::f64(3.14);
let flag = Binding::bool(true);

// Container constructor for complex types
let name = Binding::container(String::from("Alice"));
let title = Binding::container(Str::from("Welcome"));

// Default value
let items: Binding<Vec<String>> = Binding::default();

Use the typed constructors (Binding::i32, Binding::u32, Binding::i64, Binding::u64, Binding::isize, Binding::usize, Binding::f32, Binding::f64, Binding::bool) for primitives, and Binding::container(value) for everything else (String, Str, Vec<T>, Option<T>, your own types).

Reading values

use waterui::prelude::*;

let count = Binding::i32(10);
let current = count.get(); // 10

Writing values

use waterui::prelude::*;

let count = Binding::i32(0);

// Direct set
count.set(42);

// Set with Into conversion
let name = Binding::container(String::from("Alice"));
name.set_from("Bob"); // &str -> String automatically

// Arithmetic operations on numeric bindings
count.add_assign(5);   // count += 5
count.sub_assign(2);   // count -= 2
count.mul_assign(3);   // count *= 3
count.div_assign(2);   // count /= 2
count.rem_assign(3);   // count %= 3

// Bitwise operations on integer bindings
count.bitand_assign(0xFF);
count.bitor_assign(0x10);
count.bitxor_assign(0x01);
count.shl_assign(2);
count.shr_assign(1);

// Append to a string-like or vec-like binding
let text = Binding::container(String::from("Hello"));
text.append(" World"); // "Hello World"

Mutating In Place

For complex mutations, use with_mut or get_mut:

let items = Binding::container(vec!["a".to_string(), "b".to_string()]);

// with_mut -- preferred, avoids extra clone for Container bindings
items.with_mut(|vec| {
    vec.push("c".into());
    vec.sort();
});

// get_mut -- returns a guard that writes back on drop
*count.get_mut() += 10; // modify and auto-commit

// IMPORTANT: Do NOT bind get_mut() to `let _`
// let _ = count.get_mut(); // This keeps the guard alive until scope end!
// Instead, use the one-liner pattern above.

Warning: Be careful with get_mut(). The returned guard writes the value back when it is dropped. If you accidentally bind it to a variable, the write-back is delayed until the variable goes out of scope, which can cause surprising behavior.

The with_mut method is more efficient for Container-backed bindings because it avoids an intermediate clone.

take()

Extract the value and replace it with the default:

let name = Binding::container("hello".to_string());
let taken = name.take(); // taken == "hello", name is now ""

Now that you know how to read and write bindings, let’s look at the specialized methods available for common types.

Boolean Bindings

Binding<bool> has specialized methods that make working with toggles and flags ergonomic:

let dark_mode = Binding::bool(false);

dark_mode.toggle();     // false -> true
let light = dark_mode.reverse(); // Binding<bool> that is always the opposite

// Conditional selection
let theme = dark_mode.bidirectional_select("dark".to_string(), "light".to_string());
// theme.get() == "dark" when dark_mode is true

// Produce Option from bool
let username = dark_mode.then("admin".to_string());
// Some("admin") when true, None when false

// Logical NOT via operator
let enabled = !dark_mode; // same as dark_mode.reverse()

Option Bindings

Binding<Option<T>> provides unwrapping helpers so you do not have to manually match on Some/None:

let maybe_name = Binding::container::<Option<String>>(None);

// Unwrap with default
let name = maybe_name.unwrap_or("Anonymous".to_string());
let name = maybe_name.unwrap_or_default();
let name = maybe_name.unwrap_or_else(|| generate_name());

// Check equality through Option
let is_alice = maybe_name.some_equal_to("Alice".to_string());

Setting a value on the unwrapped binding wraps it in Some automatically.

Numeric Bindings

For PartialOrd types:

let volume = Binding::container(0.5f32);

// Only accept values in range (reject out-of-range sets)
let safe = volume.range(0.0..=1.0);

// Clamp values to range (out-of-range values clamped to bounds)
let clamped = volume.clamp(0.0..=1.0);

For Signed types:

let number = Binding::i32(10);

let sign = number.sign();      // Binding<bool>: true if non-negative
let neg = number.negate();     // Binding<i32>: always the negation
let neg2 = -number;            // operator syntax for negate()

Tip: Use .range() for validation (silently rejects bad values) and .clamp() for correction (forces values into bounds). A volume slider, for example, would typically use .clamp(0.0..=1.0).

Bidirectional Mappings

Sometimes you need a derived binding that can be written to as well as read. Binding::mapping creates a two-way derived binding:

let celsius = Binding::f64(0.0);

let fahrenheit = Binding::mapping(
    &celsius,
    |c| c * 9.0 / 5.0 + 32.0,        // getter: celsius -> fahrenheit
    |binding, f| binding.set((f - 32.0) * 5.0 / 9.0), // setter: fahrenheit -> celsius
);

fahrenheit.set(212.0);
assert_eq!(celsius.get(), 100.0);

Try setting fahrenheit to 32.0 and check what celsius.get() returns.

Filtering

Create a binding that rejects invalid values:

let age = Binding::i32(25);
let valid_age = age.filter(|&a| a >= 0 && a <= 150);
valid_age.set(-1); // silently ignored
assert_eq!(age.get(), 25); // unchanged

Condition and Equality

let score = Binding::i32(85);

// Condition: arbitrary predicate -> Binding<bool>
let is_passing = score.condition(|&s| s >= 60);

// Equal to a specific value -> Binding<bool>
let is_perfect = score.equal_to(100);

Computed<T>: Derived Read-Only State

While Binding is for state you own and modify, Computed is for values you derive from other signals. It is a type-erased, read-only signal that wraps any Signal implementation behind a Box<dyn ...>:

pub struct Computed<T>(Box<dyn ComputedImpl<Output = T>>);

Create computed values from other signals:

let count = Binding::i32(5);

// From a binding (zero-cost conversion)
let computed: Computed<i32> = count.computed();

// Constant computed (never changes)
let always_42 = Computed::constant(42);

// Default computed
let zero: Computed<i32> = Computed::default(); // wraps 0

Computed<V: View> also implements View directly – it watches itself and dynamically re-renders whenever the inner view changes.

Note: Computed is useful when you need to store a signal in a struct field or pass it across an API boundary where the concrete signal type would be inconvenient. In most cases, you can work with concrete signal types directly.

SignalExt Combinators

The SignalExt trait is automatically available on all Signal types. It provides a rich set of combinators for deriving new signals – similar to how iterator adapters work in Rust’s standard library.

Transforming: map

The most fundamental combinator. It creates a new signal whose value is derived from another:

let count = Binding::i32(5);
let doubled = count.map(|n| n * 2);
assert_eq!(doubled.get(), 10);

count.set(10);
assert_eq!(doubled.get(), 20);

Combining: zip

When you need a value that depends on two signals, use zip:

let width = Binding::container(100.0f32);
let height = Binding::container(50.0f32);

let area = width.zip(&height).map(|(w, h)| w * h);
assert_eq!(area.get(), 5000.0);

zip creates a signal that emits whenever either input changes.

Type Conversion: map_into

let count = Binding::i32(42);
let as_i64 = count.map_into::<i64>();

Side Effects: inspect

let value = Binding::i32(0);
let inspected = value.inspect(|v| tracing::debug!("Value changed to {v}"));

inspect runs a side-effect function on each value but passes the original value through unchanged.

Deduplication: distinct

let noisy = Binding::i32(5);
let quiet = noisy.distinct(); // only emits when value actually changes

Tip: Use distinct() after expensive map() operations to avoid redundant downstream updates when the mapped result has not actually changed.

Caching: cached

let expensive = count.map(|n| heavy_computation(n));
let cached_result = expensive.cached(); // memoizes the last value

Type Erasure: computed

let signal = count.map(|n| n * 2);
let erased: Computed<i32> = signal.computed();

Comparison Helpers

These produce boolean signals from numeric or comparable values:

let score = Binding::i32(85);

let is_100 = score.equal_to(100);          // Signal<Output = bool>
let is_high = score.condition(|s| *s > 90); // arbitrary predicate
let above_50 = score.gt(50);               // greater than
let below_50 = score.lt(50);               // less than
let at_least_60 = score.ge(60);            // greater or equal
let at_most_90 = score.le(90);             // less or equal

Boolean Combinators

Combine boolean signals with familiar logical operations:

let logged_in = Binding::bool(true);
let is_admin = Binding::bool(false);

let not_logged = logged_in.not();
let can_edit = logged_in.and(&is_admin);
let can_view = logged_in.or(&is_admin);

// Conditional values
let badge = is_admin.then_some("Admin");    // Signal<Output = Option<&str>>
let role = is_admin.select("admin", "user"); // Signal<Output = &str>

Numeric Combinators

let temp = Binding::i32(-5);

let abs_temp = temp.abs();          // 5
let neg_temp = temp.negate();       // 5
let is_pos = temp.is_positive();    // false
let is_neg = temp.is_negative();    // true
let is_zero = temp.is_zero();       // false
let sign = temp.sign();             // false (negative)

Option Combinators

Work with Signal<Output = Option<T>> without unwrapping manually:

let maybe = Binding::container(Some(42i32));

let is_some = maybe.is_some();              // true
let is_none = maybe.is_none();              // false
let value = maybe.unwrap_or(0);             // 42
let value = maybe.unwrap_or_default();      // 42
let value = maybe.unwrap_or_else(|| 99);    // 42
let eq = maybe.some_equal_to(42);           // true

let nested = Binding::container(Some(Some(5i32)));
let flat = nested.flatten();                // Some(5)

let mapped = maybe.map_some(|n| n.to_string());  // Some("42")
let chained = maybe.and_then_some(|n| if n > 0 { Some(n) } else { None });

Result Combinators

let result = Binding::container::<Result<i32, String>>(Ok(42));

let is_ok = result.is_ok();
let is_err = result.is_err();
let ok_val = result.ok();       // Signal<Output = Option<i32>>
let err_val = result.err();     // Signal<Output = Option<String>>
let safe = result.unwrap_or_result(0);
let mapped = result.map_ok(|n| n * 2);
let mapped_err = result.map_err(|e| format!("Error: {e}"));

String Combinators

let text = Binding::container("hello world".to_string());

let empty = text.is_empty();             // false
let len = text.str_len();                // 11
let has_world = text.contains("world");  // true

Timer Combinators

These require the timer feature and are essential for handling rapid user input:

use std::time::Duration;

let rapid_input = Binding::container(String::new());

// Only emit after 300ms of inactivity
let debounced = rapid_input.debounce(Duration::from_millis(300));

// Emit at most once per 100ms
let throttled = rapid_input.throttle(Duration::from_millis(100));

Tip: Use debounce for search-as-you-type (wait until the user stops typing). Use throttle for scroll or resize handlers (limit update frequency).

constant(): Static Signals

For values that never change but need to participate in the signal graph:

use waterui::reactive::constant;

let tax_rate = constant(0.08);
let price = Binding::f64(100.0);

let total = price.zip(&tax_rate).map(|(p, r)| p * (1.0 + r));
assert_eq!(total.get(), 108.0);

A Constant<T> implements Signal but its watch() is a no-op – watchers are never notified because the value never changes. This makes it zero-overhead in the reactive graph.

Lazy: Deferred Constants

For expensive constant computations that should only run on first access:

use waterui::reactive::constant::Lazy;

let config = Lazy::new(|| {
    // Expensive computation, runs only once
    load_config_from_disk()
});

// First call computes and caches; subsequent calls return cached value
let value = config.get();

The s! Macro: Reactive String Formatting

Building formatted strings from multiple reactive values is a common need. The s! macro creates a signal that produces a formatted String, automatically capturing reactive variables from scope:

let name = Binding::container("Alice".to_string());
let age = Binding::i32(30);

// Named variable capture -- variables are found by name in scope
let greeting = s!("Hello {name}, you are {age} years old");
// greeting is a Signal<Output = String> that updates when name or age change

// Positional arguments
let msg = s!("Value: {}", count);

The macro supports up to 4 reactive variables. It automatically zips and maps them, producing a signal that re-formats whenever any input changes.

Rules:

• Named placeholders like {name} are auto-captured from scope.
• Positional placeholders like {} require explicit arguments.
• You cannot mix named and positional placeholders in the same call.

Note: s! produces a Signal<Output = String>. If you need a Text view, use text! instead.

The text! Macro: Localized Reactive Text

The text! macro creates a localized Text view with full i18n support:

// Simple text -- looked up in i18n/*.toml files
text!("Hello, World!")

// With reactive placeholders
let name = Binding::container("Alice".to_string());
text!("Hello, {name}")

// Plural support -- {#count} marks the plural source
let count = Binding::i32(3);
text!("I have {#count} apple")
// English: "I have 3 apples" (other)
// English: "I have 1 apple" (one)

// Context disambiguation
text!("Right" @ "direction")  // different from text!("Right" @ "correct")

// Explicit binding
text!("Hello, {name}", name = get_current_user())

Translation files are TOML in the i18n/ directory:

# i18n/en.toml
"Hello, World!" = "Hello, World!"
"I have {#count} apple" = { one = "I have {count} apple", other = "I have {count} apples" }

# i18n/zh.toml
"Hello, World!" = "你好，世界！"
"I have {#count} apple" = { other = "我有{count}个苹果" }

The #[derive(Project)] Macro

When you have a Binding<Struct>, you often need to pass individual fields to different child views. The Project derive macro lets you decompose a struct binding into per-field bindings:

#[derive(Clone, Project)]
struct Person {
    name: String,
    age: u32,
}

let person = Binding::container(Person {
    name: "Alice".to_string(),
    age: 30,
});

// Decompose into individual field bindings
let projected: PersonProjected = person.project();
// projected.name: Binding<String>
// projected.age: Binding<u32>

// Changes propagate bidirectionally
projected.name.set_from("Bob");
projected.age.set(25);
assert_eq!(person.get().name, "Bob");
assert_eq!(person.get().age, 25);

The macro generates a PersonProjected struct with Binding<T> for each field. Each projected binding uses Binding::mapping internally, so changes in either direction are reflected.

Tuples also implement Project natively (up to 14 elements):

let pair = Binding::container((42i32, "hello".to_string()));
let (num, text) = pair.project();
num.set(100);
assert_eq!(pair.get().0, 100);

Tip: Project is especially useful when you have a form that edits a struct. Project the struct into per-field bindings and pass each one to its corresponding input control.

List<T>: Reactive Collections

For dynamic lists – think todo items, chat messages, or search results – Binding<Vec<T>> works but does not tell you what changed. List<T> is a reactive Vec that notifies watchers when its contents change, with fine-grained information about insertions, removals, and reorderings:

use waterui::reactive::collection::{Collection, List};

let items = List::new();

// Mutation methods
items.push("first".to_string());
items.push("second".to_string());
items.insert(1, "middle".to_string());
let removed = items.remove(0);  // returns "first"
let last = items.pop();         // returns Some("middle")
items.clear();
items.sort(); // for Ord types

// Reading
let snapshot: Vec<String> = items.snapshot(); // clone current contents
let len = items.len(); // via Collection trait

// Iteration (clones the list to avoid borrow conflicts)
for item in &items {
    // ...
}

List<T> implements the Collection trait, which supports range-based watching:

// Watch the entire collection
let all_items_guard = items.watch(.., |ctx| {
    let current = ctx.into_value();
    tracing::debug!("Items: {current:?}");
});

// Watch a specific range
let visible_items_guard = items.watch(1..4, |ctx| {
    tracing::debug!("Items 1..4: {:?}", ctx.into_value());
});

List<T> is reference-counted internally – cloning a List creates a shared handle. Modifications through any handle notify all watchers.

Using List with ForEach

To render a reactive list, use ForEach:

use waterui::views::ForEach;
use waterui::Identifiable;

#[derive(Clone)]
struct TodoItem {
    id: i32,
    title: String,
    completed: Binding<bool>,
}

impl Identifiable for TodoItem {
    type Id = i32;

    fn id(&self) -> Self::Id {
        self.id
    }
}

let todos: List<TodoItem> = List::new();
let list_view = ForEach::new(todos, |item| {
    hstack((
        text(item.title),
        Spacer,
        Toggle::new(&item.completed),
    ))
});

Each item must implement Identifiable so the framework can track insertions, removals, and reorderings efficiently.

Warning: Do not use Vec with Dynamic::watch for lists that change frequently. You will lose all diffing benefits and re-render the entire list on every change. Use List<T> with ForEach instead.

The BindingMailbox: Cross-Thread Access

Since Binding<T> is !Send (it uses Rc internally), you cannot send it across threads. If you need to update UI state from a background task – say, after fetching data from a network – the BindingMailbox provides an async interface:

let count = Binding::i32(0);
let mailbox = count.mailbox();

// Send from another task
async fn background_work(mailbox: BindingMailbox<i32>) {
    let current = mailbox.get().await;
    mailbox.set(current + 1).await;

    // Or send a mutation job
    mailbox.handle(|binding| {
        binding.add_assign(10);
    });
}

The mailbox spawns a local task that processes jobs sequentially on the UI thread.

Watching Signals Manually

While most reactive updates happen automatically through the view system, you can watch signals manually for side effects like logging, analytics, or synchronizing with external systems:

let count = Binding::i32(0);

let guard = count.watch(|ctx| {
    let new_value = ctx.into_value();
    tracing::debug!("Count changed to {new_value}");
});

// IMPORTANT: The guard keeps the watcher alive.
// Dropping the guard unsubscribes the watcher.
// Use .retain(guard) to tie it to a view's lifecycle.

To keep a manual watcher alive for the lifetime of a view:

fn my_view(count: Binding<i32>) -> impl View {
    let guard = count.watch(|ctx| {
        tracing::debug!("Count: {}", ctx.into_value());
    });

    text!("Hello")
        .retain(guard) // guard lives as long as the view
}

Feeding Signals into Views

There are several ways to connect reactive state to the UI. Let’s look at each approach and when to use it.

Dynamic::watch

Rebuild a view section whenever a signal changes:

let count = Binding::i32(0);

Dynamic::watch(count, |n| {
    text!("Count: {n}")
})

This is the most general approach – the closure receives the raw value and returns any View.

The text! and s! macros

For text content, the macros handle reactivity automatically:

let name = Binding::container("World".to_string());
text!("Hello, {name}") // updates when name changes

Component-level reactivity

Many WaterUI components accept signals directly:

let is_on = Binding::bool(false);
Toggle::new(&is_on) // Toggle reads and writes the binding

let progress = Binding::f64(0.5);
Slider::new(&progress) // Slider binds to the value

let label = Binding::container("Click me".to_string());
Button::new(text!("{label}")).action(|| { /* action */ })

The Golden Rule

Never call .get() in view body code to feed values into the UI.

This is the single most important rule for working with WaterUI reactivity. When you call .get(), you take a snapshot of the current value. The UI will never update when the signal changes because no watcher was registered:

// BAD -- breaks reactivity
fn bad_view(count: Binding<i32>) -> impl View {
    let n = count.get(); // snapshot! never updates
    text!("Count: {n}")  // n is a plain i32, not a signal
}

// GOOD -- reactive
fn good_view(count: Binding<i32>) -> impl View {
    Dynamic::watch(count, |n| text!("Count: {n}"))
}

// GOOD -- text! captures the binding reactively by name
fn also_good(count: Binding<i32>) -> impl View {
    text!("Count: {count}")
}

Warning: This is the number one source of “my UI is not updating” bugs. If your view is not reacting to state changes, check whether you are accidentally calling .get() in the view body.

Use .get() only in:

• Event handlers and callbacks (e.g., on_tap(|| { let x = count.get(); ... }))
• Watcher closures
• Async tasks
• Tests

Combining Multiple Signals

Use zip and map to derive values from multiple signals without breaking reactivity:

let first_name = Binding::container("Alice".to_string());
let last_name = Binding::container("Smith".to_string());

// Combine two signals
let full_name = first_name.zip(&last_name)
    .map(|(f, l)| format!("{f} {l}"));

// Use in a view
Dynamic::watch(full_name, |name| text!("{name}"))

For more than two signals, chain zip:

let a = Binding::i32(1);
let b = Binding::i32(2);
let c = Binding::i32(3);

let sum = a.zip(&b).zip(&c)
    .map(|((a, b), c)| a + b + c);

Tip: If you find yourself zipping more than three signals, consider whether they belong in a struct with #[derive(Project)]. It often leads to cleaner code.

Summary Table

With reactive state under your belt, the next chapter introduces the Environment – WaterUI’s dependency injection system that lets you share configuration, themes, and services across your entire view tree.

The Environment

In this chapter, you will:

• Understand how WaterUI’s type-indexed dependency injection works
• Learn to insert, read, and override values that flow through the view tree
• Use use_env and extractors to access shared configuration from any view
• Build plugins and hooks that customize component rendering globally

Picture this: you are building an app with a dark mode toggle. When the user flips the switch, every single component – buttons, text labels, backgrounds – needs to update its colors. You could pass a theme parameter to every view function… but that would be tedious and fragile. What if a deeply nested component also needs the current locale, or an API client, or a navigation controller?

The Environment solves this. It is WaterUI’s type-indexed dependency injection system – a shared bag of values that flows automatically through the view hierarchy. Any view can read from it, and any view can extend it for its descendants. Think of it like React Context or SwiftUI’s @Environment, but with Rust’s type system as the key.

How It Works

Environment is a type-indexed map – each unique type can store at most one visible value. When a view’s body() is called, it receives a reference to the current environment. Child views inherit the parent’s environment, and any view can extend it with additional values for its descendants.

Internally, Environment is implemented as a structurally-shared overlay chain (an Rc<EnvironmentState> linked list backed by a BTreeMap at the root). That means cloning an environment is an Rc bump, and extending one is an O(1) overlay – no map copy required.

This design gives you:

• Zero boilerplate: No keys, strings, or registration ceremonies. The type is the key.
• Automatic scoping: Values inserted by a parent are visible to all descendants.
• Override-friendly: A child can shadow a parent’s value for its subtree.
• Clone-cheap: Environment clones share their backing state through Rc.

Note: Since each type can appear at most once, inserting the same type again replaces the previous value. If you need multiple values of the same type (e.g., two different Color values), see the Store section below.

Creating and Seeding

Empty Environment

let env = Environment::new();

Inserting Values

Use insert for imperative insertion. Both insert and with mutate the environment in place; with returns &mut Self so successive calls can be chained on a mutable handle:

let mut env = Environment::new();

// Imperative
env.insert(String::from("hello"));
env.insert(42i32);

// Fluent chaining on a &mut Environment
env.with(String::from("hello"))
   .with(42i32);

Since types are keys, each type can appear at most once. Inserting the same type replaces the previous value. To extend a borrowed environment without mutation, use env.extending(value), which returns a fresh Environment that overlays the new value on the original.

The store() Method: Namespaced Keys

What if you need two values of the same type? Use Store<K, V> where K is a zero-sized marker type. store consumes the environment and returns a new one (it is the chainable cousin of with):

use waterui_core::env::Store;

struct PrimaryColor;
struct AccentColor;

let env = Environment::new()
    .store::<PrimaryColor, _>(Color::blue())
    .store::<AccentColor, _>(Color::orange());

Now the environment holds two Color values distinguished by their marker type. Query them with:

let primary: Option<&Color> = env.query::<PrimaryColor, Color>();
let accent: Option<&Color> = env.query::<AccentColor, Color>();

Tip: Store is a lightweight pattern for when you need the same type in multiple roles. The marker types are zero-sized, so they add no runtime overhead.

Installing Plugins

let mut env = Environment::new();
env.install(MyThemePlugin);
env.install(LocalizationPlugin::new("en"));

The install method calls the plugin’s install method, which can insert multiple values, hooks, or other plugins. We will cover plugins in detail later in this chapter.

Reading Values

Direct Lookup

// Returns Option<&T>
if let Some(theme) = env.get::<MyTheme>() {
    // use theme
}

get_or_insert_with

Lazily initialize a value if it does not exist:

let config = env.get_or_insert_with(|| AppConfig::default());

Removing Values

env.remove::<MyTheme>();

Now that you know how to seed and query the environment directly, let’s see how views interact with it.

Accessing the Environment from Views

The use_env Function

use_env creates a view that receives extracted values from the environment. This is the primary way your views consume shared configuration:

use waterui_core::env::use_env;

let view = use_env(|theme: MyTheme| {
    let name = theme.name.clone();
    text!("Current theme: {name}")
        .foreground(theme.text_color)
});

The closure parameter must implement the Extractor trait (more on this below). If extraction fails (the value is not in the environment), the view panics.

For optional values, wrap the extractor in Option:

let view = use_env(|theme: Option<MyTheme>| {
    match theme {
        Some(theme) => {
            let name = theme.name.clone();
            text!("Theme: {name}").anyview()
        }
        None => text("No theme set").anyview(),
    }
});

Note: text! accepts only named placeholders captured from scope or aliased explicitly (text!("Hello, {name}", name = greeting())). Positional {} placeholders are rejected at compile time.

Tuple Extraction

Extract multiple values at once:

let view = use_env(|(nav, db): (NavigationController, Database)| {
    let name = db.name();
    text!("Connected to {name}")
});

Tuple extractors are implemented for tuples up to 8 elements.

The ViewExt::with Method

Inject a value into the environment for a view’s subtree:

// All descendants of this view will see MyConfig in their environment
my_view.with(MyConfig { debug: true })

This creates a With<V, T> wrapper that clones the current environment, inserts the value, and passes the modified environment to the child.

Tip: .with() is how you scope configuration to a subtree. For example, you can set a different theme for just the settings page without affecting the rest of the app.

The ViewExt::install Method

Install a plugin into the environment for a subtree:

my_view.install(MyPlugin)

This is equivalent to use_env(|mut env: Environment| { env.install(plugin); Metadata::new(view, env) }).

Extractor and Use<T>

The Extractor trait defines how to pull values from an Environment:

pub trait Extractor: 'static + Sized {
    fn extract(env: &Environment) -> Result<Self, Error>;
}

Built-in Extractors

The Use<T> Wrapper

Use<T> is the standard way to extract a value. It implements Deref<Target = T>:

use waterui_core::extract::Use;

let view = use_env(|Use(config): Use<AppConfig>| {
    let debug = config.debug;
    text!("Debug: {debug}")
});

If the type is not found, extraction returns an error with a clear message describing the missing type.

Custom Extractors

The impl_extractor! macro generates an Extractor impl that delegates to Use<T>:

impl_extractor!(MyConfig);

// Now you can write:
let view = use_env(|config: MyConfig| {
    // config is extracted directly, no Use<> wrapper needed
});

Tip: Use impl_extractor! for types you access frequently. It saves you from writing Use<MyConfig> everywhere.

Metadata<T> and IgnorableMetadata<T>

Metadata attaches additional rendering instructions to views. There are two kinds, depending on whether the instruction is mandatory or optional.

Metadata<T> (Mandatory)

pub struct Metadata<T: MetadataKey> {
    pub content: AnyView,
    pub value: T,
}

If a renderer encounters Metadata<T> and does not handle it, calling body() will panic. This ensures critical rendering instructions (e.g., environment overrides, lifecycle hooks) are not silently dropped.

// Attach mandatory metadata
let view = Metadata::new(my_view, LifeCycleHook::new(LifeCycle::Appear, || {
    tracing::info!("View appeared!");
}));

IgnorableMetadata<T> (Optional)

pub struct IgnorableMetadata<T: MetadataKey> {
    pub content: AnyView,
    pub value: T,
}

If a renderer does not handle this metadata, body() simply returns the content view – the metadata is silently discarded. Use this for hints that improve the experience but are not required (e.g., accessibility labels).

let view = IgnorableMetadata::new(my_view, AccessibilityLabel::new("Submit button"));

MetadataKey

Both metadata types require the value to implement MetadataKey:

pub trait MetadataKey: 'static {}

This is a simple marker trait. Implement it for any type you want to attach as metadata.

Retain: Keeping Guards Alive

When you set up a manual watcher on a signal, the watcher is unsubscribed as soon as its guard is dropped. But view body functions are one-shot – they return a view and then their local variables go out of scope. Retain solves this by keeping an arbitrary value alive for the lifetime of the view:

pub struct Retain {
    // private fields
}

Use it through ViewExt::retain:

fn my_view(data: Binding<String>) -> impl View {
    let guard = data.watch(|ctx| {
        tracing::debug!("Data changed: {}", ctx.into_value());
    });

    text!("Watching data")
        .retain(guard)  // guard lives as long as this view
}

Without .retain(), the guard would be dropped at the end of the function, immediately unsubscribing the watcher.

You can retain multiple values by chaining or passing a tuple:

text!("Hello")
    .retain(guard1)
    .retain(guard2)

// Or combine into one retain
text!("Hello")
    .retain((guard1, guard2, some_subscription))

Warning: Forgetting to .retain() a watcher guard is a common bug. Your watcher will appear to “not work” because it gets unsubscribed immediately. If your side effect never fires, check that you are retaining the guard.

Hooks: Intercepting View Configuration

Hooks allow global interception of configurable views. This is the mechanism that powers WaterUI’s theming system. A Hook<C> wraps a function that receives an Environment and a ViewConfiguration, and returns a custom view:

pub struct Hook<C>(Box<dyn Fn(&Environment, C) -> AnyView>);

Construct one with Hook::new(|env, config| ...), where the closure may return any impl View – the constructor erases it to AnyView for you.

Installing a Hook

env.insert_hook(|env: &Environment, config: ButtonConfig| {
    // Return a custom view instead of the default button
    custom_button(config.label, config.action)
        .padding()
        .background(Color::blue())
});

Or using Hook::new directly when you need to keep the hook value around:

use waterui_core::view::Hook;

let hook: Hook<ButtonConfig> = Hook::new(|env, config: ButtonConfig| {
    my_custom_button(config)
});
env.insert(hook);

How Hooks Work

When a configurable view’s body() is called:

1. It extracts its configuration via ConfigurableView::config().
2. It checks env.get::<Hook<Config>>().
3. If a hook exists, hook.apply(env, config) is called.
4. The hook receives a modified environment with itself removed (preventing infinite recursion).
5. If no hook exists, the default native rendering is used.

This is the mechanism behind WaterUI’s theming system – a theme plugin installs hooks for ButtonConfig, ToggleConfig, SliderConfig, etc., replacing the default platform rendering with themed versions.

Note: The hook receives an environment with itself removed. This means if your hook calls config.render(), the default rendering will be used for the inner view – no infinite recursion. This is intentional and allows hooks to wrap the default rendering rather than fully replace it.

Plugins: The Plugin Trait

Plugins bundle related environment setup into a reusable unit. Instead of manually inserting values, hooks, and configurations, you define a plugin that does it all:

pub trait Plugin: Sized + 'static {
    fn install(self, env: &mut Environment) {
        env.insert(self);
    }

    fn uninstall(self, env: &mut Environment) {
        env.remove::<Self>();
    }
}

The default install implementation stores the plugin itself in the environment. Override it to perform custom setup:

struct DarkThemePlugin;

impl Plugin for DarkThemePlugin {
    fn install(self, env: &mut Environment) {
        // Store self so we can check if installed
        env.insert(self);

        // Install hooks for themed components
        env.insert_hook(|env: &Environment, config: ButtonConfig| {
            dark_themed_button(config)
        });

        env.insert_hook(|env: &Environment, config: ToggleConfig| {
            dark_themed_toggle(config)
        });

        // Store theme colors
        env.insert(ThemeColors::dark());
    }
}

Install plugins at the app level or per-subtree:

// App-wide: install into the root environment before constructing App.
pub fn app(mut env: Environment) -> App {
    env.install(DarkThemePlugin);
    App::new(main, env)
}

// Per-subtree: only affects descendants of `settings_form`.
fn settings_page() -> impl View {
    settings_form()
        .install(HighContrastPlugin)
}

Practical Examples

Let’s see the environment in action with some real-world patterns.

Theming with Environment

use waterui::prelude::*;

#[derive(Clone, Debug)]
struct AppTheme {
    primary: Color,
    background: Color,
    text: Color,
}

impl AppTheme {
    fn light() -> Self {
        Self {
            primary: Color::blue(),
            background: Color::srgb(255, 255, 255),
            text: Color::srgb(0, 0, 0),
        }
    }

    fn dark() -> Self {
        Self {
            primary: Color::cyan(),
            background: Color::srgb(26, 26, 26),
            text: Color::srgb(255, 255, 255),
        }
    }
}

fn themed_card(title: &'static str) -> impl View {
    use_env(|theme: AppTheme| {
        text(title)
            .foreground(theme.text)
            .padding()
            .background(theme.background)
    })
}

fn app_root() -> impl View {
    // Inject a static theme into the subtree's environment. Each descendant
    // re-extracts `AppTheme` from the environment via `use_env`.
    vstack((
        themed_card("Welcome"),
        themed_card("Settings"),
    ))
    .with(AppTheme::light())
}

Tip: To swap themes reactively, scope two subtrees behind a when(dark_mode, || ...).otherwise(|| ...) – each branch installs the appropriate theme, and the framework rebuilds the relevant subtree when dark_mode flips.

Configuration Injection

#[derive(Clone, Debug)]
struct ApiConfig {
    base_url: String,
    timeout_ms: u32,
}

impl Plugin for ApiConfig {
    fn install(self, env: &mut Environment) {
        env.insert(self);
    }
}

fn api_status() -> impl View {
    use_env(|config: ApiConfig| {
        let base_url = config.base_url.clone();
        let timeout_ms = config.timeout_ms;
        text!("API: {base_url} ({timeout_ms}ms timeout)")
    })
}

pub fn app(mut env: Environment) -> App {
    env.install(ApiConfig {
        base_url: "https://api.github.com".into(),
        timeout_ms: 5000,
    });
    App::new(main, env)
}

Button Hook Customization

use waterui::prelude::*;
use waterui::shape::RoundedRectangle;

struct RoundedButtonPlugin;

impl Plugin for RoundedButtonPlugin {
    fn install(self, env: &mut Environment) {
        env.insert(self);
        env.insert_hook(|env: &Environment, config: ButtonConfig| {
            // Re-render the default button, then wrap it in chrome.
            config.render()
                .padding()
                .background(Color::blue())
                .clip(RoundedRectangle::new(0.2))
        });
    }
}

fn my_screen() -> impl View {
    vstack((
        // These buttons render through RoundedButtonPlugin's hook.
        button("Save").action(|| {}),
        button("Cancel").action(|| {}),
    ))
    .install(RoundedButtonPlugin)
}

Note: RoundedRectangle::new takes a normalized corner radius in 0.0..=0.5, not points. The 0.2 above produces softly rounded corners regardless of the button size.

Try installing RoundedButtonPlugin on just one section of your app and observe how only that subtree’s buttons are affected.

Summary

With the environment in hand, you have a powerful tool for sharing state across your view tree. The next chapter covers modifiers – the chainable methods that let you style, position, and add behavior to any view.

Modifiers and ViewExt

In this chapter, you will:

• Learn how modifier chaining works under the hood
• Use layout modifiers to control sizing, spacing, and alignment
• Apply visual effects like backgrounds, borders, shadows, and filters
• Add interactivity with tap, gesture, and drag-and-drop modifiers
• Understand why modifier order matters and how to get it right

You have your views and your reactive state. Now you need to make them look good and respond to user input. In WaterUI, you do this with modifiers – chainable methods that add styling, layout, and behavior to any view. Instead of passing dozens of parameters to a constructor, you build up the description one modifier at a time:

text!("Hello")
    .padding()
    .background(Color::blue())
    .on_tap(|| { /* ... */ })

This approach keeps your view constructors simple and your styling composable.

A Hydrolysis preview showing how modifier order changes rendered output. Example source.

How Modifiers Work

Every modifier method on ViewExt takes self (consuming the view) and returns a new type that wraps it. For example:

text!("Hello")          // Text
    .padding()          // Padding (wraps Text)
    .background(Color::blue())  // Background (wraps Padding)
    .border(Color::srgb(0, 0, 0), 1.0) // Metadata<Border> (wraps Background)

The resulting type is a nested structure. The renderer walks this structure from outside to inside, applying each modifier’s effect as it goes.

Because modifiers are type-level wrappers (not runtime property bags), the compiler can optimize aggressively and catch errors at compile time.

The ViewExt Trait

ViewExt is an extension trait automatically implemented for every View:

pub trait ViewExt: View + Sized {
    // ... modifier methods ...
}

impl<V: View + Sized> ViewExt for V {}

All methods are available through the WaterUI prelude – no special imports needed. The following sections catalog every modifier by category.

Layout Modifiers

Layout modifiers control sizing, spacing, and alignment – the fundamentals of placing your views on screen.

padding

Every UI needs breathing room. padding adds space around the view’s content:

// Default padding (14.0 points on all sides)
text!("Hello").padding()

// Custom edge insets
text!("Hello").padding_with(EdgeInsets::new(10.0, 20.0, 10.0, 20.0))

// EdgeInsets also supports From<f32> for uniform padding
text!("Hello").padding_with(16.0)

width, height, size

Fix the view to specific dimensions:

Color::red().width(100.0)
Color::red().height(50.0)
Color::red().size(100.0, 50.0) // both at once

min/max constraints

When you want a view that flexes within bounds:

text!("Flexible")
    .min_width(80.0)
    .max_width(300.0)
    .min_height(40.0)
    .max_height(200.0)

// Both axes at once
text!("Bounded").min_size(80.0, 40.0).max_size(300.0, 200.0)

alignment

Position the view within its allocated frame:

text!("Top Left").alignment(Alignment::TopLeading)
text!("Center").alignment(Alignment::Center)
text!("Bottom Right").alignment(Alignment::BottomTrailing)

ignore_safe_area

Extend the view’s bounds beyond safe area insets (useful for full-bleed backgrounds):

use waterui::prelude::*;

// Fill entire screen including notch/status bar area
Color::red().ignore_safe_area(EdgeSet::ALL)

// Only extend to top (under status bar)
header_view.ignore_safe_area(EdgeSet::TOP)

Frame Builder

The width, height, alignment, and constraint methods all return a Frame, which supports further chaining:

text!("Hello")
    .width(200.0)        // returns Frame
    .height(50.0)        // Frame method
    .min_width(100.0)    // Frame method
    .alignment(Alignment::Center) // Frame method

Tip: You can chain all frame-related modifiers together in one fluent call since they all return Frame.

Visual Modifiers

Visual modifiers affect the appearance of views without changing their layout. These are what make your views look polished.

background

Render content behind the view:

// Solid color
text!("Hello").background(Color::red())

// Material (platform blur effect)
text!("Hello").background(Material::Regular)

// Any view as background
text!("Hello").background(
    hstack((Color::red(), Color::blue()))
)

The background fills the view’s bounds. The content determines the layout size; the background stretches to fill it.

foreground

Set the foreground color for text and icons in the subtree:

// All text in this VStack will be red
vstack((
    text!("Hello"),
    text!("World"),
)).foreground(Color::red())

This works by injecting a ForegroundOverride into the environment, so it affects all descendants that do not override it themselves.

opacity

Control transparency. Any IntoSignalF32 is accepted, including a constant f32 or a reactive Binding<f32>:

// Static opacity
text!("Faded").opacity(0.5)

// Reactive opacity (useful for animations)
let alpha = Binding::f32(1.0);
text!("Dynamic").opacity(alpha)

The opacity modifier maps to compositor-native operations (no GPU pass) and is available directly on ViewExt.

overlay

Render content on top of the view, without affecting the base view’s size:

text!("Hello").overlay(
    Color::red().opacity(0.5)
)

Unlike ZStack, an overlay does not influence the layout of the underlying view.

Tip: overlay is great for badges, status indicators, or decorative elements that should sit on top of content without affecting layout.

shadow

Add a drop shadow. Shadow::new takes a color, an offset vector, and a blur radius:

use waterui::style::{Shadow, Vector};

text!("Shadowed").shadow(Shadow::new(
    Color::srgb(0, 0, 0).with_opacity(0.3),
    Vector { x: 2.0, y: 2.0 },
    4.0,
))

border

Add a border around the view:

// Simple border on all edges
text!("Bordered").border(Color::red(), 2.0)

// Full customization via Border builder
let custom = Border::new(Color::blue(), 2.0)
    .corner_radius(12.0)
    .edges(EdgeSet::HORIZONTAL);

text!("Custom").border_with(custom)

clip

Clip the view to a shape. The shape is normalized to the view’s bounds, so RoundedRectangle::new accepts a corner radius in 0.0..=0.5:

use waterui::shape::{Circle, RoundedRectangle};

// Clip to circle
avatar_view.clip(Circle)

// Clip to rounded rectangle (10% corner radius)
card_view.clip(RoundedRectangle::new(0.1))

visible

Control visibility. visible is implemented as a composition of opacity and hit testing – when hidden, the view fades to opacity 0.0 and stops receiving touches:

let show = Binding::bool(true);
text!("Now you see me").visible(show)

Transform Modifiers

Transforms are purely visual – they change how the view is drawn but do not affect layout calculations. This makes them ideal for animations.

scale

Scale the view around its center. Both axes accept any IntoSignalF32:

// Uniform scale
star_view.scale(1.5, 1.5)

// Non-uniform scale
text!("Stretched").scale(2.0, 1.0)

// Reactive (for animations)
let s = Binding::f32(1.0);
heart_view.scale(s.clone(), s)

// Scale from a specific anchor point
star_view.scale_from(0.5, 0.5, Anchor::TOP_LEFT)

rotation

Rotate the view in degrees:

// Static (positive = clockwise)
arrow_view.rotation(45.0)

// Reactive
let angle = Binding::f32(0.0);
spinner_view.rotation(angle)

// Rotate around a specific anchor
dial_view.rotation_from(90.0, Anchor::TOP_LEFT)

offset

Translate the view:

// Static offset
badge.offset(10.0, -5.0)

// Reactive (great for drag or animation)
let x = Binding::f32(0.0);
let y = Binding::f32(0.0);
draggable_view.offset(x, y)

Tip: Combine offset with reactive bindings and animations to create smooth drag interactions or slide-in effects.

Interaction Modifiers

These modifiers add gesture recognition and touch handling to views. They turn passive content into interactive controls.

on_tap

The simplest interaction – recognize a single tap:

text!("Click me").on_tap(|| {
    tracing::info!("Tapped!");
})

on_tap_gesture_count

Require a specific number of taps:

text!("Double-tap me").on_tap_gesture_count(2, || {
    tracing::info!("Double tapped!");
})

on_long_press_gesture

Recognize a long press:

text!("Press and hold").on_long_press_gesture(500, || {
    tracing::info!("Long pressed for 500ms!");
})

gesture

Attach any gesture recognizer:

use waterui::gesture::*;

text!("Custom gesture")
    .gesture(TapGesture::repeat(3), || {
        tracing::info!("Triple tap!");
    })

hittable

Control whether the view responds to touch/click events:

// Disable hit testing -- touches pass through
overlay_decoration.hittable(false)

// Reactive control
let interactive = Binding::bool(true);
my_view.hittable(interactive)

disabled

Disable the view – grays it out and blocks all interactions:

// Static
button("Submit").action(|| {}).disabled(true)

// Reactive
let is_loading = Binding::bool(false);
button("Submit").action(|| {}).disabled(is_loading)

disabled is a convenience that composes opacity(0.5), hittable(false), and the corresponding accessibility state.

draggable

Make a view draggable:

use waterui::drag_drop::DragData;

text!("Drag me").draggable(DragData::text("Hello!"))

drop_destination

Make a view accept dropped content:

text!("Drop here").drop_destination(|data: DragData| {
    tracing::info!("Received: {:?}", data);
})

Stateful Event Handlers

Sometimes your event handlers need to capture mutable state – for example, tracking a hover count or toggling a flag. Use ViewExt::state to inject cloneable state into the view’s environment, then extract it in handlers via the State<T> extractor:

use waterui::extract::State;

let count = Binding::i32(0);
let is_hovered = Binding::bool(false);

text("Hover Me!")
    .padding()
    .state(&count)
    .state(&is_hovered)
    .on_hover_enter(
        |State(count): State<Binding<i32>>,
         State(hovered): State<Binding<bool>>| {
            count.set(count.get() + 1);
            hovered.set(true);
        },
    )
    .on_hover_exit(|State(hovered): State<Binding<bool>>| {
        hovered.set(false);
    })

Each .state(&value) call inserts that binding into the subtree’s environment. Handlers extract whichever values they need via State<T> parameters; missing values become a clear runtime error.

Feedback Modifiers

These modifiers provide sensory feedback to the user, making your app feel more responsive and native.

on_tap_haptic

Trigger haptic feedback on tap (requires the std feature):

use waterkit_haptic::Intensity;

text!("Haptic tap").on_tap_haptic(Intensity::MEDIUM, || {
    // action
})

// Default medium intensity
text!("Haptic tap").on_tap_haptic_default(|| {
    // action
})

cursor

Set the cursor style when hovering (desktop platforms):

use waterui::cursor::CursorStyle;

text!("Click me").cursor(CursorStyle::PointingHand)

badge

Add a numeric badge overlay (common for notification counts):

let unread = Binding::i32(5);
SystemIcon::new("envelope").badge(unread)

Filter Modifiers

Filter modifiers apply GPU-accelerated visual effects. They come from the FilterViewExt trait (included in the prelude) and are great for image processing and polished UI effects.

blur

Apply a Gaussian blur:

photo_view.blur(10.0)

// Reactive
let blur_amount = Binding::f32(0.0);
photo_view.blur(blur_amount)

brightness

Adjust brightness:

photo_view.brightness(0.2)  // increase
photo_view.brightness(-0.2) // decrease

contrast

Adjust contrast:

photo_view.contrast(1.5) // higher contrast
photo_view.contrast(0.5) // lower contrast

saturation

Adjust color saturation:

photo_view.saturation(1.5) // more vivid
photo_view.saturation(0.0) // completely desaturated

grayscale

Convert to grayscale:

photo_view.grayscale(1.0) // fully grayscale
photo_view.grayscale(0.5) // partially desaturated

hue_rotation

Rotate the hue of all colors (degrees):

photo_view.hue_rotation(90.0)  // shift by 90 degrees
photo_view.hue_rotation(180.0) // invert hues

All filter modifiers accept any impl IntoSignalF32, which means you can pass a static f32, a Binding<f32>, or any signal-based value for animated filters.

Tip: Try animating blur or saturation with a reactive binding for smooth transition effects – for example, blurring the background when a modal appears.

Lifecycle Modifiers

These modifiers let you run code at specific points in a view’s lifecycle.

on_appear

Execute code when the view becomes visible:

text!("Hello").on_appear(|| {
    tracing::info!("View is now visible");
})

Note: body() being called does not mean the view is visible. A lazy container may resolve views ahead of time. Use on_appear for code that should run when the view is actually displayed on screen.

on_disappear

Execute code when the view is removed from the view hierarchy:

text!("Hello").on_disappear(|| {
    tracing::info!("View removed from hierarchy");
})

on_change

Monitor a signal and execute a handler when the value changes:

let search = Binding::container(String::new());

text_field("Search", search.clone())
    .on_change(&search, |value: String| {
        tracing::info!("Search changed to: {value}");
    })

This is a convenience over manual watch() + retain() – the watcher lifecycle is managed automatically. The handler receives the new Output value of the source signal.

task

Spawn an async task tied to the view’s lifecycle:

text!("Loading...").task(async {
    let data = fetch_data().await;
    // The task is cancelled when the view is removed
})

Event Modifiers

on_hover_enter / on_hover_exit

React to cursor hover (macOS, iPadOS with trackpad, Android API 24+):

text!("Hover me")
    .on_hover_enter(|| tracing::info!("Mouse entered"))
    .on_hover_exit(|| tracing::info!("Mouse exited"))

event

Attach a handler for any Event variant:

use waterui_core::event::Event;

text!("Interactive")
    .event(Event::HoverEnter, || { /* ... */ })
    .event(Event::HoverExit, || { /* ... */ })

Other Modifiers

metadata

Attach arbitrary metadata to a view:

text!("Important").metadata(MyCustomMetadata { priority: 1 })

tag

Tag a view for identification:

text!("Item").tag(42)

anyview

Convert to a type-erased AnyView:

let view: AnyView = text!("Hello").anyview();

retain

Keep a value alive for the view’s lifetime:

let guard = some_signal.watch(|_| { /* ... */ });
text!("Watching").retain(guard)

title

Wrap in a navigation view with a title:

content_view.title(text!("Settings"))

focused

Mark the view as focused when a binding matches:

let focus = Binding::container::<Option<Field>>(None);
text_field("Name", name).focused(&focus, Field::Name)

secure

Prevent screenshots of the view:

sensitive_content.secure()

context_menu

Attach a context menu (long-press on mobile, right-click on desktop). Menu content is built from MenuView implementations – ordinary Buttons with .action() work directly:

text("Right-click me").context_menu((
    button("Copy").action(|| { /* ... */ }),
    button("Paste").action(|| { /* ... */ }),
))

a11y_label / a11y_role

Set accessibility attributes:

SystemIcon::new("star").a11y_label("Favorite")
SystemIcon::new("star").a11y_role(AccessibilityRole::Button)

Tip: Always add a11y_label to icon-only buttons and interactive elements. Screen readers rely on these labels to describe your UI to users with visual impairments.

Modifier Order

Modifier order matters in WaterUI because each modifier wraps the previous result. The outermost modifier is applied first during rendering. Getting the order wrong is one of the most common sources of “why does my layout look wrong?”

A common pattern where order matters:

// Padding INSIDE the background
text!("Hello")
    .padding()           // padding applied first
    .background(Color::red()) // background wraps the padded view

// Padding OUTSIDE the background
text!("Hello")
    .background(Color::red()) // background applied first
    .padding()           // padding wraps the background

Similarly for transforms:

// Rotate then offset -- rotates in place, then translates
view.rotation(45.0).offset(100.0, 0.0)

// Offset then rotate -- translates first, then rotates around original center
view.offset(100.0, 0.0).rotation(45.0)

Warning: If your background does not seem to extend behind your padding, or your border appears inside your content area, check your modifier order.

General guidelines:

1. Layout modifiers (padding, frame, alignment) should go before visual modifiers.
2. Gestures should go after layout/visual modifiers so the hit area matches what the user sees.
3. Lifecycle hooks can go anywhere – they do not affect rendering.
4. Background goes after padding if you want the background to include the padded area.

Try swapping .padding() and .background() on a view and observe the difference.

Complete Example

Here is a complete example that puts many modifier categories together:

use waterui::prelude::*;
use waterui::shape::RoundedRectangle;
use waterui::style::{Shadow, Vector};

fn card(title: &'static str, count: Binding<i32>) -> impl View {
    let is_highlighted = count.clone().map(|n| n > 10);
    let background = is_highlighted.map(|on| {
        if on { Color::blue() } else { Color::grey() }
    });

    vstack((
        text(title).foreground(Color::srgb(255, 255, 255)),
        text!("{count}"),
        button("Increment").action(move || {
            count.set(count.get() + 1);
        }),
    ))
    .padding()
    .background(background)
    .border(Color::srgb(0, 0, 0), 1.0)
    .clip(RoundedRectangle::new(0.15))
    .shadow(Shadow::new(
        Color::srgb(0, 0, 0).with_opacity(0.2),
        Vector { x: 0.0, y: 2.0 },
        4.0,
    ))
    .on_appear(|| tracing::info!("Card appeared"))
}

Summary

You now have the complete toolkit for building views, managing reactive state, sharing configuration through the environment, and styling everything with modifiers. The next part of the book, Building UIs, puts all of these concepts together as you work with text, layouts, controls, forms, and navigation.

Text and typography

In this chapter, you will:

• Display text using text() for static content and text! for reactive, localized strings
• Style text with semantic fonts, weights, colors, and decorations
• Build rich text with StyledStr, including Markdown and concatenation
• Add syntax highlighting for source code

Text is the most fundamental building block in any user interface. Whether you are showing a headline, a label beside a toggle, or a paragraph of help text, you reach for the Text component first. WaterUI gives you a small two-function API: text() for plain content that does not change, and the text! macro for reactive strings that interpolate captured bindings and (optionally) consult a translation catalog.

A Hydrolysis preview of WaterUI text rendered with semantic typography and colors. Example source.

Static text with text()

The simplest way to display text is the text() function. It accepts anything that converts into Text — a &'static str becomes localized through the catalog, while String and Str are used verbatim:

use waterui::prelude::*;

fn greeting() -> impl View {
    text("Hello, World!")
}

Text sizes itself to fit its content and never stretches to fill extra space. When the available width is limited, it wraps to multiple lines automatically.

Layout behavior

Here is what you need to know about how Text participates in layout:

• Sizing: fits its content naturally, like a label.
• In stacks: takes only the space it needs, leaving room for siblings.
• Wrapping: wraps when width is constrained — for example by a parent Frame.

use waterui::prelude::*;

fn row() -> impl View {
    // Push two labels apart in a row.
    hstack((text("Name"), spacer(), text("Value")))
}

Tip: Because Text never stretches on its own, you can safely place it in any stack without worrying about it gobbling up space from sibling views.

Reactive text with text!

Static strings are fine for fixed labels, but most apps need text that updates in response to state. The text! macro captures any named placeholder from the surrounding scope and re-evaluates whenever those bindings change. When a i18n/<locale>.toml catalog is present, the same call site also resolves the matching translation:

use waterui::prelude::*;

fn counter_label(count: &Binding<i32>) -> impl View {
    // Captures `count` from scope; the rendered text updates on every change.
    text!("Count: {count}")
}

The macro only accepts named placeholders. Either name a binding directly ({count}), or alias an expression with name = expr:

use waterui::prelude::*;

fn welcome(get_name: impl Fn() -> String) -> impl View {
    text!("Hello, {name}", name = get_name())
}

Warning: text! does not accept positional {} placeholders. Writing text!("Count: {}", count) will not compile. Use a named placeholder ({count}) and capture the binding from scope, or pass an explicit alias (name = expr).

Why not .get() and format!?

Calling .get() on a binding inside a view body reads the current value once and never re-runs. The text would freeze at construction time. Always express formatting through text! so the framework tracks the dependency:

use waterui::prelude::*;

fn show(value: &Binding<f64>) -> impl View {
    // Reactive: updates whenever `value` changes.
    text!("Value: {value:.2}")
}

Displaying arbitrary values

Any signal whose output type implements Display can be rendered with Text::display:

use waterui::prelude::*;

fn show_price(price: &Binding<f64>) -> impl View {
    Text::display(price.clone())
}

Text::display maps the signal through to_string() internally, so the text updates whenever the signal does.

Locale-aware formatting

For specialised formatting — locale-specific dates or numbers — use Text::format:

use waterui::prelude::*;
use waterui::text::locale::Formatter;

fn formatted<T: 'static + Clone>(value: &Binding<T>, fmt: impl Formatter<T> + 'static) -> impl View {
    Text::format(value.clone(), fmt)
}

Implement the Formatter<T> trait for any type whose presentation depends on the active locale.

Translation files for text!

If your app supports multiple languages, place TOML files under i18n/ in the crate root:

# i18n/en.toml
"Count: {count}" = "Count: {count}"

# i18n/zh.toml
"Count: {count}" = "计数：{count}"

The macro picks the right translation based on the active Locale in the environment. Missing translation files are not an error — text! falls back to the format string itself.

Note: Plural forms use {#count} syntax in the format string and a TOML table with one/other keys. See waterui/macros/src/locale.rs for the full grammar.

Font system

WaterUI provides a semantic font system with six built-in presets. Each preset resolves to a platform-appropriate size and weight through the environment, so a “Larger Text” accessibility setting cascades into your screen automatically:

Use the convenience methods on Text. They work on values produced by both text() and text!:

use waterui::prelude::*;

fn typography() -> impl View {
    vstack((
        text("Page Title").title(),
        text("Main heading").headline(),
        text("Section header").sub_headline(),
        text("Body content").body(),
        text("Small note").caption(),
        text("Legal text").footnote(),
    ))
}

Custom font configuration

For fine-grained control, build a Font value and pass it to .font():

use waterui::prelude::*;
use waterui::text::font::{Font, FontWeight};

fn custom() -> impl View {
    text("Custom").font(
        Font::default()
            .size(18.0)
            .weight(FontWeight::Medium)
            .family("monospace"),
    )
}

Font weights

The FontWeight enum provides nine standard weights:

pub enum FontWeight {
    Thin,       // 100
    UltraLight, // 200
    Light,      // 300
    Normal,     // 400 (default)
    Medium,     // 500
    SemiBold,   // 600
    Bold,       // 700
    UltraBold,  // 800
    Black,      // 900
}

Size, weight, italic shortcuts

You do not always need to construct a Font. Text provides direct shortcuts. .size() and .weight() accept signals, so they can react:

use waterui::prelude::*;

fn highlight(emphasised: &Binding<bool>) -> impl View {
    vstack((
        text("Large bold text").size(28.0).bold(),
        // Italic toggles reactively from the binding.
        text("May be italic").italic(emphasised.clone()),
    ))
}

Color

Colors are zero-sized marker types you can pass into .color() or .foreground(). The built-in palette includes Red, Blue, Green, Orange, Purple, Cyan, Yellow, Pink, and Grey:

use waterui::prelude::*;

fn status() -> impl View {
    vstack((
        text("Error message").color(Red),
        text("Success").color(Green),
        text("Highlighted").background_color(Yellow),
    ))
}

Note: .color() on Text sets an explicit foreground color for that specific text view. The more general .foreground() modifier from ViewExt sets the inherited foreground for an entire view subtree, so children respect the cascade.

Text decorations

Underline

use waterui::prelude::*;

fn link_label(highlighted: &Binding<bool>) -> impl View {
    text("Click here").underline(highlighted.clone())
}

.underline() accepts any IntoSignal<bool>, so the decoration can toggle reactively.

Strikethrough

Strikethrough lives on StyledStr, not on Text:

use waterui::prelude::*;
use waterui::text::styled::StyledStr;

fn deprecated() -> impl View {
    text(StyledStr::plain("Deprecated").strikethrough(true))
}

Concatenating text

Sometimes you need mixed styles within a single line. Text implements Add and AddAssign, so styled fragments compose with +:

use waterui::prelude::*;

fn name_row() -> impl View {
    text("Name: ").bold() + text("Alice")
}

The resulting Text preserves the styling of each fragment.

Rich text with StyledStr

For full control over rich text, build a StyledStr directly. Each chunk carries its own Style, which includes font, foreground color, background color, italic, underline, and strikethrough:

use waterui::prelude::*;
use waterui::text::styled::{Style, StyledStr};

fn intro() -> impl View {
    let mut styled = StyledStr::empty();
    styled.push("Bold intro: ", Style::default().bold());
    styled.push("normal continuation", Style::default());
    text(styled)
}

Markdown shorthand

StyledStr::from_markdown parses a small subset of Markdown — headings, bold, italic, strikethrough, inline code, and paragraphs — into a styled string in one step:

use waterui::prelude::*;
use waterui::text::styled::StyledStr;

fn release_notes() -> impl View {
    text(StyledStr::from_markdown("**Bold** and *italic* with `code`"))
}

Syntax highlighting

If your app displays source code, WaterUI ships a syntect-backed highlighter. highlight_text is synchronous: it consumes a borrowed source string and a mutable highlighter, and returns a fully styled StyledStr:

use waterui::prelude::*;
use waterui::text::highlight::{DefaultHighlighter, Language, highlight_text};

fn code_view(source: &str) -> impl View {
    let mut highlighter = DefaultHighlighter::default();
    text(highlight_text(Language::Rust, source, &mut highlighter))
}

The Language enum covers Rust, Swift, Python, TypeScript, and many others. Each chunk in the resulting StyledStr carries the appropriate syntax color.

Quick reference

Now that you can display and style text, it is time to learn how to arrange views on screen. In the next chapter, you will explore stacks, frames, grids, and the rest of the layout system.

Layout: stacks, frames, and grids

In this chapter, you will:

• Arrange views vertically, horizontally, and in layers using stacks
• Control spacing, alignment, and sizing with frames and padding
• Build grid-based layouts and scrollable content
• Use absolute positioning and pin constraints for free-form layouts

Every app needs to place things on screen — a title at the top, a button at the bottom, a sidebar on the left. WaterUI uses a declarative layout system inspired by SwiftUI: you compose views using stacks, spacers, frames, and grids, and the framework resolves sizes and positions through a proposal-based layout protocol. All values are in logical pixels (points/dp) — the same unit as Figma and Sketch. Native backends convert to physical pixels automatically.

A Hydrolysis preview of WaterUI stack layout primitives. Example source.

Stacks

Stacks are your primary tool for arranging views. Think of them as the rows and columns of your interface. WaterUI provides three kinds: vstack (vertical), hstack (horizontal), and zstack (overlay).

vstack — vertical layout

vstack arranges children from top to bottom. It accepts a tuple of views:

use waterui::prelude::*;

fn profile_card() -> impl View {
    vstack((
        text("Alice").title(),
        text("Software Engineer"),
        text("San Francisco"),
    ))
}

Default spacing between children is 10pt and alignment is center.

Custom spacing and alignment

Use the struct constructor for full control:

use waterui::prelude::*;

fn left_aligned() -> impl View {
    VStack::new(HorizontalAlignment::Leading, 16.0, (
        text("Left-aligned"),
        text("Also left-aligned"),
    ))
}

Or chain the builder methods on vstack:

use waterui::prelude::*;

fn trailing_8pt() -> impl View {
    vstack((
        text("Item 1"),
        text("Item 2"),
    ))
    .alignment(HorizontalAlignment::Trailing)
    .spacing(8.0)
}

Horizontal alignment options

pub enum HorizontalAlignment {
    Leading,  // left in LTR locales
    Center,   // default
    Trailing, // right in LTR locales
}

hstack — horizontal layout

hstack arranges children left to right. This is what you reach for when building toolbars, rows of buttons, or any side-by-side arrangement:

use waterui::prelude::*;

fn toolbar() -> impl View {
    hstack((
        text("WaterUI"),
        spacer(),
        button("Settings").action(|| {}),
    ))
}

Default spacing is 10pt and alignment is center (vertical).

Custom spacing and alignment

use waterui::prelude::*;

fn top_aligned() -> impl View {
    HStack::new(VerticalAlignment::Top, 20.0, (
        text("Top-aligned"),
        text("Also top"),
    ))
}

Vertical alignment options

pub enum VerticalAlignment {
    Top,
    Center,  // default
    Bottom,
    FirstBaseline,
    LastBaseline,
}

zstack — overlay layout

When you need to layer views on top of each other — a badge on an avatar, text over an image — reach for zstack. The last child in the tuple renders on top, and the stack sizes itself to fit the largest child:

use waterui::prelude::*;

fn badge() -> impl View {
    zstack((
        Blue,
        text("Overlay").color(Yellow),
    ))
}

zstack alignment

Control where children are positioned within the stack:

use waterui::prelude::*;

fn corner_badge(image: impl View, dot: impl View) -> impl View {
    ZStack::new(Alignment::TopTrailing, (image, dot))
}

The Alignment enum has nine positions:

pub enum Alignment {
    TopLeading, Top, TopTrailing,
    Leading, Center, Trailing,    // Center is the default
    BottomLeading, Bottom, BottomTrailing,
}

Spacer

Spacer is a flexible gap that expands to push views apart. It adapts to its parent container: in an HStack it expands horizontally, in a VStack it expands vertically. This is one of the most useful layout tools you have.

use waterui::prelude::*;

fn pushed_to_the_edge() -> impl View {
    hstack((
        text("Title"),
        spacer(),
        button("Done").action(|| {}),
    ))
}

Minimum length

Use spacer_min to set a minimum length the spacer never shrinks below:

use waterui::prelude::*;

fn at_least_20pt() -> impl View {
    hstack((text("A"), spacer_min(20.0), text("B")))
}

Divider

The Divider widget draws a thin line for visual separation between sections:

use waterui::prelude::*;

fn sectioned() -> impl View {
    vstack((
        text("Section 1"),
        Divider,
        text("Section 2"),
    ))
}

Padding

Add breathing room around a view with the Padding wrapper, or its ViewExt shortcuts. padding() applies a default 14pt inset; use padding_with(EdgeInsets) for exact control:

use waterui::prelude::*;

fn padded() -> impl View {
    vstack((
        // Default 14pt on every side.
        text("Default").padding(),

        // Equal padding on all sides.
        text("Padded").padding_with(EdgeInsets::all(16.0)),

        // Symmetric vertical and horizontal.
        text("Symmetric").padding_with(EdgeInsets::symmetric(8.0, 16.0)),

        // Explicit edges.
        text("Custom").padding_with(EdgeInsets::new(10.0, 20.0, 15.0, 25.0)),
    ))
}

EdgeInsets provides three constructors. Note the explicit-edge order:

Frame

When you need a view to be a specific size, or at least a minimum width, wrap it in Frame. It supports minimum, ideal, and maximum dimensions:

use waterui::prelude::*;
use waterui::layout::frame::Frame;

fn fixed() -> impl View {
    Frame::new(text("Fixed"))
        .width(200.0)
        .height(100.0)
}

fn bounded() -> impl View {
    Frame::new(text("Bounded"))
        .max_width(300.0)
        .max_height(200.0)
}

Frame alignment

Control how the child is positioned within the frame:

use waterui::prelude::*;
use waterui::layout::frame::Frame;

fn bottom_right() -> impl View {
    Frame::new(text("Bottom-right"))
        .width(300.0)
        .height(200.0)
        .alignment(Alignment::BottomTrailing)
}

Frame methods

Tip: Use Frame only when you need explicit size constraints. Most views have sensible natural sizes, and stacks distribute space for you.

Scrolling

When content might exceed the available space, wrap it in a scroll view. This is essential for long lists and tall forms:

use waterui::prelude::*;

fn long_list() -> impl View {
    scroll(
        vstack((
            text("Item 1"),
            text("Item 2"),
            text("Item 3"),
        )),
    )
}

Three convenience constructors map to ScrollView:

Grid

For content that naturally falls into rows and columns — a settings panel with labels and values, or an image gallery — use Grid. You specify the number of columns, and the grid distributes children into rows automatically:

use waterui::prelude::*;

fn settings_grid() -> impl View {
    grid(2, [
        row((text("Name"), text("Alice"))),
        row((text("Age"), text("30"))),
        row((text("City"), text("SF"))),
    ])
}

Grid customisation

use waterui::prelude::*;
use waterui::layout::grid::{Grid, GridRow};

fn three_col(rows: Vec<GridRow>) -> impl View {
    Grid::new(3, rows)
        .spacing(16.0)
        .alignment(Alignment::Leading)
}

Default spacing is 8pt in both directions, and default alignment is Center. The grid sizes columns equally based on the available width; row heights are determined by the tallest item in each row.

Overlay

An Overlay layers content on top of a base view without changing the base’s layout sizing. Use it for badges, highlights, and decorations:

use waterui::prelude::*;

fn avatar_with_badge(avatar: impl View, dot: impl View) -> impl View {
    overlay(avatar, dot).alignment(Alignment::TopTrailing)
}

Unlike zstack, the overlay’s size is determined entirely by the base child. The overlay content is positioned within those bounds according to the alignment.

Note: If you need both children to contribute to the overall size, use zstack instead. Overlay is for decorations that should not affect layout.

Background

background() renders a view behind another view. The content child determines the size, and the background fills those bounds:

use waterui::prelude::*;

fn highlighted() -> impl View {
    background(text("Foreground content"), Blue)
}

Absolute positioning

For the rare cases where stacks and grids are not enough — floating action buttons, custom popovers, canvas-like UIs — use absolute with the PositionExt extensions:

use waterui::prelude::*;

fn floating_ui(fab: impl View) -> impl View {
    absolute((
        Color::grey(),
        text("Center").position_in(UnitPoint::CENTER),
        fab.position_in_offset(
            UnitPoint::BOTTOM_TRAILING,
            UnitPoint::BOTTOM_TRAILING,
            -16.0,
            -16.0,
        ),
    ))
}

Positioning methods

The PositionExt trait provides these methods on any View:

UnitPoint constants

UnitPoint uses normalised coordinates (0.0 to 1.0):

UnitPoint::TOP_LEADING     // (0.0, 0.0)
UnitPoint::TOP             // (0.5, 0.0)
UnitPoint::TOP_TRAILING    // (1.0, 0.0)
UnitPoint::LEADING         // (0.0, 0.5)
UnitPoint::CENTER          // (0.5, 0.5)
UnitPoint::TRAILING        // (1.0, 0.5)
UnitPoint::BOTTOM_LEADING  // (0.0, 1.0)
UnitPoint::BOTTOM          // (0.5, 1.0)
UnitPoint::BOTTOM_TRAILING // (1.0, 1.0)

Pin constraints

Pin-based positioning uses edge distances to compute position and size. This is useful when you want a child to stretch between edges or sit at a fixed offset from a corner:

use waterui::prelude::*;
use waterui::layout::PinConstraints;

fn fill_with_inset(child: impl View) -> impl View {
    child.pin(PinConstraints::all(12.0))
}

fn corner_badge(badge: impl View) -> impl View {
    badge.pin(
        PinConstraints::new()
            .trailing(12.0)
            .bottom(12.0)
            .width(28.0)
            .height(28.0),
    )
}

When both leading and trailing are set, the width is computed automatically. The same applies to top and bottom. Explicit .width() and .height() override the computed dimensions.

StretchAxis

Every view has an associated StretchAxis that tells parent layouts whether it wants to expand along one or both axes. Understanding this concept helps you predict how views behave inside stacks:

pub enum StretchAxis {
    None,       // content-sized (e.g. Text, Button)
    Horizontal, // expands width (e.g. TextField, Slider, VStack)
    Vertical,   // expands height
    Both,       // fills available space (e.g. ScrollView, Absolute)
    MainAxis,   // expands along parent stack's main axis (Spacer)
    CrossAxis,  // expands along parent stack's cross axis
}

Stacks use this information to distribute surplus space. For example, Spacer reports MainAxis, so in an HStack it expands horizontally and in a VStack it expands vertically. A TextField reports Horizontal, so it fills available width but keeps its intrinsic height.

Tip: If a view is not expanding as you expect, check its stretch axis. A Text view never stretches; a TextField stretches horizontally; a ScrollView stretches in both directions.

Dynamic stacks via for_each

Stacks support dynamic children through for_each. Instead of a fixed tuple, you provide a reactive collection and a generator that returns one view per element:

use waterui::prelude::*;
use waterui::reactive::collection::List as ReactiveList;

#[derive(Clone)]
struct TodoItem { id: i32, title: String }

impl Identifiable for TodoItem {
    type Id = i32;
    fn id(&self) -> i32 { self.id }
}

fn todo_list(items: ReactiveList<TodoItem>) -> impl View {
    VStack::for_each(items, |item| text(item.title))
        .spacing(8.0)
        .alignment(HorizontalAlignment::Leading)
}

This integrates with the LazyContainer system for efficient rendering of large collections. See the Lists and collections chapter for the full story.

Layout tips

1. Start with stacks. Most layouts can be expressed as nested vstack and hstack calls. Use spacer() to distribute remaining space.
2. Use Frame only when needed. Text and controls have natural sizes; apply explicit frames only for fixed-size regions or constraints.
3. Prefer Alignment over manual positioning. Stack alignment handles most needs. Reserve absolute for truly free-form layouts.
4. Logical pixels everywhere. Backends handle screen density for you.
5. Inspect StretchAxis when something refuses to fit. It tells you whether a view will fight for or yield space.

With layout under your belt, you are ready to make your interfaces interactive. In the next chapter, you will learn about buttons, toggles, sliders, and other controls that let users take action.

Buttons and controls

In this chapter, you will:

• Wire button actions to reactive state with .action() and the State<T> extractor
• Use Toggle, Slider, Stepper, and TextField for primary user input
• Apply button styles to convey hierarchy (primary vs. secondary actions)
• Build dropdown menus from labels and nested submenus

Imagine you are building a settings screen. You need toggles for on/off preferences, a slider for brightness, a text field for a username, and buttons to save or cancel. WaterUI provides a comprehensive set of interactive controls for exactly these scenarios. Each control follows a consistent pattern: you create it with a constructor or convenience function, configure it with builder methods, and wire it to reactive state through bindings.

A Hydrolysis preview of WaterUI controls rendered from real bindings. Example source.

Button

Buttons are the most common interactive element. WaterUI buttons support multiple action patterns, custom labels, and visual styles.

Simple action

The simplest button takes a label and a closure with no arguments:

use waterui::prelude::*;

fn dismiss() -> impl View {
    button("Dismiss").action(|| {
        // Handle click.
    })
}

Reactive state via .state() and State<T>

Most real buttons need to mutate some reactive state — for example, increment a counter. The pattern is two-sided: pass the binding into the action through State<T> extractors, then attach the binding to the button’s environment with .state():

use waterui::prelude::*;

fn increment(counter: &Binding<i32>) -> impl View {
    button("Increment")
        .action(|State(count): State<Binding<i32>>| {
            count.set(count.get() + 1);
        })
        .state(counter)
}

Chain several .state() calls when an action needs more than one binding. They line up positionally with the State<T> parameters in the action closure:

use waterui::prelude::*;

fn reset(x: &Binding<i32>, y: &Binding<i32>) -> impl View {
    button("Reset")
        .action(|State(x): State<Binding<i32>>, State(y): State<Binding<i32>>| {
            x.set(0);
            y.set(0);
        })
        .state(x)
        .state(y)
}

Note: .state() is a ViewExt method that injects the value into the button’s local environment. Inside the action, the State<T> extractor pulls it back out by type and position. This avoids manual clone() dances at every call site and keeps the binding free of accidental capture.

Environment extraction

Any value already present in the environment can be extracted directly — no State wrapper needed. For example, the navigation controller is injected by NavigationStack:

use waterui::prelude::*;
use waterui::navigation::NavigationController;

fn back_button() -> impl View {
    button("Go Back").action(|nav: NavigationController| nav.pop())
}

You can mix State<T> parameters with environment extractors in the same action; the extraction order follows the parameter order.

Async actions

Use action_async when the handler needs to await something. The future is spawned on the local executor, so it can await network calls or file I/O:

use waterui::prelude::*;

async fn fetch_from_server() -> String { unimplemented!() }

fn fetch_button(result: &Binding<String>) -> impl View {
    button("Fetch Data")
        .action_async(|State(result): State<Binding<String>>| async move {
            let data = fetch_from_server().await;
            result.set(data);
        })
        .state(result)
}

Button styles

ButtonStyle controls visual emphasis. Choose the right style to communicate the importance of an action:

Apply with .style() or convenience methods:

use waterui::prelude::*;

fn cta_row() -> impl View {
    hstack((
        button("Primary").bordered_prominent().action(|| {}),
        button("Secondary").bordered().action(|| {}),
        button("Subtle").plain().action(|| {}),
        button("Learn More").link().action(|| {}),
    ))
}

Tip: Use bordered_prominent for the main call-to-action on a screen, and bordered or plain for secondary actions. This creates a clear visual hierarchy.

Custom labels

button(...) accepts any value that converts into a semantic Label, including raw strings. For richer content — an icon plus text, for instance — build a Label:

use waterui::prelude::*;
use waterui::icon::system_icon;

fn add_button() -> impl View {
    button(label("Add Item").icon(system_icon::plus())).action(|| {})
}

Buttons inside a Menu must use a semantic label or set accessibility_label, otherwise the menu cannot announce them to assistive technology.

Toggle

Toggle is a boolean switch backed by a Binding<bool>. It is the natural choice for any on/off setting — Wi-Fi, dark mode, or notification preferences:

use waterui::prelude::*;

fn settings(is_enabled: &Binding<bool>, dark_mode: &Binding<bool>) -> impl View {
    vstack((
        // With a label.
        toggle("Wi-Fi", is_enabled),
        // Without a label.
        Toggle::new(dark_mode),
    ))
}

Toggle styles

pub enum ToggleStyle {
    Automatic, // platform default
    Switch,    // sliding pill
    Checkbox,  // square with checkmark
}

Apply with .style():

use waterui::prelude::*;

fn dark_mode_switch(dark: &Binding<bool>) -> impl View {
    Toggle::new(dark)
        .label("Dark Mode")
        .style(ToggleStyle::Switch)
}

Layout behavior

With a label, Toggle expands horizontally to fill available space, placing the label on the leading edge and the switch on the trailing edge. Without a label, it is content-sized.

Slider

Slider lets users select a value from a continuous range by dragging a thumb. The constructor takes the binding directly; the range defaults to 0.0..=1.0 and is overridden with .range(...):

use waterui::prelude::*;

fn volume_slider(volume: &Binding<f64>) -> impl View {
    slider(volume).range(0.0..=100.0)
}

Labels

use waterui::prelude::*;

fn brightness_slider(brightness: &Binding<f64>) -> impl View {
    slider(brightness)
        .label("Brightness")
        .min_value_label("Dark")
        .max_value_label("Bright")
}

Layout behavior

Slider expands horizontally to fill available space but has a fixed height. In an hstack, it takes up all remaining width after other views are sized:

use waterui::prelude::*;

fn volume_row(volume: &Binding<f64>) -> impl View {
    hstack((
        text("Volume"),
        slider(volume).range(0.0..=100.0),
    ))
}

Stepper

Stepper provides +/- buttons for incrementing or decrementing an i32 value. Use it for precise, discrete adjustments — picking a quantity, setting a timer:

use waterui::prelude::*;

fn quantity_stepper(quantity: &Binding<i32>) -> impl View {
    stepper(quantity)
}

Configuration

use waterui::prelude::*;

fn item_stepper(count: &Binding<i32>) -> impl View {
    stepper(count)
        .label("Items")
        .range(1..=10)
        .step(1)
}

By default, the stepper displays the current value as its label. Use .label(...) to replace it with custom content, or .value_formatter(...) to customise how the value is rendered:

use waterui::prelude::*;

fn temperature_stepper(temperature: &Binding<i32>) -> impl View {
    stepper(temperature)
        .value_formatter(|v| format!("{v}°C"))
        .range(-20..=50)
        .step(5)
}

Layout behavior

With a label, Stepper expands horizontally. The label sits on the leading edge and the +/- buttons on the trailing edge, with flexible space between.

TextField

TextField is a single-line text input field backed by a Binding<Str>. You will use it for usernames, search queries, email addresses, and any short text input:

use waterui::prelude::*;

fn username_field(username: &Binding<Str>) -> impl View {
    vstack((
        // With a label.
        field("Username", username),
        // Without a label, with a placeholder prompt.
        TextField::new(username).prompt("Enter your name"),
    ))
}

Styled text binding

For rich text editing, bind to a StyledStr directly:

use waterui::prelude::*;
use waterui::text::styled::StyledStr;

fn rich_field(value: &Binding<StyledStr>) -> impl View {
    TextField::styled(value)
}

Multi-line input

TextField defaults to a single line. Set a higher line limit, or disable it entirely, for paragraph-style entry:

use waterui::prelude::*;

fn notes(notes: &Binding<Str>) -> impl View {
    TextField::new(notes).line_limit(5)
}

fn unbounded(notes: &Binding<Str>) -> impl View {
    TextField::new(notes).disable_line_limit()
}

Custom selection menu

.selection_menu(...) adds custom actions to the text selection context menu. It accepts any MenuView — most commonly a tuple of buttons or Menu instances:

use waterui::prelude::*;

fn field_with_menu(value: &Binding<Str>) -> impl View {
    TextField::new(value).selection_menu((
        button("Custom Action").action(|| {}),
    ))
}

Layout behavior

TextField expands horizontally to fill available space but has a fixed height. This makes it work naturally in forms and hstack layouts.

Menu

Menu displays a popup of commands when its label is tapped. The items argument is any MenuView — most commonly a tuple of Button, nested Menu, or Divider:

use waterui::prelude::*;

fn options_menu(selected: &Binding<String>) -> impl View {
    Menu::new(
        "Options",
        (
            button("Copy").action(|| {}),
            button("Paste")
                .action(|State(s): State<Binding<String>>| s.set("Pasted".into()))
                .state(selected),
            Divider,
            Menu::new(
                "More",
                (button("Reset").action(|| {}),),
            ),
        ),
    )
}

The first argument is the menu’s semantic label (any IntoLabel). Buttons inside a menu convert automatically into MenuItem::Commands.

Control summary

Here is a quick reference of the controls covered in this chapter and how they behave in layout:

These controls are the building blocks, but what if you need to collect several pieces of data at once? In the next chapter, you will learn how WaterUI’s form system can automatically generate an entire editing UI from a Rust struct.

Forms and data entry

In this chapter, you will:

• Generate a complete form UI from a Rust struct with #[derive(FormBuilder)]
• Understand how Rust types map to UI controls automatically
• Use pickers, date pickers, color pickers, and secure fields
• Validate user input with composable validators
• Build a registration form from scratch

Every app that collects user data needs forms — registration screens, settings panels, profile editors. Building these by hand means wiring up a text field for each string, a toggle for each boolean, a stepper for each number. WaterUI’s form system solves this by generating UI controls from your Rust data structures. Derive a single trait, and your struct becomes an editable form.

A Hydrolysis preview of stable WaterUI data-entry controls used by forms. Example source.

The FormBuilder trait

The FormBuilder trait is the foundation of the form system. It maps a type to a view that can edit a Binding of that type:

pub trait FormBuilder: Sized {
    type View: View;

    fn view<L: IntoLabel>(
        binding: &Binding<Self>,
        label: L,
        placeholder: Str,
    ) -> Self::View;

    fn binding() -> Binding<Self>
    where
        Self: Default + Clone,
    {
        Binding::default()
    }
}

You can implement this trait manually for full control, but in most cases the derive macro does the work for you.

The derive macro

Annotate your struct with #[derive(FormBuilder)], and each field generates an appropriate control:

use waterui::prelude::*;

#[derive(Default, Clone, Debug, FormBuilder, Project)]
pub struct UserProfile {
    /// Display name
    pub name: String,
    /// Account active status
    pub active: bool,
    /// User's current level
    pub level: i32,
}

That is it — three lines of fields, and WaterUI knows how to render a text field, a toggle, and a stepper. The derive macro relies on the Project derive to expose per-field bindings; you can either derive both or use the #[form] attribute, which derives Default, Clone, Debug, FormBuilder, and Project in one step.

Rendering a form

Use the form() function to create a view from a binding:

use waterui::prelude::*;

#[derive(Default, Clone, Debug, FormBuilder, Project)] struct UserProfile { name: String }
fn profile_editor() -> impl View {
    let profile = UserProfile::binding();
    form(&profile)
}

Pre-fill with initial data by constructing the binding directly:

use waterui::prelude::*;

#[derive(Default, Clone, Debug, FormBuilder, Project)] struct UserProfile { name: String }
fn edit_profile(initial: UserProfile) -> impl View {
    let profile = Binding::container(initial);
    form(&profile)
}

Tip: Try it yourself — define a struct with a mix of String, bool, and i32 fields, derive the form, and watch the controls appear.

Type-to-component mapping

The derive macro maps Rust types to controls automatically:

Field labels and placeholders

The derive macro converts each field name from snake_case to a "Title Case" label. A doc comment on the field becomes the placeholder argument passed to FormBuilder::view:

use waterui::prelude::*;

#[form]
pub struct ContactForm {
    /// Enter your email address
    pub email: String,
}

For a String field, that doc comment surfaces as the TextField’s prompt.

Numeric fields

• i32 (and other integer widths) maps to a Stepper with the full i32::MIN..=i32::MAX range.
• f64 and f32 map to a Slider with range 0.0..=1.0.

If you need different ranges or formatting, use a manual implementation (below).

Color fields

Color fields produce a ColorPicker with platform-native UI:

use waterui::prelude::*;

#[form]
pub struct ThemeConfig {
    pub accent_color: Color,
}

Manual form implementation

For custom layouts or fields outside the automatic mapping, implement FormBuilder yourself:

use waterui::prelude::*;
use waterui::form::secure::{Secure, secure};

#[derive(Clone, Project)]
struct LoginForm {
    username: String,
    password: Secure,
}

impl FormBuilder for LoginForm {
    type View = waterui::layout::stack::VStack<((waterui::component::TextField, waterui::form::SecureField),)>;

    fn view<L: IntoLabel>(binding: &Binding<Self>, label: L, placeholder: Str) -> Self::View {
        // Project the struct binding into per-field bindings.
        let projected = binding.project();
        vstack((
            <String as FormBuilder>::view(&projected.username, label, placeholder),
            secure("Password", &projected.password),
        ))
    }
}

The key trick is Project. Deriving it (or using #[form]) gives you a LoginForm::project(binding) helper that returns a struct of per-field Bindings, so each control sees only the slice of state it needs.

Individual form controls

Beyond the automatic mapping, WaterUI provides specialised controls for specific data entry tasks. You can use these in both auto-generated and manually built forms.

Color picker

ColorPicker provides a platform-native color selection interface:

use waterui::prelude::*;
use waterui::form::picker::color::ColorPicker;

fn accent_picker(accent: &Binding<Color>) -> impl View {
    ColorPicker::new("Accent Color", accent).with_alpha()
}

.with_alpha() enables the alpha channel; .with_hdr() enables HDR color selection.

Date picker

DatePicker adapts to the bound type — jiff::civil::Date, Time, or DateTime — and supports several picker layouts:

use waterui::prelude::*;
use waterui::form::picker::date::{DatePicker, DatePickerType};
use jiff::civil::Date;

fn birthday_picker(date: &Binding<Date>) -> impl View {
    DatePicker::new(date)
        .label("Birthday")
        .ty(DatePickerType::Date)
}

Date picker types:

Picker (selection list)

Picker lets users select from a list of options. Each item is a text(label).tag(value) — the label is what the user sees, the tag is the value written back into the binding:

use waterui::prelude::*;
use waterui::form::picker::{Picker, PickerStyle};

#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
enum Plan { Free, Pro, Team }

fn plan_picker(selection: &Binding<Plan>) -> impl View {
    let items = vec![
        text("Free").tag(Plan::Free),
        text("Pro").tag(Plan::Pro),
        text("Team").tag(Plan::Team),
    ];
    Picker::new(items, selection).style(PickerStyle::Menu)
}

Picker styles:

Secure field

SecureField masks input and uses automatic memory zeroing (via zeroize) for password-grade security. Use it for passwords, API keys, and other sensitive data:

use waterui::prelude::*;
use waterui::form::secure::{Secure, secure};

fn password_field(password: &Binding<Secure>) -> impl View {
    secure("Password", password)
}

The Secure type wraps a String with:

• Display redaction: Debug output shows Secure(****).
• Memory zeroing: the inner string is zeroed on drop.
• Hashing helper: .hash() produces a bcrypt hash.

Warning: Never store raw passwords. Always use .hash() before persisting to a database or sending over the network.

Building a registration form

Here is a complete example that ties auto-generation, a submit button, and reactive state together:

use waterui::prelude::*;

#[form]
pub struct Registration {
    pub username: String,
    pub email: String,
    pub age: i32,
    pub newsletter: bool,
}

fn registration_form() -> impl View {
    let form_data = Registration::binding();

    vstack((
        text("Create Account").title(),

        // Auto-generated form
        form(&form_data),

        // Submit button: capture the form state and read it on click.
        button("Register")
            .bordered_prominent()
            .action(|State(data): State<Binding<Registration>>| {
                let registration = data.get();
                waterui::log::info!(
                    username = %registration.username.as_str(),
                    "registration submitted"
                );
            })
            .state(&form_data),
    ))
}

Validation

A form is only as good as the data it collects. WaterUI provides a composable validation system through the Validator trait and the Validatable extension. Range<T>, regex::Regex, and the marker Required come out of the box:

use waterui::prelude::*;
use waterui::form::valid::{Required, Validator};
use regex::Regex;

fn build_validators() {
    // Range validator (note: `Range<T>`, exclusive end)
    let age_validator = 18i32..100;
    assert!(age_validator.validate(42).is_ok());

    // Regex validator (validates `&str` and `String`).
    let email_validator = Regex::new(r"^[^@]+@[^@]+\.[^@]+$")
        .expect("email validator regex must compile");
    assert!(email_validator.validate("[email protected]").is_ok());

    // Combine validators with `.and()` and `.or()`.
    let required_email = Required.and(
        Regex::new(r"^[^@]+@[^@]+\.[^@]+$")
            .expect("email validator regex must compile"),
    );
    assert!(required_email.validate("").is_err());
}

Built-in validators

Combinators

• validator_a.and(validator_b) — both must pass; short-circuits on first failure.
• validator_a.or(validator_b) — at least one must pass.

ValidatableView

Wrap a form control with validation to get automatic error display:

use waterui::prelude::*;
use waterui::form::valid::ValidatableView;
use regex::Regex;

fn validated_email(value: &Binding<Str>) -> impl View {
    ValidatableView::new(
        TextField::new(value),
        Regex::new(r"^[^@]+@[^@]+\.[^@]+$").unwrap(),
    )
}

ValidatableView filters the binding (rejecting invalid values from being committed) and displays the validation error message below the control.

Accessing form data

The binding returned by FormBuilder::binding() provides field-level access through projection:

use waterui::prelude::*;

#[form] pub struct Registration { pub username: String }
fn show_summary() -> impl View {
    let form_data = Registration::binding();
    let projected = Registration::project(&form_data);

    vstack((
        // Read a field value.
        text(projected.username.get()),
        // Display reactive values.
        text!("Name: {username}", username = projected.username.clone()),
    ))
}

Form layout tips

1. Use vstack for vertical forms. Stack form controls vertically for a natural settings-screen layout.
2. Mix auto-generated and manual controls. Use form() for the basic fields, then add custom controls (pickers, buttons) manually around it.
3. Validate before submission. Use the Validator combinators to check all fields before processing the form data.
4. Pre-fill with initial data. Pass an initial struct to Binding::container() instead of relying on Default.

You now know how to collect structured data from users. But what about displaying collections of data back to them? In the next chapter, you will learn how to render dynamic lists and collections efficiently.

Lists and collections

In this chapter, you will:

• Display dynamic collections with List::for_each and the Identifiable trait
• Use waterui::reactive::collection::List for reactive, fine-grained collection updates
• Group rows with the new ListSection semantic marker
• Build a complete contacts list with add and remove operations

Every app needs a way to show lists of data — a chat thread, a to-do list, a feed of posts, a directory of contacts. Unlike a fixed set of views you write by hand, these collections grow and shrink at runtime as data changes. WaterUI provides List<V> as the native list surface, for_each to map collections to views, and the new ListSection marker to group rows under semantic headers.

A Hydrolysis preview of sectioned WaterUI lists. Example source.

A first dynamic list

List::for_each is the bridge between a data collection and the rows on screen. You give it a collection and a generator that returns one ListItem per element:

use waterui::prelude::*;
use waterui::Identifiable;
use waterui::component::list::{List, ListItem};

#[derive(Clone)]
struct TodoItem {
    id: i32,
    title: String,
    done: bool,
}

impl Identifiable for TodoItem {
    type Id = i32;
    fn id(&self) -> i32 { self.id }
}

fn todo_list(items: Vec<TodoItem>) -> impl View {
    List::for_each(items, |item| {
        ListItem::new(hstack((
            text(item.title),
            spacer(),
            if item.done { text("Done") } else { text("Pending") },
        )))
    })
}

List is a native, scrolling, platform-styled surface. On iOS it renders as an inset-grouped UITableView; on macOS as an NSTableView with group rows; on Material backends as a list with section dividers.

The Identifiable trait

Every item in a for_each generator must implement Identifiable. The trait provides a stable identity for each element so the framework can efficiently diff, insert, and remove rows when the collection changes:

use core::hash::Hash;
pub trait Identifiable {
    type Id: Hash + Ord + Clone;
    fn id(&self) -> Self::Id;
}

Common Id types are integers, UUIDs, and string keys.

Warning: The identity must be stable — the same data item should always return the same id. Changing an item’s id forces the framework to treat it as a removal followed by an insertion, which is more expensive than an in-place update.

Reactive collections with waterui::reactive::collection::List

A plain Vec works for static data, but lists usually change at runtime. The List<T> type from waterui::reactive::collection is a reactive collection: every mutation emits a fine-grained change notification that the UI observes:

use waterui::reactive::collection::List as ReactiveList;
#[derive(Clone)] struct TodoItem { id: i32, title: String, done: bool }

fn seed() {
    let items: ReactiveList<TodoItem> = ReactiveList::new();

    items.push(TodoItem { id: 1, title: "Buy milk".into(), done: false });
    items.push(TodoItem { id: 2, title: "Write docs".into(), done: false });

    let _ = items.pop();
    items.insert(0, TodoItem { id: 3, title: "Urgent".into(), done: false });
}

Note: Both the rendering surface and the data backend are called List. To keep them apart in code, alias one of them — this chapter uses ReactiveList for the data type and the bare List for the view.

Initialise from a Vec:

use waterui::reactive::collection::List as ReactiveList;
#[derive(Clone)] struct TodoItem { id: i32, title: String, done: bool }
fn from_seed(item1: TodoItem, item2: TodoItem) {
    let _ = ReactiveList::from(vec![item1, item2]);
}

Sectioned lists

The pinned waterui adds a ListSection semantic marker so a single List can express multiple logical groups. Mark the first row of a section with .section(ListSection::new("Header")) and subsequent items belong to that section until another marker is encountered:

use waterui::prelude::*;
use waterui::Identifiable;
use waterui::component::list::{List, ListItem, ListSection};

#[derive(Clone)]
struct ContactRow {
    id: i32,
    name: String,
    section: Option<&'static str>,
}

impl Identifiable for ContactRow {
    type Id = i32;
    fn id(&self) -> i32 { self.id }
}

fn directory(contacts: Vec<ContactRow>) -> impl View {
    List::for_each(contacts, |contact| {
        let mut row = ListItem::new(text(contact.name.clone()));
        if let Some(section) = contact.section {
            row = row.section(ListSection::new(section));
        }
        row
    })
}

ListSection carries an optional header label and footer. Use ListSection::unlabeled() for a visual divider with no header, and .footer(...) to append a caption-style note below the section. The visual treatment is delegated to the platform — iOS renders inset-grouped sections, macOS uses NSTableView group rows, and Material backends translate the marker into section dividers.

Tip: Reach for ListSection whenever a list contains more than one kind of row. Grouping rows by topic is exactly the use case the upstream dev branch added the marker for.

Editing: delete and reorder

List exposes editing(...), on_delete(...), and on_move(...) builders. The handlers pull ListDelete (a row index) and ListMove (from/to indices) from the environment so you can dispatch on them just like any other extractor:

use waterui::prelude::*;
use waterui::Identifiable;
use waterui::component::list::{List, ListDelete, ListItem, ListMove};
use waterui::reactive::collection::List as ReactiveList;

#[derive(Clone)] struct Contact { id: i32 }
impl Identifiable for Contact { type Id = i32; fn id(&self) -> i32 { self.id } }
fn editable(items: ReactiveList<Contact>) -> impl View {
    let editing = Binding::bool(false);
    List::for_each(items.clone(), |item| ListItem::new(text(item.id.to_string())))
        .editing(editing.clone())
        .on_delete(
            move |State(items): State<ReactiveList<Contact>>, ListDelete(index): ListDelete| {
                items.remove(index);
            },
        )
        .on_move(
            move |State(items): State<ReactiveList<Contact>>, ListMove(movement): ListMove| {
                let _ = (items, movement);
                // perform reorder on the reactive list
            },
        )
        .state(&items)
}

Per-row controls — ListItem::deletable(false), for instance — refine the behavior on a row-by-row basis.

Static lists from iterators

When the data is genuinely static, you can collect any iterator of views into a VStack:

use waterui::prelude::*;

fn fruit_list() -> impl View {
    let names = ["Apple", "Banana", "Cherry"];
    let stack: VStack<_> = names.into_iter().map(text).collect();
    stack
}

This produces a VStack with default 10pt spacing. There is no virtualization here — every item is laid out at once — so prefer List::for_each plus a reactive collection for anything that might grow.

Building a complete list

Here is a contacts screen with a reactive list, a typed Contact model, and an add button:

use waterui::prelude::*;
use waterui::Identifiable;
use waterui::component::list::{List, ListItem};
use waterui::reactive::collection::List as ReactiveList;

#[derive(Clone)]
struct Contact { id: i32, name: String }

impl Identifiable for Contact {
    type Id = i32;
    fn id(&self) -> i32 { self.id }
}

fn contacts_screen() -> impl View {
    let contacts: ReactiveList<Contact> = ReactiveList::from(vec![
        Contact { id: 1, name: "Alice".into() },
        Contact { id: 2, name: "Bob".into() },
    ]);
    let next_id = Binding::i32(3);

    vstack((
        text("Contacts").title(),

        // Add button: capture both bindings via State<T>.
        button("Add Contact")
            .action(
                |State(contacts): State<ReactiveList<Contact>>,
                 State(next_id): State<Binding<i32>>| {
                    let id = next_id.get();
                    contacts.push(Contact { id, name: format!("Contact {id}") });
                    next_id.set(id + 1);
                },
            )
            .state(&contacts)
            .state(&next_id),

        // The list itself.
        List::for_each(contacts, |contact| ListItem::new(text(contact.name))),
    ))
}

Tip: Try extending this example by adding a delete button next to each contact. You can either use the on_delete handler shown above, or attach a per-row button that captures the contact’s id and removes it manually.

Performance considerations

1. Use waterui::reactive::collection::List<T> for mutable collections. It emits fine-grained change notifications. A plain Vec is suitable only for static data.
2. Keep Identifiable::id() stable. Changing an item’s id forces a removal + insertion instead of an in-place update.
3. Wrap with a List for backend virtualization. List::for_each produces a native list surface that can lazily realise rows.
4. Avoid expensive closures in the generator. It is invoked for each visible row. Push expensive computation into async tasks or cached Computed values.
5. Group with ListSection, not extra stacks. A single List with sections gives the platform full control over chrome and scroll performance; nested stacks defeat virtualization.

You can now display any dynamic data set. But what if you need to show different views depending on a condition — a loading spinner while data loads, or a login prompt when the user is not authenticated? That is the topic of the next chapter.

Conditional rendering

In this chapter, you will:

• Show and hide views reactively with the when function
• Chain conditions with .or() and .otherwise() for multi-branch logic
• Derive boolean conditions from signals using .map() and .equal_to()
• Pick between when and match + .anyview() for complex branching

Think about the screens in a typical app: a loading spinner while data fetches, a “Welcome back!” message when the user is logged in, a “Please log in” prompt when they are not. Your UI needs to show different things based on conditions that can change at any moment. WaterUI provides the when function for exactly this — unlike Rust’s built-in if/else (which evaluates once at build time), when creates reactive branches that automatically swap views as conditions change.

Basic usage

when takes a reactive boolean condition and a builder closure that returns the view to show when the condition is true:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn maybe_message(show_message: &Binding<bool>) -> impl View {
    when(show_message.clone(), || text("This message is visible!"))
}

When show_message is false, nothing is rendered. The UI updates automatically whenever the binding changes.

Adding a fallback with .otherwise()

Use .otherwise() to provide an alternative view when the condition is false:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn login_state(is_logged_in: &Binding<bool>) -> impl View {
    when(is_logged_in.clone(), || text("Welcome back!"))
        .otherwise(|| text("Please log in"))
}

This is the reactive equivalent of an if/else expression — but it responds to signal changes at runtime.

Chaining conditions with .or()

For multi-branch logic (analogous to if/else if/else), chain .or() calls. Each .or() adds another conditional branch; the chain must end with .otherwise():

use waterui::prelude::*;
use waterui::widget::condition::when;

fn status_text(state: &Binding<i32>) -> impl View {
    when(state.equal_to(0), || text("Loading..."))
        .or(state.equal_to(1), || text("Ready"))
        .or(state.equal_to(2), || text("Error"))
        .otherwise(|| text("Unknown state"))
}

The first matching condition wins — subsequent branches are not evaluated.

Note: Think of this as a reactive match. The conditions are checked in order, and only the first matching branch renders.

Condition types

when accepts any type that implements IntoComputed<bool>. In practice you will use a handful of common patterns.

Binding<bool>

The simplest case — a boolean binding directly:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn visible(show: &Binding<bool>) -> impl View {
    when(show.clone(), || text("Visible"))
}

Negated binding

Binding<bool> implements Not, which produces a new signal:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn hidden(show: &Binding<bool>) -> impl View {
    // Show only when the binding is `false`.
    when(!show.clone(), || text("Hidden content revealed"))
}

Derived Computed<bool>

Any Computed<bool> works as a condition. Build one with SignalExt::map:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn positive_indicator(count: &Binding<i32>) -> impl View {
    let is_positive = count.map(|n| n > 0).computed();
    when(is_positive, || text("Count is positive"))
}

Derived conditions with SignalExt

SignalExt ships with comparison helpers that produce Computed<bool> directly. They are the most readable way to turn a value into a condition:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn name_status(name: &Binding<Str>) -> impl View {
    when(name.is_empty(), || text("Please enter your name"))
        .otherwise(|| text!("Hello, {name}!"))
}

.equal_to() for value comparison

use waterui::prelude::*;
use waterui::widget::condition::when;

fn tab_content(selected_tab: &Binding<i32>) -> impl View {
    when(selected_tab.equal_to(0), || text("Home"))
        .or(selected_tab.equal_to(1), || text("Settings"))
        .otherwise(|| text("Unknown tab"))
}

Static bool

Plain bool values also work. When all conditions in a chain are static booleans, the framework picks the matching branch at construction time, so the unused branches never cost anything at runtime:

use waterui::prelude::*;
use waterui::widget::condition::when;

fn debug_only() -> impl View {
    when(cfg!(debug_assertions), || text("Debug mode"))
        .otherwise(|| text("Release mode"))
}

Tip: Use this pattern for feature flags and debug-only UI.

When to reach for .anyview() instead

when().or().otherwise() chains are great for two or three branches. For richer matching — especially when each arm constructs a different concrete view type — destructure the value with match and erase each arm with .anyview():

use waterui::prelude::*;

#[derive(Clone, Copy, PartialEq, Eq)]
enum Mode { A, B, C }

fn render(mode: Mode) -> AnyView {
    match mode {
        Mode::A => text("Mode A").title().anyview(),
        Mode::B => button("Mode B").action(|| {}).anyview(),
        Mode::C => vstack((text("Header"), text("Body"))).anyview(),
    }
}

Use .anyview() whenever you need uniform view types across branches and the boolean ladder of when is starting to feel like an enum match.

Rendering mechanics

Understanding how when works under the hood helps you write efficient conditional views. Internally, When uses the Dynamic view to swap content:

1. The combined condition signal re-evaluates.
2. The framework determines which branch index matched.
3. The previous view is removed and the matching branch’s builder is called.
4. The new view is inserted into the tree.

Each branch closure runs every time the condition switches into that branch, so keep them lightweight. State that should survive a branch toggle must live outside the branch — typically in a Binding owned by the parent.

Patterns and examples

Show / hide with a toggle

use waterui::prelude::*;
use waterui::widget::condition::when;

fn settings_panel() -> impl View {
    let show_advanced = Binding::bool(false);
    let value = Binding::f64(0.5);

    vstack((
        toggle("Show Advanced", &show_advanced),
        when(show_advanced.clone(), {
            let value = value.clone();
            move || {
                vstack((
                    text("Advanced Settings").headline(),
                    slider(&value).range(0.0..=1.0),
                ))
            }
        }),
    ))
}

Loading states

use waterui::prelude::*;
use waterui::widget::condition::when;

fn data_view(loading: &Binding<bool>, data: &Binding<Str>) -> impl View {
    let data = data.clone();
    when(loading.clone(), || text("Loading..."))
        .otherwise(move || text!("{data}"))
}

Multi-state status indicator

use waterui::prelude::*;
use waterui::widget::condition::when;

fn status_indicator(status: &Binding<i32>) -> impl View {
    when(status.equal_to(0), || text("Idle").color(Grey))
        .or(status.equal_to(1), || text("Running").color(Green))
        .or(status.equal_to(2), || text("Warning").color(Yellow))
        .otherwise(|| text("Error").color(Red))
}

Best practices

1. Always end chains with .otherwise(). A bare when() without .otherwise() renders nothing when the condition is false. Multi-branch chains require .otherwise() to close.
2. Use signal combinators, not .get(). Calling .get() inside a when condition or branch closure breaks reactivity. Prefer .map(), .is_empty(), .equal_to(), and friends.
3. Keep branch closures pure. Branches return views without side effects. They may run multiple times as conditions toggle.
4. Prefer when over Rust if/else in view bodies. Rust’s if evaluates once at construction time; when updates as conditions change.
5. Switch to .anyview() when branches diverge. Once you reach four or more arms, or each arm produces a different concrete view type, a match plus .anyview() is clearer than a long when chain.

Quick reference

You now have the tools to build dynamic, condition-driven interfaces. The final piece of the UI puzzle is navigation — how do you move between screens, manage a navigation stack, and organize your app with tabs? That is exactly what the next chapter covers.

Navigation

In this chapter, you will:

• Build hierarchical navigation with NavigationStack and NavigationView
• Push screens with NavigationLink and route values with NavigationLink::value
• Drive the stack programmatically with NavigationPath and NavigationPathController
• Organize your app with tabs using Tabs and Tab

As your app grows beyond a single screen, you need a way to move between them. A user taps a contact to see their details, navigates to settings, or switches between tabs. WaterUI provides a declarative navigation system that lowers to native platform patterns — UINavigationController on Apple platforms, fragment navigation on Android — giving your app a first-class feel on every platform.

A Hydrolysis preview of WaterUI navigation chrome and links. Example source.

NavigationStack

NavigationStack is the container that manages a stack of navigation views. Think of it as a deck of cards: the root screen is at the bottom, and each navigation action pushes a new card on top.

use waterui::prelude::*;

fn home_screen() -> impl View { text("Home") }

fn app_root() -> impl View {
    NavigationStack::new(home_screen())
}

The root view is displayed initially. When navigation occurs (via NavigationLink or programmatically), new screens slide in on top.

NavigationView

Every screen in a stack is a NavigationView. It pairs a navigation bar with your content. The most ergonomic way to build one is the .title(...) modifier from ViewExt, which wraps any view in a NavigationView:

use waterui::prelude::*;

fn detail_screen(name: &str) -> NavigationView {
    vstack((
        text(name.to_string()).title(),
        text("Some detail content"),
    ))
    .title("Detail")
}

You can also call NavigationView::new(title, content) directly when you want full control over the bar.

Title display mode

Control how the title appears in the navigation bar:

use waterui::prelude::*;

fn settings(content: impl View) -> NavigationView {
    content.title("Settings").large_title()
}

fn detail(content: impl View) -> NavigationView {
    content.title("Detail").inline_title()
}

The NavigationTitleDisplayMode enum has three variants:

Tip: Follow platform conventions — use .large_title() on root screens and .inline_title() on pushed detail screens. This matches what users expect on iOS and macOS.

Bar slots

NavigationView exposes leading and trailing slots so you can place toolbar content beside the title:

use waterui::prelude::*;

fn toolbar_screen(content: impl View) -> NavigationView {
    content
        .title("Inbox")
        .navigation_bar_leading(button("Cancel").action(|| {}))
        .navigation_bar_trailing(button("Done").action(|| {}))
}

For full customisation — bar background color, hidden state, or a search field — set the Bar fields directly via NavigationView::new(...) and friends.

NavigationLink

The simplest way to add push navigation is NavigationLink. It renders as a tappable element that pushes a new screen when activated:

use waterui::prelude::*;

fn settings_content() -> impl View { text("Settings") }
fn profile_content() -> impl View { text("Profile") }

fn home_screen() -> impl View {
    vstack((
        text("Home").title(),
        NavigationLink::new(
            "Go to Settings",
            || settings_content().title("Settings"),
        ),
        NavigationLink::new(
            "View Profile",
            || profile_content().title("Profile"),
        ),
    ))
}

The first argument is the label (any IntoLabel), and the second is a closure that returns the destination NavigationView when the link is tapped. The closure is a ViewBuilder, so it only runs when navigation actually occurs.

Note: NavigationLink must live inside a NavigationStack. A debug assertion fires if it is used outside a navigation context.

Programmatic navigation with NavigationPath

NavigationLink is great for simple drill-downs, but real apps need deep links, “back to root” actions, and routing from button handlers. For programmatic control, model navigation with a typed NavigationPath<T>:

use waterui::prelude::*;

#[derive(Clone, PartialEq, Eq)]
enum Route {
    Detail(i32),
    Settings,
}

fn detail_screen(id: i32) -> impl View { text!("Detail {id}") }
fn settings_screen() -> impl View { text("Settings") }
fn home_screen() -> impl View { text("Home") }

fn app() -> impl View {
    let path: NavigationPath<Route> = NavigationPath::new();

    NavigationStack::with(path.clone(), home_screen())
        .destination(|route| match route {
            Route::Detail(id) => detail_screen(id).title("Detail"),
            Route::Settings => settings_screen().title("Settings"),
        })
}

The destination closure maps each route value to a NavigationView. This pattern gives you type-safe routing — the compiler ensures every variant is handled.

Pushing with NavigationLink::value

When the stack is path-backed, prefer NavigationLink::value for declarative pushes. The link reads NavigationPathController<T> from the environment automatically and pushes the value when tapped:

use waterui::prelude::*;

#[derive(Clone, PartialEq, Eq)] enum Route { Detail(i32) }
fn home_with_links() -> impl View {
    vstack((
        text("Home").title(),
        NavigationLink::value("Show item 42", Route::Detail(42)),
    ))
}

Driving the path imperatively

NavigationPath is backed by a reactive list. Mutate it from button handlers via NavigationPathController<T>, which is automatically extracted from the environment:

use waterui::prelude::*;

#[derive(Clone, PartialEq, Eq)] enum Route { Detail(i32) }
fn manual_push() -> impl View {
    button("Open detail")
        .action(|controller: NavigationPathController<Route>| {
            controller.push(Route::Detail(42));
        })
}

fn back_to_root() -> impl View {
    button("Reset")
        .action(|controller: NavigationPathController<Route>| controller.clear())
}

NavigationPathController exposes push, pop, pop_n, and clear. Pre-populating a path is just as easy:

use waterui::prelude::*;
#[derive(Clone, PartialEq, Eq)] enum Route { Detail(i32), Settings }
fn prepopulated_stack() -> impl View {
    let path = NavigationPath::from(vec![Route::Settings, Route::Detail(1)]);
    NavigationStack::with(path, text("Home"))
}

Navigation transitions

Control the transition animation style on the stack:

use waterui::prelude::*;
use waterui::navigation::NavigationTransition;

#[derive(Clone, PartialEq, Eq)] enum Route { Settings }
fn fade_stack(root: impl View) -> impl View {
    let path: NavigationPath<Route> = NavigationPath::new();
    NavigationStack::with(path, root)
        .destination(|_| text("placeholder").title("placeholder"))
        .transition(NavigationTransition::Fade)
}

Imperative navigation with NavigationController

For navigation outside a typed path — pushing an arbitrary NavigationView directly — extract NavigationController from the environment:

use waterui::prelude::*;

fn detail_content() -> impl View { text("Detail") }

fn back_button() -> impl View {
    button("Go Back").action(|nav: NavigationController| nav.pop())
}

fn detail_button() -> impl View {
    button("Show Detail").action(|nav: NavigationController| {
        nav.push(detail_content().title("Detail"));
    })
}

NavigationController wraps a CustomNavigationController provided by the backend renderer; you typically never implement it yourself.

Tabs

Most apps organise their top-level screens with tabs. Tabs provides a tabbed container with a tab bar:

use waterui::prelude::*;
use waterui::id::{Mapping, TaggedView};
use waterui::navigation::tab::{Tab, Tabs};

fn home_content() -> impl View { text("Home") }
fn settings_content() -> impl View { text("Settings") }

fn main_app() -> impl View {
    let tabs = Mapping::new();
    let home_id = tabs.register("home");
    let settings_id = tabs.register("settings");
    let selection = Binding::container(home_id);

    Tabs::new(
        selection,
        vec![
            Tab::new(
                TaggedView::new(home_id, AnyView::new(text("Home"))),
                || home_content().title("Home"),
            ),
            Tab::new(
                TaggedView::new(settings_id, AnyView::new(text("Settings"))),
                || settings_content().title("Settings"),
            ),
        ],
    )
}

Tab structure

Each Tab consists of:

• Label: A TaggedView<Id, AnyView> that provides both the visual tab label and a unique identifier for selection.
• Content: A ViewBuilder that returns a NavigationView. Each tab gets its own independent navigation experience.

Tab position

Control whether the tab bar appears at the top or bottom:

use waterui::prelude::*;
use waterui::navigation::tab::{TabPosition, Tabs};
use waterui::id::{Id, Mapping};

fn placeholder_tabs() -> Vec<waterui::navigation::tab::Tab<Id>> { Vec::new() }
fn top_tabs() -> impl View {
    let tabs = Mapping::new();
    let selected = tabs.register("home");
    Tabs::new(Binding::container(selected), placeholder_tabs()).position(TabPosition::Top)
}

Selection binding

The selection binding is a Binding<Id> that tracks the currently active tab. You can read and write it programmatically to switch tabs from anywhere in the app.

Convenience constructor

navigation(title, view) is a shortcut equivalent to NavigationView::new(title, view):

use waterui::prelude::*;

fn ad_hoc() -> NavigationView {
    navigation("Inbox", text("Empty"))
}

Putting it all together

Here is a complete app skeleton with tabs, a typed navigation path, and programmatic routing:

use waterui::prelude::*;
use waterui::id::{Mapping, TaggedView};
use waterui::navigation::tab::{Tab, Tabs};

#[derive(Clone, PartialEq, Eq)]
enum BrowseRoute {
    Item(i32),
}

fn browse_root() -> impl View {
    vstack((
        text("Browse Items").title(),
        NavigationLink::value("View item 42", BrowseRoute::Item(42)),
    ))
}

fn item_detail(id: i32) -> impl View {
    vstack((
        text(format!("Item #{id}")).headline(),
        button("Go Back")
            .action(|nav: NavigationController| nav.pop()),
    ))
}

fn profile_view() -> impl View { text("Profile Screen") }

fn app() -> impl View {
    let tabs = Mapping::new();
    let browse_id = tabs.register("browse");
    let profile_id = tabs.register("profile");
    let tab_selection = Binding::container(browse_id);

    Tabs::new(
        tab_selection,
        vec![
            Tab::new(
                TaggedView::new(browse_id, AnyView::new(text("Browse"))),
                || {
                    let path: NavigationPath<BrowseRoute> = NavigationPath::new();
                    NavigationStack::with(path, browse_root())
                        .destination(|route| match route {
                            BrowseRoute::Item(id) => item_detail(id).title("Item"),
                        })
                        .title("Browse")
                },
            ),
            Tab::new(
                TaggedView::new(profile_id, AnyView::new(text("Profile"))),
                || profile_view().title("Profile"),
            ),
        ],
    )
}

Navigation tips

1. Use NavigationLink for simple push navigation. It hides the NavigationController extraction for you.
2. Use NavigationPath<T> plus NavigationLink::value for typed routing. The compiler keeps every destination in sync with every push site.
3. Each tab gets its own navigation stack. Wrap each tab’s content in a NavigationStack (or use NavigationView directly) to give each tab an independent stack of pushed screens.
4. Keep route types small. The type parameter T in NavigationPath<T> must be Clone + 'static. Use enums with associated data for the cleanest destination match.
5. Use .large_title() on root screens. Following platform conventions, root screens typically use large titles that collapse on scroll, while pushed screens use inline titles.

Congratulations — you have now covered the complete Building UIs section. You know how to display text, lay out views, handle user input, build forms, render lists, conditionally show content, and navigate between screens. With these tools, you can build fully functional app interfaces. In Part IV: Rich Content, you will learn how to add media, maps, web views, and more to your apps.

Media: photos, video, and audio

In this chapter, you will:

• Display images from the network with progressive streaming
• Play video with native controls or build your own player UI
• Work with Live Photos and the unified Media enum
• Let users pick media with the platform-native MediaPicker
• Apply GPU-accelerated image filters

Every app eventually needs to show a photo, play a video, or let the user pick something from their library. WaterUI’s media stack handles the hard parts for you: async fetching, progressive decoding, and GPU texture management.

Feature flags and crate layout

The media types live behind cargo features in the waterui crate:

[dependencies]
waterui = { version = "*", features = ["media"] }
# Or for the raw video surface only:
# waterui = { version = "*", features = ["video"] }

media enables both waterui-media and waterui-video; the picker pulls in platform dialogs through the std feature, which is on by default.

waterui-media re-exports the video types, so a single import covers most apps:

use waterui::prelude::*;
use waterui::media::{Photo, Video, VideoPlayer, LivePhoto, Media};

Displaying Images with Photo

Photo is the primary component for showing images from a URL. It fetches the image asynchronously, decodes it through a streaming pipeline, and hands the pixel data to the GPU-backed Image view.

Basic Usage

use waterui::media::Photo;

fn avatar() -> impl View {
    Photo::new("https://static.rust-lang.org/logos/rust-logo-512x512.png")
}

Photo::new accepts anything that implements Into<Url>, including string literals.

Listening for Events

You can observe loading progress through the on_event callback. Because waterui::media re-exports a video Event type, alias the photo event to keep the two clearly separate:

use waterui::media::Photo;
use waterui::media::photo::Event as PhotoEvent;

fn profile_photo() -> impl View {
    Photo::new("https://static.rust-lang.org/logos/rust-logo-512x512.png")
        .on_event(|event| match event {
            PhotoEvent::Loaded => tracing::info!("Image loaded successfully"),
            PhotoEvent::Error(msg) => tracing::error!("Failed to load: {msg}"),
        })
}

photo::Event has two variants:

Reactive filters

Filter modifiers from ViewExt accept signals, so a Binding lets the user adjust filter values in real time without rebuilding the photo:

use waterui::prelude::*;
use waterui::media::Photo;

fn blurry_photo() -> impl View {
    let blur = Binding::f64(0.0);
    let saturation = Binding::f64(1.0);

    vstack((
        Photo::new("https://static.rust-lang.org/logos/rust-logo-512x512.png")
            .blur(blur.clone())
            .saturation(saturation.clone()),
        Slider::new(&blur).range(0.0..=20.0),
        Slider::new(&saturation).range(0.0..=2.0),
    ))
}

See Filters and Visual Effects for the full filter catalog.

Streaming / Progressive Decoding

Photo uses an ImageStreamDecoder internally. As HTTP response chunks arrive, the decoder attempts intermediate decodes at increasing byte thresholds (starting at 24 KB, stepping by 96 KB). For formats that support progressive rendering – JPEG, PNG, GIF, WebP, BMP, ICO, TIFF – you may see a lower-quality preview appear before the final image lands. This is automatic and requires no configuration.

Tip: Progressive decoding is especially valuable on slower connections. Your users see something almost immediately, which makes the app feel faster even before the full image arrives.

How Image Works Under the Hood

The Image struct holds raw pixel data (RGBA8 or RGBA16F) that gets uploaded to a GPU texture on first render. After the texture is created, the CPU-side pixel buffer is dropped, keeping memory usage lean.

use waterui::media::Image;

// Construct directly from pixel data (4 bytes per pixel, RGBA)
let pixels: Vec<u8> = vec![255, 0, 0, 255]; // 1x1 red pixel
let red_dot = Image::new(pixels, 1, 1);

For HDR content on Apple and Android platforms, WaterUI automatically selects the platform image decoder and produces RGBA16F textures. When the output surface does not support HDR, a tone-mapping shader converts the content to SDR transparently.

Video Playback

Whether you are building a media gallery, an onboarding flow with background video, or a full-featured player, WaterUI has you covered with two components:

VideoPlayer – Full-Featured Playback

The quickest way to get video playing is VideoPlayer, which comes with platform-native controls out of the box:

use waterui::media::{AspectRatio, VideoPlayer};

fn trailer() -> impl View {
    VideoPlayer::new("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4")
        .show_controls(true)
        .aspect_ratio(AspectRatio::Fit)
}

Configuration Methods

Video – Raw View

When you need full control over the playback UI – a custom scrubber, gesture-based controls, or a looping background – use Video:

use waterui::prelude::*;
use waterui::media::{AspectRatio, Video};

fn background_video() -> impl View {
    Video::new("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4")
        .aspect_ratio(AspectRatio::Fill)
        .loops(true)
}

Volume and Mute System

Both video components encode mute state into the volume value itself:

• Positive values represent audible volume (e.g. 0.7 = 70%).
• Negative values represent muted state while preserving the original level (e.g. -0.7 means “muted, but restore to 70% on unmute”).

In practice, use the muted method with a Binding<bool> and let the framework handle the encoding:

use waterui::prelude::*;
use waterui::media::VideoPlayer;

fn mutable_player() -> impl View {
    let muted = Binding::bool(false);
    VideoPlayer::new("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4")
        .muted(&muted)
}

Video Events

Subscribe to playback lifecycle events to keep your UI in sync. The video Event is re-exported from waterui::media as Event; the example aliases it to make the variant matches read clearly:

use waterui::media::VideoPlayer;
use waterui::media::Event as VideoEvent;

fn player_with_events() -> impl View {
    VideoPlayer::new("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/Sintel.mp4")
        .on_event(|event| match event {
            VideoEvent::ReadyToPlay => tracing::info!("ready"),
            VideoEvent::Ended => tracing::info!("playback ended"),
            VideoEvent::Buffering => tracing::info!("buffering"),
            VideoEvent::BufferingEnded => tracing::info!("resumed"),
            VideoEvent::Error { message } => tracing::error!("error: {message}"),
            _ => {}
        })
}

Live Photos (Apple)

Live Photos combine a still image with a short video clip: press and hold on an iPhone and the photo comes alive. WaterUI models this through LivePhoto and LivePhotoSource:

use waterui::media::{LivePhoto, Url};
use waterui::media::live::LivePhotoSource;

fn my_live_photo() -> impl View {
    let source = LivePhotoSource::new(
        Url::parse("https://static.rust-lang.org/logos/rust-logo-512x512.png").unwrap(),
        Url::parse("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4").unwrap(),
    );
    LivePhoto::new(source)
}

LivePhoto::new accepts any IntoComputed<LivePhotoSource>, so you can drive it with a reactive signal that changes the photo dynamically.

Note: Live Photos are an Apple-specific feature. On non-Apple platforms, the native backend may fall back to displaying just the still image.

The Unified Media Enum

When your data model may contain images, videos, or Live Photos – imagine a social feed or a chat thread – use the Media enum. It implements View and automatically selects the right component:

use waterui::media::{Media, Url};
use waterui::media::live::LivePhotoSource;

let items: Vec<Media> = vec![
    Media::Image(Url::parse("https://static.rust-lang.org/logos/rust-logo-512x512.png").unwrap()),
    Media::Video(Url::parse("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/TearsOfSteel.mp4").unwrap()),
    Media::LivePhoto(LivePhotoSource::new(
        Url::parse("https://static.rust-lang.org/logos/rust-logo-512x512.png").unwrap(),
        Url::parse("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/SubaruOutbackOnStreetAndDirt.mp4").unwrap(),
    )),
];

Each variant renders via its corresponding component:

Media Picker

Want to let users choose a photo or video from their device? The MediaPicker component presents the platform’s native media selection dialog. It requires the std feature, which is enabled by default.

Basic Selection

use waterui::prelude::*;
use waterui::media::media_picker::{MediaFilter, MediaPicker, Selected};

fn picker_demo() -> impl View {
    let selection: Binding<Option<Selected>> = Binding::container(None);

    MediaPicker::new(&selection)
        .filter(MediaFilter::Image)
}

Media Filters

Control what type of media the user can select:

Custom Label

Replace the default “Select Media” button text:

use waterui::prelude::*;
use waterui::media::media_picker::{MediaPicker, Selected};

fn custom_picker() -> impl View {
    let selection: Binding<Option<Selected>> = Binding::container(None);

    MediaPicker::new(&selection)
        .label(text("Choose a photo"))
}

Accessing the Result

Once the user selects media, inspect the Selected value through its media() accessor:

use waterui::media::Media;
use waterui::media::media_picker::Selected;

fn handle_selection(selected: &Selected) {
    match selected.media() {
        Media::Image(url) => tracing::info!("selected image: {url}"),
        Media::Video(url) => tracing::info!("selected video: {url}"),
        Media::LivePhoto(source) => tracing::info!(?source, "selected live photo"),
    }
}

Image Filters

Filter modifiers come from ViewExt and accept any IntoSignalF32, so you can hand them a literal value or a Binding<f64> for live updates:

use waterui::prelude::*;
use waterui::media::Photo;

fn vintage_photo() -> impl View {
    Photo::new("https://static.rust-lang.org/logos/rust-logo-512x512.png")
        .saturation(0.6)
        .brightness(-0.05)
        .blur(1.5)
}

Common modifiers: .blur(radius), .brightness(amount), .contrast(amount), .saturation(amount). The full list (and how filters compose into a single GPU pass) lives in Filters and Visual Effects.

WaterUI also re-exports filtrate::Filter as waterui::media::Filter if you need to construct filter pipelines manually.

Platform Considerations

Supported Image Formats

The decoding pipeline automatically selects between a platform-native decoder (Apple/Android) and a software fallback depending on the format and platform:

• Software path: JPEG, PNG, GIF, WebP, BMP, ICO, TIFF
• Platform path: AVIF, HEIC/HEIF (Apple & Android only), images with embedded ICC/cICP color profiles

What’s Next

Now that you can display images and play video, the next chapter explores Maps and Location – embedding interactive maps, dropping pins, and tracking the user’s real-time position.

Maps and Location

In this chapter, you will:

• Embed interactive maps with annotations and styles
• Track and display the user’s real-time location
• Build a complete location-aware feature with reactive state
• Understand cross-platform differences in map rendering

Picture a ride-sharing app that follows your car in real time, or a travel guide that drops pins on every restaurant nearby. Maps are one of those features that instantly make an app feel polished and professional. WaterUI gives you native map rendering through the waterui-map crate and cross-platform location access via waterkit-location, all with a declarative, reactive API.

Feature flag: Maps live behind the map feature on waterui. Enable it in Cargo.toml (waterui = { version = "...", features = ["map"] }) so the prelude re-export waterui::map is available.

Crate Overview

The map crate re-exports the location crate for convenience:

use waterui::map::location; // waterkit-location
use waterui::map::Location; // waterkit_location::Location

Coordinates and Regions

Before you can display a map, you need to tell it where to look. That starts with two types: Coordinate and Region.

Coordinate

A geographic point on the globe:

use waterui::map::Coordinate;

let san_francisco = Coordinate::new(37.7749, -122.4194);
let tokyo = Coordinate::new(35.6762, 139.6503);

Coordinate has two fields:

You can convert from a waterkit_location::Location directly:

use waterui::map::Coordinate;
use waterkit_location::Location;

// From a Location reference
let coord = Coordinate::from_location(&location);

// Or via Into
let coord: Coordinate = location.into();

Region

A Region describes the visible area of the map – a center coordinate plus a span in degrees:

use waterui::map::{Coordinate, Region};

// Explicit span
let bay_area = Region::new(
    Coordinate::new(37.7749, -122.4194),
    0.5,  // latitude span in degrees
    0.5,  // longitude span in degrees
);

// Default zoom from a coordinate
let zoomed_in = Region::from_coordinate(Coordinate::new(37.7749, -122.4194));
// Uses 0.05 degree span in both directions

Region implements From<Coordinate>, so you can pass a bare coordinate anywhere a region is expected and get a sensible default zoom.

Displaying a Map

Now let’s put a map on screen. You will find it is just as straightforward as placing any other view.

Basic Map

use waterui::map::{Map, Coordinate, Region};

fn city_map() -> impl View {
    let region = Region::new(
        Coordinate::new(48.8566, 2.3522), // Paris
        0.1,
        0.1,
    );
    Map::new(region)
}

Map::new accepts any Into<Computed<Region>>, meaning you can pass:

• A static Region value
• A reactive Computed<Region> signal that updates the visible area over time

Centering on a Coordinate

If you only have a coordinate and want the default zoom:

use waterui::map::{Map, Coordinate};

fn pin_map() -> impl View {
    Map::centered_on(Coordinate::new(35.6762, 139.6503))
}

Map::centered_on also accepts Computed<Coordinate> for reactive updates.

Centering on a Location

When working directly with the waterkit-location crate:

use waterui::map::Map;
use waterkit_location::Location;

fn location_map(location: Computed<Location>) -> impl View {
    Map::centered_on_location(location)
}

Annotations (Map Markers)

A map without markers is just a pretty picture. Add pins with Annotation:

use waterui::map::{Map, Coordinate, Region, Annotation};

fn annotated_map() -> impl View {
    let sf = Coordinate::new(37.7749, -122.4194);
    let la = Coordinate::new(34.0522, -118.2437);

    Map::new(Region::new(Coordinate::new(36.0, -120.0), 5.0, 5.0))
        .annotations(vec![
            Annotation::new(sf, "San Francisco"),
            Annotation::new(la, "Los Angeles")
                .subtitle("City of Angels"),
        ])
}

Annotation API

Each annotation has these fields:

Reactive Annotations

Since annotations accepts Into<Computed<Vec<Annotation>>>, you can drive the marker list from a reactive signal. This is perfect for search results, live tracking, or any data that changes over time:

use waterui::prelude::*;
use waterui::map::{Map, Coordinate, Region, Annotation};

fn dynamic_markers() -> impl View {
    let markers = Binding::container(vec![
        Annotation::new(Coordinate::new(37.7749, -122.4194), "Start"),
    ]);

    Map::new(Region::default())
        .annotations(markers.into_computed())
}

Map Styles

Choose between three display modes to match the feel of your app:

use waterui::map::{Map, Region, MapStyle};

fn satellite_view() -> impl View {
    Map::new(Region::default())
        .style(MapStyle::Satellite)
}

User Location

Showing the User’s Position

Display the familiar blue dot indicating the user’s current location:

use waterui::map::{Map, Region};

fn location_enabled_map() -> impl View {
    Map::new(Region::default())
        .shows_user_location(true)
}

Note: This requires location permission. Use Location::ask_permission() or let the platform prompt the user automatically.

Following the User

follows_location both centers the map on a reactive Location stream and enables the user-location indicator. The map moves as the user moves – great for navigation or fitness tracking:

use waterui::map::Map;
use waterkit_location::Location;

fn tracking_map(location: Computed<Location>) -> impl View {
    Map::new(Region::default())
        .follows_location(location)
}

This is equivalent to calling shows_user_location(true) plus binding the region to the location signal.

Map Interaction Controls

Fine-tune the map’s interactive behavior. For example, you might want a non-interactive overview map in a list cell:

use waterui::map::{Map, Region};

fn static_overview() -> impl View {
    Map::new(Region::default())
        .is_interactive(false)  // Disable pan and zoom
        .shows_compass(false)   // Hide the compass
        .shows_scale(true)      // Show the scale bar
}

Getting the User’s Location

The waterkit-location crate provides a cross-platform API for accessing device location:

use waterkit_location::{Location, LocationError};

async fn where_am_i() -> Result<(), LocationError> {
    let location = Location::get().await?;

    tracing::info!("Lat: {}", location.latitude());
    tracing::info!("Lon: {}", location.longitude());

    if let Some(alt) = location.altitude() {
        tracing::info!("Altitude: {} meters", alt);
    }

    tracing::info!("Accuracy: {:?} meters", location.horizontal_accuracy());
    tracing::info!("Time: {:?}", location.timestamp());

    Ok(())
}

Location Accessors

Error Handling

Location::get() returns Result<Location, LocationError>:

Permissions

Location::get() calls Location::ask_permission() automatically. If you want to check permission status before presenting the map, call it explicitly:

use waterkit_location::Location;

async fn ensure_location_access() {
    if let Err(e) = Location::ask_permission().await {
        tracing::warn!("Location permission not granted: {e}");
    }
}

Convenience Function

A free function map() is available as a shorthand for Map::new():

use waterui::map::{map, Region};

fn quick_map() -> impl View {
    map(Region::default())
}

Complete Example

Here is a complete example that fetches the user’s location and displays a map centered on it with an annotation:

use waterui::prelude::*;
use waterui::map::{Annotation, Coordinate, Map, MapStyle, Region};
use waterkit_location::Location;

fn location_app() -> impl View {
    let location_binding: Binding<Option<Location>> = Binding::container(None);

    // Reactive map region and annotations derived from the same source signal.
    let region = location_binding.map(|opt| {
        opt.map(|loc| Region::from_coordinate(Coordinate::from(loc)))
            .unwrap_or_default()
    });

    let annotations = location_binding.map(|opt| {
        opt.map(|loc| vec![
            Annotation::new(Coordinate::from(loc), "You are here"),
        ])
        .unwrap_or_default()
    });

    // Fetch the location once when the map appears; the task is cancelled with the view.
    let loc = location_binding.clone();
    Map::new(region)
        .annotations(annotations)
        .style(MapStyle::Standard)
        .shows_user_location(true)
        .shows_compass(true)
        .task(async move {
            match Location::get().await {
                Ok(location) => loc.set(Some(location)),
                Err(e) => tracing::error!("Location error: {e}"),
            }
        })
}

Platform Considerations

The Map component uses the configurable! macro with StretchAxis::Both, meaning it expands to fill available space in both directions by default. Use layout modifiers like .size(width, height), .width(...), or .height(...) to constrain its size when needed.

What’s Next

You have maps and location covered. Next up: WebView, where you will embed web content directly into your app – complete with JavaScript bridges, cookie management, and navigation controls.

WebView

In this chapter, you will:

• Embed web content directly inside your WaterUI application
• Navigate, inject scripts, and execute JavaScript from Rust
• Set up bidirectional communication between Rust and web code
• Manage cookies and redirect behavior programmatically
• Build a minimal in-app browser with back/forward controls

Sometimes the best tool for the job is the web. Maybe you need to display documentation, embed an OAuth login flow, or wrap an existing web app inside your native shell. The waterui-webview crate makes this seamless – you get a full-featured embedded browser with navigation, JavaScript execution, cookie management, and a Rust-to-JS bridge, all from Rust.

Feature flag: WebView lives behind the webview feature on waterui. Enable it in Cargo.toml (waterui = { version = "...", features = ["webview"] }) before importing waterui::webview.

Architecture

The WebView system follows a layered design:

Native backends (Apple, Android) implement CustomWebViewController and inject a WebViewController into the Environment at startup. Your application code then obtains the controller and creates web views through it.

Quick Start

The simplest way to embed web content is with WebView::open:

use waterui::webview::WebView;

fn docs_page() -> impl View {
    WebView::open("https://waterui.dev/docs")
}

WebView::open pulls the WebViewController from the environment automatically, creates a new web view handle, navigates to the URL, and returns a View that renders the embedded browser.

That is all it takes – one line to go from URL to rendered web content.

Creating a WebView Manually

For more control, obtain the controller from the environment, open a fresh WebView, and configure it before placing it in the view hierarchy:

use waterui::prelude::*;
use waterui::webview::{WebView, WebViewController};

fn custom_browser() -> impl View {
    use_env(|controller: WebViewController| {
        let webview = controller.open();
        webview.go_to("https://book.waterui.dev");
        webview.set_user_agent("WaterUIBook/1.0");
        webview
    })
}

WebViewController::open() returns a fresh WebView already wrapped with reactive event state. Use the WebView itself as the imperative handle.

open_then for Post-Creation Configuration

When you want to configure the underlying handle immediately after creation but still build the view in a single expression, use WebView::open_then:

use waterui::webview::WebView;

fn configured_webview() -> impl View {
    WebView::open_then("https://book.waterui.dev", |handle| {
        handle.set_user_agent("WaterUIBook/1.0");
        handle.set_redirects_enabled(false);
    })
}

The closure receives an AnyWebViewHandle, which exposes the same imperative API as WebView (navigation, user agent, cookie store, script injection).

Navigation

Once you have a WebView instance, control navigation imperatively:

// Navigate to a URL
webview.go_to("https://book.waterui.dev");

// Refresh the current page
webview.refresh();

// Stop loading
webview.stop();

// History navigation
webview.go_back();
webview.go_forward();

Reactive Navigation State

WebView exposes reactive signals for history state:

// Returns Computed<bool>
let can_back = webview.can_go_back();
let can_forward = webview.can_go_forward();

These update automatically as the user navigates. Use them to enable/disable back and forward buttons in your custom browser chrome.

Events

Subscribe to navigation lifecycle events through the reactive event() signal:

use waterui::prelude::*;
use waterui::webview::{WebViewController, WebViewEvent};

fn eventful_webview() -> impl View {
    use_env(|controller: WebViewController| {
        let webview = controller.open();
        let events = webview.event(); // impl Signal<Output = WebViewEvent>
        webview
    })
}

WebViewEvent Variants

Error Types

use waterui::webview::WebViewError;

JavaScript Execution

One of the most powerful features of the WebView is the ability to run JavaScript from Rust and get results back.

Running Scripts

Execute JavaScript in the context of the loaded page:

let result = webview.run_javascript("document.title").await;
match result {
    Ok(title) => tracing::info!("Page title: {title}"),
    Err(err) => tracing::error!("JS error: {err}"),
}

run_javascript is async and returns Result<Str, Str>. It executes after the page has loaded. For scripts that must run before the DOM is constructed, use script injection instead.

Script Injection

Inject scripts that run automatically on every page load:

use waterui::webview::ScriptInjectionTime;

// Run before DOM construction
webview.inject_script(
    r#"window.APP_VERSION = "1.0.0";"#,
    ScriptInjectionTime::DocumentStart,
);

// Run after DOM is ready
webview.inject_script(
    r#"document.body.style.backgroundColor = "#f0f0f0";"#,
    ScriptInjectionTime::DocumentEnd,
);

Rust-to-JavaScript Bridge

The WebView supports bidirectional communication through message handlers. This is how you connect your Rust business logic to your web UI.

Setting Up a Handler

Register a Rust function that JavaScript can call:

webview.handle().add_handler("greet", Box::new(|data: &[u8]| {
    let name = String::from_utf8_lossy(data);
    tracing::info!("Greeting requested for: {name}");
    format!("Hello, {name}!").into_bytes()
}));

Calling from JavaScript

The JavaScript API depends on the platform:

// Apple (WKWebView)
window.webkit.messageHandlers.greet.postMessage("World");

// Android
window.greet.postMessage("World");

Setting Up a Convenient Bridge

Combine inject_script and add_handler for a clean API that hides platform differences from your web code:

use waterui::webview::ScriptInjectionTime;

// Inject a friendly JavaScript API
webview.inject_script(r#"
    window.myApp = {
        greet: function(name) {
            window.webkit.messageHandlers.greet.postMessage(name);
        }
    };
"#, ScriptInjectionTime::DocumentStart);

// Register the native handler
webview.handle().add_handler("greet", Box::new(|data: &[u8]| {
    let name = String::from_utf8_lossy(data);
    tracing::info!("JS called greet({name})");
    Vec::new()
}));

Removing a Handler

webview.handle().remove_handler("greet");

Cookies

Manage cookies programmatically – useful for authentication flows or session management:

use waterui::webview::{WebView, cookie::Cookie};

// Set a cookie
fn set_session_cookie(webview: &WebView, session_token: &str) {
    let cookie = Cookie::build(("session", session_token))
        .domain("book.waterui.dev")
        .path("/")
        .secure(true)
        .build()
        .unwrap();

    webview.handle().set_cookie(cookie);
}

// Retrieve all cookies
let cookies = webview.handle().get_cookies();
for c in &cookies {
    tracing::info!("Cookie: {} = {}", c.name(), c.value());
}

The cookie crate (re-exported as waterui::webview::cookie) provides the Cookie type.

Redirect Control

Enable or disable HTTP redirect following:

// Imperatively
webview.set_redirects_enabled(false);

// Reactively via a binding
let allow_redirects = Binding::bool(true);
let webview = controller
    .open()
    .redirects_enabled(allow_redirects);

The redirects_enabled builder method watches the signal and syncs the setting automatically when the value changes.

User Agent

Customize the user agent string sent with requests:

webview.set_user_agent("WaterUIBook/1.0");

Complete Example

Let’s put it all together. Here is a minimal in-app browser with back/forward buttons:

use waterui::prelude::*;
use waterui::webview::{WebView, WebViewController};

fn mini_browser() -> impl View {
    use_env(|controller: WebViewController| {
        let webview = controller.open();
        webview.go_to("https://waterui.dev");

        let can_back = webview.can_go_back();
        let can_forward = webview.can_go_forward();

        let back = webview.clone();
        let forward = webview.clone();
        let reload = webview.clone();

        vstack((
            hstack((
                button("Back")
                    .action(move || back.go_back())
                    .disabled(can_back.map(|ok| !ok)),
                button("Forward")
                    .action(move || forward.go_forward())
                    .disabled(can_forward.map(|ok| !ok)),
                button("Refresh").action(move || reload.refresh()),
            )),
            webview,
        ))
    })
}

The disabled modifier accepts the inverted reactive signal, so the back and forward buttons grey out automatically as the navigation history changes.

Platform Considerations

WebView is declared as a raw view with StretchAxis::Both, so it expands to fill all available space by default. Use .size(width, height), .width(...), .height(...), or a parent layout to control its size.

Downcasting the Handle

When you need access to the platform-specific handle (for example, to configure WKWebView preferences on Apple), you can downcast:

if let Some(native) = webview.handle().downcast_ref::<MyNativeHandle>() {
    // Access platform-specific APIs
}

This is primarily useful for backend authors and advanced platform integration.

What’s Next

You have seen how to embed the entire web inside your app. Next, let’s look at something more focused: Barcodes and QR Codes, where you will generate scannable codes entirely on the GPU.

Barcodes and QR Codes

In this chapter, you will:

• Generate QR codes and Code 128 barcodes from any string
• Customize colors with solid fills, gradients, and GPU content
• Understand how the GPU-based rendering pipeline keeps codes crisp at any size
• Build a shareable QR code component for your app

Need to let users share a link by scanning their phone, or display a product barcode in a retail app? The waterui-barcode crate renders barcodes and QR codes entirely on the GPU. Module data is encoded on the CPU, packed into a bit buffer, and rasterized by a fragment shader – producing crisp output at any resolution with no CPU rasterization overhead.

Feature flag: Barcodes live behind the barcode feature on waterui. Enable it in Cargo.toml (waterui = { version = "...", features = ["barcode"] }) before importing waterui::barcode.

A QR code rendered from the pinned WaterUI barcode component. Example source.

Quick Start

use waterui::barcode::Barcode;

// QR code
fn my_qr() -> impl View {
    Barcode::qr("https://waterui.dev")
}

// 1D barcode
fn my_barcode() -> impl View {
    Barcode::code128("HELLO-WATERUI")
}

Both Barcode::qr and Barcode::code128 return a Barcode struct that implements View and can be placed directly in your view hierarchy.

Supported Symbologies

The BarcodeSymbology enum represents these:

pub enum BarcodeSymbology {
    Qr,
    Code128,
}

Barcode::new(content) is an alias for Barcode::qr(content).

Customizing Colors

The default black-and-white look works fine, but you can match your app’s branding with custom colors.

A Hydrolysis preview of custom barcode colors and gradient fills. Example source.

Dark Module Color

By default, dark modules are black. Change them with dark_color. Srgb::new takes three linear-light channels in 0.0..=1.0:

use waterui::barcode::Barcode;
use waterui::graphics::color::Srgb;

fn blue_qr() -> impl View {
    Barcode::qr("https://waterui.dev")
        .dark_color(Srgb::new(0.0, 0.3, 0.8))
}

Light Module / Background Color

Change the background (light modules and quiet zone):

fn dark_mode_qr() -> impl View {
    Barcode::qr("https://waterui.dev")
        .dark_color(Srgb::WHITE)
        .light_color(Srgb::new(0.1, 0.1, 0.1))
}

Gradient Fill

Apply a linear gradient to the dark modules for a more eye-catching look:

use waterui::barcode::Barcode;
use waterui::graphics::color::Srgb;

fn gradient_qr() -> impl View {
    Barcode::qr("https://waterui.dev")
        .linear_gradient(
            Srgb::new(0.0, 0.5, 1.0), // start color (blue)
            Srgb::new(1.0, 0.0, 0.5), // end color (pink)
            [0.0, 0.0],               // start point (top-left)
            [1.0, 1.0],               // end point (bottom-right)
        )
}

Gradient coordinates are normalized to the barcode’s bounding square:

• [0.0, 0.0] is the top-left corner
• [1.0, 1.0] is the bottom-right corner

GPU-Content Fill

For advanced effects – imagine a QR code filled with an animated gradient, or modules that shimmer with a particle effect – use fill_gpu. Any type implementing GpuView can serve as the fill source:

use waterui::barcode::Barcode;

fn artistic_qr(animated_renderer: impl GpuView) -> impl View {
    Barcode::qr("https://waterui.dev")
        .fill_gpu(animated_renderer)
        .light_color(Srgb::WHITE)
}

This creates a BarcodeGpuFill<V> view that:

1. Renders the fill content to an offscreen texture.
2. Applies a barcode mask effect where dark modules sample from the fill texture and light modules use the configured light color.

The mask is applied via the BarcodeMaskEffect shader, which runs the same packed-matrix lookup as the standard renderer but composites the fill texture instead of a flat color.

The BarcodeFill Enum

Under the hood, the fill style for solid colors and gradients is represented as BarcodeFill:

pub enum BarcodeFill {
    Solid(Srgb),
    LinearGradient {
        start_color: Srgb,
        end_color: Srgb,
        start_point: [f32; 2],
        end_point: [f32; 2],
    },
}

You do not need to construct this directly – dark_color and linear_gradient produce the appropriate variant for you.

How It Works

Understanding the rendering pipeline helps you appreciate why QR codes stay perfectly sharp at any zoom level.

Matrix Generation

When a Barcode view renders, it first generates the module matrix:

• QR codes use the fast_qr crate. The QR matrix dimension depends on the content length and error correction level.
• Code 128 uses the barcoders crate. The 1D bar pattern is repeated on every row to produce a square matrix compatible with the same GPU shader.

Bit Packing

The matrix is packed into a Vec<u32> where each u32 holds 32 modules as individual bits:

• Bit value 1 = dark module
• Bit value 0 = light module

For a 25x25 QR code, the total is 625 modules requiring 20 u32 words. This compact representation is uploaded as a GPU storage buffer.

Fragment Shader Rasterization

The shader (qr_render.wgsl) receives:

• A uniform buffer with the matrix dimension, quiet zone size, output resolution, and color/gradient parameters
• A read-only storage buffer with the packed matrix bits

For each fragment, the shader:

1. Maps the pixel position to a module coordinate (accounting for quiet zone)
2. Looks up the corresponding bit in the packed buffer
3. Outputs the dark or light color (or gradient-interpolated color)

This approach renders at any resolution without aliasing artifacts because the module lookup is resolution-independent.

Quiet Zones

Each symbology includes an appropriate quiet zone (margin):

The quiet zone is rendered in the light color and is included automatically.

API Reference Summary

Barcode

BarcodeGpuFill<V>

BarcodeRenderer

For direct GPU pipeline integration:

The renderer implements GpuRenderer, so it can be used with GpuSurface and the rest of the graphics pipeline.

BarcodeSource

Complete Example

A settings page with a shareable QR code:

use waterui::prelude::*;
use waterui::barcode::Barcode;
use waterui::graphics::color::Srgb;

fn share_page() -> impl View {
    let url = "https://book.waterui.dev";

    vstack((
        text("Scan to join"),
        Barcode::qr(url)
            .dark_color(Srgb::new(0.15, 0.15, 0.15))
            .light_color(Srgb::WHITE),
        text(url),
        Spacer::flexible(),
    ))
}

A branded QR code with a gradient:

use waterui::prelude::*;
use waterui::barcode::Barcode;
use waterui::graphics::color::Srgb;

fn branded_qr() -> impl View {
    Barcode::qr("https://waterui.dev")
        .linear_gradient(
            Srgb::new(0.0, 0.4, 0.9), // brand blue
            Srgb::new(0.0, 0.8, 0.6), // brand green
            [0.0, 0.0],
            [1.0, 1.0],
        )
        .light_color(Srgb::new(0.98, 0.98, 0.98))
}

Platform Considerations

The barcode component is fully cross-platform because it renders entirely through WaterUI’s GPU pipeline (wgpu). There is no dependency on platform- specific barcode libraries.

Note: Barcode scanning (using the device camera to decode barcodes) is not currently part of this crate. It is planned for a future release as part of the WaterKit camera integration.

What’s Next

That wraps up the Rich Content section. You have learned how to display media, embed maps, render web content, and generate barcodes – all from Rust. In the next section, Graphics, you will dive into the GPU and start drawing custom shapes, shaders, and visual effects.

Canvas Drawing

In this chapter, you will:

• Draw shapes, paths, text, and images on a GPU-accelerated 2D canvas
• Use gradients, transforms, clipping, and shadows
• Drive redraws from reactive signals
• Build a custom visualization like an animated clock

Canvas is WaterUI’s 2D vector graphics view, powered by Vello. If you have used the HTML5 Canvas API, the drawing interface will feel familiar – but every command runs on the GPU through wgpu.

Checkpoint status: in the pinned WaterUI commit, waterui-canvas exists at components/visual/canvas as a workspace crate but is not re-exported by the top-level waterui facade. The examples in this chapter describe that crate-level API and are marked rust,ignore until the facade exposes a public waterui::canvas module.

Overview

Canvas is a callback-based drawing surface. You provide a closure that receives a DrawingContext, and WaterUI invokes it whenever the scene needs to repaint. Internally, the canvas drives a Vello scene that is built into a GpuSurface, so your drawing commands compile into GPU-friendly scene data.

A WaterUI Canvas preview showing vector drawing primitives. Example source.

use waterui::prelude::*;
use waterui_canvas::{Canvas, DrawingContext};
use waterui::layout::{Rect, Size};
use waterui::graphics::color::Srgb;

fn my_canvas() -> impl View {
    Canvas::new(|ctx: &mut DrawingContext| {
        ctx.set_fill_style(Srgb::new(0.2, 0.5, 1.0));
        let rect = Rect::from_size(Size::new(200.0, 100.0));
        ctx.fill_rect(rect);
    })
}

Canvas stretches to fill its parent in both axes by default. Use .size(w, h) (from ViewExt) to give it a fixed footprint.

Drawing Context

The DrawingContext is the primary interface for all drawing operations. It provides access to the canvas dimensions and a rich set of drawing methods.

Canvas::new(|ctx: &mut DrawingContext| {
    // Canvas dimensions are available as fields
    let width = ctx.width;
    let height = ctx.height;
    let center = ctx.center(); // Convenience method
    let size = ctx.size();     // Returns Size { width, height }
})

Drawing Shapes

Let’s start with the basics. Every shape begins with setting a fill or stroke style, then calling the corresponding draw method.

Rectangles

The most common primitive. Fill, stroke, or clear rectangles with a single call.

Canvas::new(|ctx: &mut DrawingContext| {
    let rect = Rect::new(Point::new(10.0, 10.0), Size::new(200.0, 100.0));

    // Solid fill
    ctx.set_fill_style(Srgb::new(0.2, 0.6, 1.0));
    ctx.fill_rect(rect);

    // Outlined stroke
    ctx.set_stroke_style(Srgb::new(1.0, 0.0, 0.0));
    ctx.set_line_width(3.0);
    ctx.stroke_rect(rect);

    // Clear a region to transparent
    ctx.clear_rect(Rect::new(Point::new(50.0, 30.0), Size::new(40.0, 40.0)));
})

Circles

Canvas::new(|ctx: &mut DrawingContext| {
    ctx.set_fill_style(Srgb::new_u8(242, 140, 168));
    ctx.fill_circle(Point::new(100.0, 100.0), 50.0);

    ctx.set_stroke_style(Srgb::new(0.0, 0.0, 0.0));
    ctx.set_line_width(2.0);
    ctx.stroke_circle(Point::new(100.0, 100.0), 50.0);
})

Lines

Canvas::new(|ctx: &mut DrawingContext| {
    ctx.set_stroke_style(Srgb::new(1.0, 1.0, 1.0));
    ctx.set_line_width(2.0);
    ctx.stroke_line(
        Point::new(10.0, 10.0),
        Point::new(200.0, 150.0),
    );
})

Path API

For complex shapes, use the Path builder. It follows the HTML5 Canvas path API closely, so you can construct anything from triangles to intricate curves.

Canvas::new(|ctx: &mut DrawingContext| {
    let mut path = ctx.begin_path();

    // Triangle
    path.move_to(Point::new(100.0, 10.0));
    path.line_to(Point::new(190.0, 170.0));
    path.line_to(Point::new(10.0, 170.0));
    path.close();

    ctx.set_fill_style(Srgb::new(0.0, 0.8, 0.4));
    ctx.fill_path(&path);
})

Bezier Curves

Canvas::new(|ctx: &mut DrawingContext| {
    let mut path = ctx.begin_path();
    path.move_to(Point::new(10.0, 100.0));

    // Quadratic curve
    path.quadratic_to(
        Point::new(100.0, 10.0),   // control point
        Point::new(200.0, 100.0),  // end point
    );

    // Cubic curve
    path.bezier_to(
        Point::new(250.0, 10.0),   // control point 1
        Point::new(350.0, 190.0),  // control point 2
        Point::new(400.0, 100.0),  // end point
    );

    ctx.set_stroke_style(Srgb::new(1.0, 0.5, 0.0));
    ctx.set_line_width(3.0);
    ctx.stroke_path(&path);
})

Arcs and Ellipses

Canvas::new(|ctx: &mut DrawingContext| {
    let mut path = ctx.begin_path();

    // Circular arc: center, radius, start_angle, end_angle, anticlockwise
    path.arc(
        Point::new(100.0, 100.0),
        50.0,
        0.0,
        std::f32::consts::PI,
        false,
    );

    // Elliptical arc: center, radii, rotation, start, end, anticlockwise
    path.ellipse(
        Point::new(250.0, 100.0),
        Size::new(80.0, 40.0), // radii
        0.3,                    // rotation in radians
        0.0,                    // start angle
        std::f32::consts::TAU,  // end angle (full ellipse)
        false,
    );

    ctx.set_stroke_style(Srgb::new(0.8, 0.2, 0.8));
    ctx.set_line_width(2.0);
    ctx.stroke_path(&path);
})

Gradients

Canvas supports three types of gradients for richer fills: linear, radial, and conic. Each is created through a builder returned by the drawing context.

Linear Gradient

Canvas::new(|ctx: &mut DrawingContext| {
    let mut gradient = ctx.create_linear_gradient(0.0, 0.0, 200.0, 200.0);
    gradient.add_color_stop(0.0, Srgb::new(1.0, 0.0, 0.0));
    gradient.add_color_stop(0.5, Srgb::new(0.0, 1.0, 0.0));
    gradient.add_color_stop(1.0, Srgb::new(0.0, 0.0, 1.0));

    ctx.set_fill_style(gradient);
    ctx.fill_rect(Rect::from_size(Size::new(200.0, 200.0)));
})

Radial Gradient

The radial gradient interpolates between two circles defined by center and radius.

Canvas::new(|ctx: &mut DrawingContext| {
    let mut gradient = ctx.create_radial_gradient(
        100.0, 100.0, 10.0,  // inner circle: center (100,100), radius 10
        100.0, 100.0, 80.0,  // outer circle: center (100,100), radius 80
    );
    gradient.add_color_stop(0.0, Srgb::new(1.0, 1.0, 1.0));
    gradient.add_color_stop(1.0, Srgb::new(0.0, 0.0, 0.4));

    ctx.set_fill_style(gradient);
    ctx.fill_circle(Point::new(100.0, 100.0), 80.0);
})

Conic (Sweep) Gradient

Canvas::new(|ctx: &mut DrawingContext| {
    let mut gradient = ctx.create_conic_gradient(
        0.0,    // start angle in radians
        100.0,  // center x
        100.0,  // center y
    );
    gradient.add_color_stop(0.0, Srgb::new(1.0, 0.0, 0.0));
    gradient.add_color_stop(0.33, Srgb::new(0.0, 1.0, 0.0));
    gradient.add_color_stop(0.66, Srgb::new(0.0, 0.0, 1.0));
    gradient.add_color_stop(1.0, Srgb::new(1.0, 0.0, 0.0));

    ctx.set_fill_style(gradient);
    ctx.fill_circle(Point::new(100.0, 100.0), 80.0);
})

Image Rendering

Load images from raw pixels or encoded bytes (PNG, JPEG, AVIF) and draw them on the canvas. This is useful for sprite sheets, photo manipulation, or compositing images with custom overlays.

Loading Images

use waterui_canvas::CanvasImage;

// From encoded bytes (PNG, JPEG, AVIF)
let image = CanvasImage::from_bytes(include_bytes!("assets/photo.png"))
    .expect("failed to decode image");

// From raw RGBA pixels
let image = CanvasImage::from_rgba_pixels(width, height, &pixel_data)
    .expect("invalid pixel data");

// Query dimensions
let w = image.width();
let h = image.height();
let size = image.size(); // Returns Size

Drawing Images

Canvas::new(move |ctx: &mut DrawingContext| {
    // Draw at natural size
    ctx.draw_image(&image, Point::new(10.0, 10.0));

    // Draw scaled to a destination rectangle
    let dest = Rect::new(Point::ZERO, Size::new(300.0, 200.0));
    ctx.draw_image_scaled(&image, dest);

    // Draw a sub-region (sprite sheet support)
    let src = Rect::new(Point::ZERO, Size::new(32.0, 32.0));
    let dest = Rect::new(Point::new(50.0, 50.0), Size::new(64.0, 64.0));
    ctx.draw_image_sub(&image, src, dest);
})

Transforms

Canvas maintains a transform stack. Transforms affect all subsequent drawing operations until restored. This is how you create rotated labels, zoomed views, or any kind of coordinate space manipulation.

Canvas::new(|ctx: &mut DrawingContext| {
    ctx.save();

    // Translate to center
    ctx.translate(ctx.width / 2.0, ctx.height / 2.0);
    // Rotate 45 degrees
    ctx.rotate(std::f32::consts::FRAC_PI_4);
    // Scale up
    ctx.scale(2.0, 2.0);

    ctx.set_fill_style(Srgb::new(0.4, 0.8, 0.2));
    let rect = Rect::new(Point::new(-25.0, -25.0), Size::new(50.0, 50.0));
    ctx.fill_rect(rect);

    ctx.restore(); // Back to original transform
})

Transform Methods

Stroke Properties

Fine-grained control over how strokes are rendered.

Canvas::new(|ctx: &mut DrawingContext| {
    ctx.set_stroke_style(Srgb::new(1.0, 1.0, 1.0));

    // Line width
    ctx.set_line_width(4.0);

    // Line cap: how endpoints are drawn
    ctx.set_line_cap(LineCap::Round); // Butt, Round, or Square

    // Line join: how corners are drawn
    ctx.set_line_join(LineJoin::Round); // Miter, Round, or Bevel
    ctx.set_miter_limit(10.0);

    // Dashed lines
    ctx.set_line_dash(vec![10.0, 5.0, 2.0, 5.0]);
    ctx.set_line_dash_offset(3.0);

    ctx.stroke_rect(Rect::from_size(Size::new(200.0, 100.0)));
})

Clipping and Layers

Push clip or alpha layers to constrain or blend drawing operations. Clipping is especially useful for creating shaped windows into your content.

Canvas::new(|ctx: &mut DrawingContext| {
    // Clip to a rectangle
    let clip = Rect::new(Point::new(20.0, 20.0), Size::new(160.0, 160.0));
    ctx.push_clip_rect(clip);

    // Everything drawn here is clipped to the rectangle
    ctx.set_fill_style(Srgb::new(1.0, 0.0, 0.0));
    ctx.fill_circle(Point::new(100.0, 100.0), 120.0);

    ctx.pop_layer();

    // Alpha layer (transparency)
    ctx.push_alpha_rect(0.5, Rect::from_size(ctx.size()));
    ctx.set_fill_style(Srgb::new(0.0, 0.0, 1.0));
    ctx.fill_rect(Rect::from_size(ctx.size()));
    ctx.pop_layer();
})

You can also clip to arbitrary paths using push_clip_path and apply alpha with push_alpha_path.

Fill Rules

Control how complex self-intersecting paths determine their interior.

use waterui_canvas::FillRule;

Canvas::new(|ctx: &mut DrawingContext| {
    // NonZero (default): a point is inside if a ray crosses a non-zero
    // net number of path segments
    ctx.set_fill_rule(FillRule::NonZero);

    // EvenOdd: a point is inside if a ray crosses an odd number of segments
    ctx.set_fill_rule(FillRule::EvenOdd);
})

Shadows

Add shadows to shapes and paths for depth and visual hierarchy.

Canvas::new(|ctx: &mut DrawingContext| {
    ctx.set_shadow_color(Srgb::new(0.0, 0.0, 0.0));
    ctx.set_shadow_blur(10.0);
    ctx.set_shadow_offset(4.0, 4.0);

    ctx.set_fill_style(Srgb::new(1.0, 1.0, 1.0));
    ctx.fill_rect(Rect::new(Point::new(50.0, 50.0), Size::new(100.0, 100.0)));
})

Global Alpha

Set a global opacity that affects all drawing operations.

Canvas::new(|ctx: &mut DrawingContext| {
    ctx.set_global_alpha(0.5); // 50% transparent

    ctx.set_fill_style(Srgb::new(1.0, 0.0, 0.0));
    ctx.fill_rect(Rect::from_size(Size::new(200.0, 200.0)));

    ctx.set_global_alpha(1.0); // Reset to fully opaque
})

Text Rendering

DrawingContext lays out text with Parley and rasterizes glyphs through Vello. Use set_font to choose a typeface, then fill_text or stroke_text to draw. For body content with localization, prefer the text!/Text view – canvas text is best for charts, annotations, and freeform graphics.

use waterui_canvas::{FontSpec, FontWeight, TextMetrics};

Canvas::new(|ctx: &mut DrawingContext| {
    ctx.set_font(FontSpec::new("Arial", 24.0).with_weight(FontWeight::Bold));

    let metrics: TextMetrics = ctx.measure_text("Hello World");
    // metrics.width, metrics.height

    ctx.set_fill_style(Srgb::new(1.0, 1.0, 1.0));
    ctx.fill_text("Hello World", Point::new(50.0, 50.0));
    ctx.stroke_text("Hello World", Point::new(50.0, 100.0));
})

To wrap text within a rectangle, call draw_text_in_rect, which width-constrains the layout and clips overflow.

Reactive Redraws

Canvas redraws on its own whenever a signal you read inside the closure changes. The simplest path is Canvas::with_signal, which threads the current value into your draw callback and tracks it for you:

use waterui::prelude::*;
use waterui_canvas::{Canvas, DrawingContext};
use waterui::layout::Point;
use waterui::graphics::color::Srgb;

fn pulsing_dot(angle: Binding<f32>) -> impl View {
    Canvas::with_signal(angle, |ctx: &mut DrawingContext, angle| {
        let cx = ctx.width / 2.0;
        let cy = ctx.height / 2.0;
        let r = 20.0 + 10.0 * angle.sin();
        ctx.set_fill_style(Srgb::new(0.4, 0.8, 1.0));
        ctx.fill_circle(Point::new(cx, cy), r);
    })
}

Inside Canvas::new, every drawing setter that takes impl IntoSignalF32 or impl IntoSignal<T> registers the signal automatically. Pass bindings directly – never call .get() to feed them in.

If you have to drive an animation that does not depend on a signal, call ctx.request_next_frame() to schedule one more redraw after the current one.

Performance considerations

• GPU-accelerated: every command lands in Vello and renders on the GPU.
• Scene rebuilds: the closure runs whenever a tracked signal changes (or the surface resizes). Keep the work proportional to that change.
• Intermediate texture: Vello renders into Rgba8Unorm, then a blit copies to the final surface (which may be HDR Rgba16Float).
• State stack: save()/restore() is cheap (clone-based). Wrap transform-heavy sections instead of resetting state by hand.
• Image caching: build CanvasImage once and reuse the handle. Decoding inside the draw closure stalls the render thread.

Complete Example: Animated Clock

Here is a clock face that draws hour markers radiating from the center. Because Canvas redraws every frame, the hands could easily be animated with time-based logic.

fn clock_canvas() -> impl View {
    Canvas::new(|ctx: &mut DrawingContext| {
        let cx = ctx.width / 2.0;
        let cy = ctx.height / 2.0;
        let radius = cx.min(cy) - 20.0;

        // Clock face
        ctx.set_fill_style(Srgb::new(0.1, 0.1, 0.15));
        ctx.fill_circle(Point::new(cx, cy), radius);
        ctx.set_stroke_style(Srgb::new(0.8, 0.8, 0.8));
        ctx.set_line_width(2.0);
        ctx.stroke_circle(Point::new(cx, cy), radius);

        // Hour markers
        for i in 0..12 {
            let angle = (i as f32) * std::f32::consts::TAU / 12.0 - std::f32::consts::FRAC_PI_2;
            let inner = radius * 0.85;
            let outer = radius * 0.95;
            ctx.stroke_line(
                Point::new(cx + inner * angle.cos(), cy + inner * angle.sin()),
                Point::new(cx + outer * angle.cos(), cy + outer * angle.sin()),
            );
        }
    })
}

Next

Canvas covers most 2D drawing needs. When you want full wgpu access – custom render pipelines, compute shaders, instanced draws – continue to GPU Rendering with GpuSurface.

GPU rendering with GpuSurface

In this chapter, you will:

• Implement the GpuView trait for custom GPU rendering
• Understand the setup, resize, and render lifecycle
• Handle pointer and gesture input inside GPU surfaces
• Use offscreen rendering for visual testing
• Configure HDR and MSAA for production-quality output

GpuSurface is the foundation of every GPU-rendered view in WaterUI. It hands you a wgpu device, queue, and a per-frame texture, and renders whatever you draw straight onto the platform’s swapchain. Canvas, ShaderSurface, AnimatedMeshGradient, Gradient, and ParticleSystem are all built on top of it.

If Canvas is a paintbrush, GpuSurface is the bare canvas frame and a tube of pigment.

A custom GpuView rendered through water preview. Example source.

Architecture

GpuSurface is a raw view. The native backend allocates the wgpu surface and swapchain for it, and calls your renderer for every frame.

your code (impl GpuView) <-> GpuSurface <-> Native backend (Swift / Kotlin / Hydrolysis)
                                                    |
                                              wgpu device + queue
                                                    |
                                              Metal / Vulkan / GL

A GpuSurface owns exactly one GpuView instance for its lifetime. GpuView::setup is the only place persistent GPU resources for that instance live. Do not move that state into shared caches to survive teardown – when the surface is dropped, the renderer should drop with it.

Layout behaviour

GpuSurface stretches to fill its parent on both axes (the same default as Color). Use .size(w, h) (from ViewExt) when you want a fixed footprint:

use waterui::prelude::*;
use waterui::graphics::GpuSurface;

GpuSurface::new(MyRenderer::default())             // fills available space
GpuSurface::new(MyRenderer::default()).size(400.0, 300.0) // fixed

The GpuView trait

use waterui::Environment;
use waterui::graphics::{GpuContext, GpuFrame};

pub trait GpuView: 'static {
    async fn setup(
        &mut self,
        ctx: &GpuContext<'_>,
        env: &mut Environment,
    );

    fn render(&mut self, frame: &mut GpuFrame);
}

A few details that the type signature does not show:

• setup is async. Awaitable work (asset loading, shader compilation queues) is allowed; for synchronous setup, the body is just straight-line Rust.
• render receives the frame by &mut so you can call frame.request_redraw() to schedule another frame for animation.
• GpuView requires a SubView impl for layout. Use the impl_gpu_subview! macro at the concrete impl site – it wires the default StretchAxis::Both layout for you.

Lifecycle

1. Setup runs once after the wgpu device is ready. Build pipelines, buffers, bind groups, and any owned textures here. Clone ctx.redraw_handle if you need to wake the surface from outside the render loop (for example, when a WaterUI signal changes, a timer fires, or a network response arrives).
2. Resize is implicit: each call to render carries the current frame.width/frame.height. Recreate size-dependent resources by detecting a size change inside render.
3. Render runs whenever the surface is dirty. Submit your wgpu commands into frame.queue. Call frame.request_redraw() to ask for the next frame.

There is no separate needs_redraw callback. Frames advance because either the surface dirtied (size, input, theme), the renderer requested another frame, or a RedrawHandle was poked.

GpuContext

GpuContext is the setup-time payload:

pub struct GpuContext<'a> {
    pub adapter: Option<&'a wgpu::Adapter>,
    pub device: &'a wgpu::Device,
    pub queue: &'a wgpu::Queue,
    pub surface_format: wgpu::TextureFormat,
    pub msaa_samples: u32,
    pub pipeline_cache: Option<&'a wgpu::PipelineCache>,
    pub redraw_handle: RedrawHandle,
}

• surface_format may be Rgba16Float when the platform supports HDR. Call ctx.is_hdr() and gate your blend state on that result – when HDR is active, use blend: None rather than BlendState::REPLACE.
• msaa_samples reflects the backend’s supported sample count, capped by WATERUI_GPU_MSAA (default 4). Use it for both pipeline configuration and any MSAA attachments you create.
• pipeline_cache, when present, should be threaded into every RenderPipelineDescriptor. It dramatically reduces pipeline compile time on subsequent launches.
• redraw_handle is a cheap, thread-safe handle. Clone and stash it; call request_redraw() whenever new state should drive a frame.

GpuFrame

pub struct GpuFrame<'a> {
    pub device: &'a wgpu::Device,
    pub queue: &'a wgpu::Queue,
    pub texture: &'a wgpu::Texture,
    pub view: wgpu::TextureView,
    pub format: wgpu::TextureFormat,
    pub width: u32,
    pub height: u32,
    pub pointer: PointerState,
    pub gesture: GestureState,
    // ...
}

• frame.elapsed() returns the accumulated animation time since the surface was first presented; frame.delta() is the gap since the previous frame.
• frame.is_hovering(), frame.pointer_normalized() give you quick access to pointer interaction.
• frame.gesture exposes pinch/pan/double-tap state forwarded by the backend.
• frame.request_redraw() schedules another frame. frame.was_redraw_requested() lets nested helpers check the flag.

Triangle example

Here is a complete “hello triangle” implementation. The shader lives in its own file, as required for anything beyond a couple of lines.

// triangle.rs
use waterui::{Environment, prelude::*};
use waterui::graphics::{GpuContext, GpuFrame, GpuSurface, GpuView, impl_gpu_subview, wgpu};

#[derive(Default)]
struct TriangleRenderer {
    pipeline: Option<wgpu::RenderPipeline>,
}

impl GpuView for TriangleRenderer {
    async fn setup(
        &mut self,
        ctx: &GpuContext<'_>,
        env: &mut Environment,
    ) {
        let shader = ctx.device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("triangle"),
            source: wgpu::ShaderSource::Wgsl(include_str!("shaders/triangle.wgsl").into()),
        });

        let layout = ctx.device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("triangle-layout"),
            bind_group_layouts: &[],
            push_constant_ranges: &[],
        });

        let blend = if ctx.is_hdr() { None } else { Some(wgpu::BlendState::REPLACE) };

        self.pipeline = Some(ctx.device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("triangle-pipeline"),
            layout: Some(&layout),
            vertex: wgpu::VertexState {
                module: &shader,
                entry_point: Some("vs_main"),
                buffers: &[],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format: ctx.surface_format,
                    blend,
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: None,
            multisample: wgpu::MultisampleState::default(),
            multiview: None,
            cache: ctx.pipeline_cache,
        }));
    }

    fn render(&mut self, frame: &mut GpuFrame) {
        let Some(pipeline) = &self.pipeline else { return };

        let mut encoder = frame.device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
            label: Some("triangle-encoder"),
        });

        {
            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("triangle-pass"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: &frame.view,
                    resolve_target: None,
                    ops: wgpu::Operations {
                        load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
                        store: wgpu::StoreOp::Store,
                    },
                    depth_slice: None,
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
            });
            pass.set_pipeline(pipeline);
            pass.draw(0..3, 0..1);
        }

        frame.queue.submit(std::iter::once(encoder.finish()));
    }
}

impl_gpu_subview!(TriangleRenderer);

pub fn triangle_view() -> impl View {
    GpuSurface::new(TriangleRenderer::default())
}

The macro impl_gpu_subview! provides the layout hooks (StretchAxis::Both, default priority) so GpuSurface can wrap your renderer as a view.

Interactive rendering

Pointer and gesture state arrive on every frame. There is nothing to subscribe to – just read it.

fn render(&mut self, frame: &mut GpuFrame) {
    if let Some((nx, ny)) = frame.pointer_normalized() {
        self.update_hover(nx, ny);
        frame.request_redraw(); // keep animating while the pointer is over us
    }

    if frame.gesture.is_pinching() {
        self.zoom *= frame.gesture.pinch_scale;
    }

    if frame.gesture.double_tap {
        self.reset_view();
    }
}

Driving redraws from outside

For animations that depend on something other than the frame loop – a timer, a Binding, an incoming network message – clone ctx.redraw_handle during setup and call request_redraw() from anywhere:

async fn setup(
    &mut self,
    ctx: &GpuContext<'_>,
    env: &mut waterui::Environment,
) {
    let redraw = ctx.redraw_handle.clone();
    self.guard = Some(self.signal.watch(move |_| redraw.request_redraw()));
    // ...
}

This pattern is exactly how MeshGradient reacts to its color signal without the surface being torn down.

Offscreen rendering

GpuSurface ships with offscreen rendering for visual tests and CI snapshots. Always render to GPU here – never read back the swapchain texture in a runtime path.

use std::num::NonZeroU32;
use waterui::graphics::{GpuSurface, OffscreenRenderConfig, OffscreenSize, wgpu};

let size = OffscreenSize::try_from_pixels(1024, 768)?;
let config = OffscreenRenderConfig::new(size)
    .format(wgpu::TextureFormat::Rgba8UnormSrgb);

let output = GpuSurface::new(MyRenderer::default())
    .render_offscreen(config, &mut env)?;

assert_eq!(output.rgba8.len(), 1024 * 768 * 4);
output.save_png("snapshot.png")?;

For HDR snapshots, swap the format and the entry point:

let config = OffscreenRenderConfig::new(size)
    .format(wgpu::TextureFormat::Rgba16Float);

let output = GpuSurface::new(MyHdrRenderer::default())
    .render_offscreen_hdr(config, &mut env)?;

let max_luminance = output.max_rgb_linear();
let hdr_ratio = output.hdr_pixel_ratio();

output.save_png("hdr_snapshot.png")?;     // PQ-coded HDR PNG with cICP metadata
output.save_sdr_png("sdr_snapshot.png")?; // tone-mapped SDR fallback

OffscreenRenderConfig lets you simulate input for hover/gesture tests:

use waterui::layout::Point;
use waterui::graphics::{GestureState, PointerState};

let config = OffscreenRenderConfig::new(size)
    .format(wgpu::TextureFormat::Rgba8UnormSrgb)
    .msaa_samples(NonZeroU32::new(4).unwrap())
    .pointer(PointerState {
        position: Some(Point::new(512.0, 384.0)),
        hit: None,
    })
    .gesture(GestureState::new());

MSAA configuration

use std::num::NonZeroU32;

GpuSurface::new(MyRenderer::default())
    .msaa_max_samples(NonZeroU32::new(8).unwrap())

Globally: set WATERUI_GPU_MSAA=4 (accepts 1, 2, 4, 8, or 16). The backend clamps the request to what the adapter and format actually support.

HDR preference

WaterUI defaults to HDR (Rgba16Float) when the platform offers it. To opt out for a single surface:

GpuSurface::new(MyRenderer::default()).prefer_sdr_surface();

Globally: WATERUI_GPU_PREFER_HDR=0 forces SDR. In your renderer, gate blend state on ctx.is_hdr() so the same code compiles into either pipeline.

Reference

Next

For the most common GPU use case – a single fragment shader full-screen quad – ShaderSurface skips most of this boilerplate. Continue to Shaders.

Shaders

In this chapter, you will:

• Write WGSL fragment shaders and display them with ShaderSurface
• Use built-in uniforms for time, resolution, and aspect-ratio correction
• Load shaders at compile time with the shader! macro
• Build animated effects like plasma, noise, and pulsing shapes
• Know when to graduate from ShaderSurface to GpuView

ShaderSurface is the shortest path from “I have a WGSL fragment shader” to “it is on screen.” You supply the fragment, and WaterUI handles pipeline creation, the uniform buffer, and the render loop.

Quick start

The fastest way to get a shader on screen is the shader! macro:

use waterui::prelude::*;
use waterui::graphics::shader;

fn my_effect() -> impl View {
    shader!("shaders/plasma.wgsl")
}

shader! loads the WGSL source at compile time, registers it for pre-warming, and creates a ShaderSurface with the file path as a label so the GPU pipeline cache can deduplicate.

A WGSL fragment shader rendered through ShaderSurface. Example source.

Creating a ShaderSurface manually

shader! is sugar over two more explicit constructors. Reach for them when you need to wire something the macro does not cover (computed paths, generated shader source, and so on).

use waterui::graphics::ShaderSurface;

// from a static string -- no cache key
fn gradient_effect() -> impl View {
    ShaderSurface::new(include_str!("shaders/gradient.wgsl"))
}

// with a label for the pipeline cache
fn labeled_effect() -> impl View {
    ShaderSurface::with_label(
        "shaders/gradient.wgsl",
        include_str!("shaders/gradient.wgsl"),
    )
}

WaterUI keeps a long shader inline in a string literal off-limits in production code – always pull from a .wgsl file with include_str! (or include_fragment_shader!).

Built-in uniforms

Every ShaderSurface shader receives a standard uniform buffer automatically. You do not declare this struct yourself – it is prepended by the ShaderSurface prelude:

struct Uniforms {
    time: f32,           // Elapsed time in seconds since creation
    resolution: vec2<f32>, // Surface size in pixels (width, height)
    padding: f32,
}

@group(0) @binding(0)
var<uniform> uniforms: Uniforms;

A full-screen quad vertex shader is also provided automatically. Your shader only needs to define a fragment function named main:

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
    // uv: normalized coordinates (0,0) at bottom-left, (1,1) at top-right
    let t = uniforms.time;
    let res = uniforms.resolution;
    return vec4<f32>(uv.x, uv.y, sin(t) * 0.5 + 0.5, 1.0);
}

The prelude

The ShaderSurface prelude that is auto-prepended to your shader includes:

1. The Uniforms struct and binding declaration
2. A VertexOutput struct with position and uv fields
3. A vs_main vertex shader that draws a full-screen quad (6 vertices, 2 triangles)

Your fragment function should be named main (not fs_main) and accept @location(0) uv: vec2<f32>.

Writing WGSL shaders

Now for the fun part. The patterns below progress from a static gradient to time-warped procedural noise.

Basic color pattern

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
    // Horizontal gradient from red to blue
    let r = uv.x;
    let b = 1.0 - uv.x;
    return vec4<f32>(r, 0.0, b, 1.0);
}

Time-based animation

This is where shaders start to feel alive. The uniforms.time value ticks up continuously, letting you create pulsing, rotating, and morphing effects:

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
    let t = uniforms.time;

    // Pulsing circle
    let center = vec2<f32>(0.5, 0.5);
    let dist = distance(uv, center);
    let radius = 0.3 + 0.1 * sin(t * 2.0);
    let circle = smoothstep(radius + 0.01, radius - 0.01, dist);

    return vec4<f32>(circle, circle * 0.5, 1.0 - circle, 1.0);
}

Resolution-aware rendering

When your effect needs correct aspect ratio:

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
    let res = max(uniforms.resolution, vec2<f32>(1.0));
    let aspect = res.x / res.y;

    // Correct for aspect ratio
    var p = vec2<f32>((uv.x - 0.5) * aspect, uv.y - 0.5);

    let dist = length(p);
    let ring = smoothstep(0.01, 0.0, abs(dist - 0.3));

    return vec4<f32>(ring, ring, ring, 1.0);
}

Noise and procedural patterns

Here is a simple hash-based noise pattern – the building block for fire, clouds, terrain, and countless other effects:

fn hash21(p: vec2<f32>) -> f32 {
    return fract(sin(dot(p, vec2<f32>(127.1, 311.7))) * 43758.5453123);
}

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
    let t = uniforms.time;
    let scale = 10.0;
    let cell = floor(uv * scale);
    let n = hash21(cell + vec2<f32>(t * 0.1, 0.0));

    return vec4<f32>(n, n, n, 1.0);
}

Shader loading macros

WaterUI provides two compile-time macros, both returning a ShaderSource (alias PrewarmedShader):

include_shader!

Loads a complete WGSL shader with both vertex and fragment stages. Use this when you write your own vertex stage:

use waterui::graphics::{include_shader, prewarm::ShaderSource};

static MY_SHADER: ShaderSource = include_shader!("shaders/my_effect.wgsl");

include_fragment_shader!

Loads a fragment-only shader. The ShaderSurface prelude (uniforms + full-screen quad vertex shader) is prepended at runtime:

use waterui::graphics::{include_fragment_shader, prewarm::ShaderSource, ShaderSurface};

static MY_FRAGMENT: ShaderSource = include_fragment_shader!("shaders/my_fragment.wgsl");

ShaderSurface::with_label(MY_FRAGMENT.label, MY_FRAGMENT.source)

The shader! convenience macro

shader!("path.wgsl") expands to roughly:

{
    static SHADER: ShaderSource = include_fragment_shader!("path.wgsl");
    ShaderSurface::with_label(SHADER.label, SHADER.source)
}

Reach for it whenever you would otherwise inline a shader path twice.

How ShaderSurface works internally

Under the hood, ShaderSurface wraps a GpuSurface with an internal ShaderRenderer (a GpuView):

1. Setup: the full WGSL source (prelude + your fragment) is compiled into a wgpu::ShaderModule. A 24-byte uniform buffer, bind group, and render pipeline are created against the current surface format.
2. Render: each frame the uniform buffer is rewritten with the latest time and resolution, then a 6-vertex full-screen quad is drawn with your shader.
3. Continuous animation: ShaderRenderer calls frame.request_redraw() so time-based animations advance every frame.
4. Format safety: if the surface format changes between setup and render (HDR toggle, for instance) the pipeline is invalidated and rebuilt.

Accessing the inner GpuSurface

If you need the underlying GpuSurface (to apply a per-surface MSAA cap, or stack with other GPU views), unwrap it:

let surface = ShaderSurface::new(my_shader).into_inner();

Going beyond: custom uniforms

ShaderSurface provides only the standard uniforms (time, resolution). If you need extra uniforms, samplers, textures, or storage buffers, write your own GpuView and wrap it in a GpuSurface. See GPU rendering with GpuSurface. The shipped AnimatedMeshGradient is a good example – it carries a 4x4 palette array uniform, which is exactly the kind of thing ShaderSurface will not give you.

Performance tips

• Shader compilation: WGSL is compiled at setup time. Use shader! or with_label so the backend can cache compiled pipelines via the pre-warm system.
• Avoid branching: GPUs prefer uniform control flow. Replace branches with select(), step(), and smoothstep() where possible.
• Texture reads: ShaderSurface does not expose texture bindings. If you need to sample images, drop down to GpuView.
• Precision: WGSL is 32-bit float by default. For pixel-precise work, multiply UVs by uniforms.resolution.
• Pipeline cache: WaterUI threads a PipelineCache through setup; the shader! and with_label paths automatically take advantage of it.

Example: a plasma effect

Let’s put it all together with a classic plasma shader – the kind of swirling, colorful effect that has mesmerized programmers since the demoscene era:

// shaders/plasma.wgsl

const PI: f32 = 3.14159265359;

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
    let t = uniforms.time * 0.5;
    let res = max(uniforms.resolution, vec2<f32>(1.0));

    var p = uv * 10.0;

    var v = 0.0;
    v += sin(p.x + t);
    v += sin(p.y + t * 0.7);
    v += sin((p.x + p.y) * 0.5 + t * 1.3);
    v += sin(length(p - vec2<f32>(5.0)) + t);

    let r = sin(v * PI) * 0.5 + 0.5;
    let g = sin(v * PI + 2.094) * 0.5 + 0.5;
    let b = sin(v * PI + 4.189) * 0.5 + 0.5;

    return vec4<f32>(r, g, b, 1.0);
}

Use it in your app:

fn plasma_background() -> impl View {
    shader!("shaders/plasma.wgsl").size(400.0, 300.0)
}

Next

Shaders compose visual effects from scratch. To transform views you already have, continue to Filters and visual effects.

Filters and visual effects

In this chapter, you will:

• Apply blur, brightness, contrast, and other filters to any view
• Chain and compose filters with automatic GPU pass fusion
• Drive filter parameters with reactive signals
• Build custom effects with ViewEffect and GpuFilter
• Understand how the multi-pass pipeline optimizes your filter chains

Filters turn ordinary views into polished UI: blurred photo galleries, frosted-glass cards, dramatic black-and-white portraits. WaterUI’s GPU filter system captures the rendered output of a view, runs it through one or more shader passes, and displays the result with automatic pass fusion and animation support.

Quick start

FilterViewExt adds filter methods to every view. Pull it in with the prelude:

use waterui::prelude::*;
use waterui::graphics::FilterViewExt;

fn frosted_card() -> impl View {
    text("Hello, World!")
        .blur(10.0)
        .brightness(0.1)
        .contrast(1.2)
}

Three filters on a text view – and thanks to automatic fusion, the brightness and contrast adjustments execute as a single GPU pass.

FilterViewExt applied to a WaterUI view snapshot. Example source.

Architecture

The filter pipeline has four layers:

1. FilterViewExt – the convenience methods (.blur(), .brightness(), …) that you call from view code.
2. FilterAdapter<F> – bridges the pure-data Filter trait from filtrate-core to the GPU-aware GpuFilter trait, handling pass fusion and signal-driven animation.
3. GpuFilter – the low-level trait you implement for custom filters.
4. Native backend – captures the child view to a texture, runs the GPU filter in Rust, and displays the resulting texture.

view.blur(10.0)
    -> Filtered<V, FilterAdapter<Blur>>
        -> AppliedFilter metadata
            -> backend captures child to texture
            -> GpuFilter::render(input, output)
            -> backend displays output texture

Built-in filters

All built-in filters accept reactive values through the IntoSignalF32 trait, so you can pass static f32s, Binding<f64>, Computed<f32>, or any signal that yields a finite float. The adapter converts to Computed<f32> and watches it for animations.

Color filters

Color filters run per pixel and fuse into a single GPU pass when chained consecutively.

Spatial Filters

Spatial filters sample neighboring pixels and require a separate GPU pass (compute shader).

Basic usage

A single filter

use waterui::prelude::*;
use waterui::media::Photo;
use waterui::graphics::FilterViewExt;

fn blurred_photo(url: impl Into<waterui::Url>) -> impl View {
    Photo::new(url).blur(8.0)
}

Chaining filters

Use .then() to stack low-level Filter types from filtrate_core::filters:

fn stylized_photo(url: impl Into<waterui::Url>) -> impl View {
    Photo::new(url)
        .blur(5.0)
        .then(filtrate_core::filters::Brightness(0.15))
        .then(filtrate_core::filters::Contrast(1.3))
        .then(filtrate_core::filters::Saturation(0.8))
}

Or use the convenience methods directly – consecutive color filters are automatically fused:

fn warm_vintage(url: impl Into<waterui::Url>) -> impl View {
    Photo::new(url)
        .brightness(0.05)
        .then(filtrate_core::filters::Sepia(0.3))
        .then(filtrate_core::filters::Contrast(1.1))
        .then(filtrate_core::filters::Vignette(0.7, 0.5))
}

Filter fusion

The filter system automatically optimizes consecutive color-only filters into a single GPU pass. When you chain brightness -> contrast -> saturation, these three fragment shader snippets are fused into one render pass rather than three separate texture reads and writes.

Spatial filters (like blur and sharpen) always require their own pass. A chain like blur -> brightness -> contrast -> sharpen produces three passes:

1. Compute pass: blur
2. Fragment pass: brightness + contrast (fused)
3. Compute pass: sharpen

Tip: Ordering matters for performance. Group your color-only filters together to maximize fusion. Interleaving spatial and color filters creates unnecessary pass boundaries.

Reactive filters

Every filter convenience method accepts a reactive signal – in particular, a Binding<f64> from a slider works directly. Pass the binding by clone; never call .get() to feed a reactive sink.

use waterui::prelude::*;
use waterui::media::Photo;
use waterui::graphics::FilterViewExt;

fn interactive_blur(url: waterui::Url) -> impl View {
    let blur_radius = Binding::f64(0.0);

    vstack((
        Photo::new(url).blur(blur_radius.clone()),
        Slider::new(&blur_radius).range(0.0..=30.0),
    ))
}

Animated transitions

When the binding feeding a filter is wrapped with an animation, the FilterAdapter interpolates between the previous and current values automatically.

fn animated_filter_demo(url: waterui::Url) -> impl View {
    let blur = Binding::f64(0.0);

    vstack((
        Photo::new(url).blur(blur.clone()),
        button("Toggle blur")
            .action(|State(blur): State<Binding<f64>>| {
                let target = if blur.get() > 0.0 { 0.0 } else { 20.0 };
                with_animation(Animation::spring(180.0, 22.0), || blur.set(target));
            })
            .state(&blur),
    ))
}

The animation system supports three modes:

• Default: ease-in-out over 250 ms.
• Bezier: cubic bezier curves with configurable duration.
• Spring: physics-based spring with stiffness and damping.

HDR policy

Filter pipelines handle HDR-capable surfaces automatically. Override the default per filter chain:

fn hdr_aware_filter(url: waterui::Url) -> impl View {
    Photo::new(url)
        .blur(10.0)
        .prefer_hdr()   // use HDR intermediates when available (default)
    //  .require_hdr()  // fail if HDR is unavailable
    //  .force_ldr()    // always use LDR intermediates
}

When the input or output surface is HDR (Rgba16Float), the scratch textures between passes use Rgba16Float to preserve dynamic range. Otherwise, Rgba8Unorm is used.

ViewEffect: a lower-level effect API

For effects that go beyond simple filters – distortion, particle overlays, custom post-processing – use ViewEffect with the EffectRenderer trait:

use core::future::Future;
use waterui::graphics::{ViewEffect, EffectRenderer, EffectContext, EffectInput, EffectOutput, wgpu};

struct WaveDistortion {
    pipeline: Option<wgpu::RenderPipeline>,
    bind_group_layout: Option<wgpu::BindGroupLayout>,
    sampler: Option<wgpu::Sampler>,
}

impl EffectRenderer for WaveDistortion {
    fn setup(&mut self, ctx: &EffectContext) -> impl Future<Output = ()> {
        // create pipeline, bind group layout, sampler.
        // ctx.input_format and ctx.output_format may differ.
        async {}
    }

    fn render(&mut self, input: &EffectInput, output: &EffectOutput) {
        // read from input.texture/input.view, write to output.texture/output.view.
        // input and output may have different dimensions.
    }
}

Using ViewEffect

fn distorted_content() -> impl View {
    ViewEffect::new(
        text("Wavy text"),
        WaveDistortion::default(),
    )
}

Output size control

By default, the output texture matches the captured view’s size. Override it via OutputSize:

// double resolution for higher quality
ViewEffect::new(my_view(), effect)
    .output_size(OutputSize::Scale(2.0))

// fixed-size output
ViewEffect::new(my_view(), effect)
    .output_size(OutputSize::Fixed { width: 1920, height: 1080 })

OutputSize does not affect layout – it changes only the GPU processing resolution.

Custom GpuFilter

For maximum control, implement GpuFilter directly. Notice that the trait’s setup returns FilterSetupResult (i.e. Result<(), &'static str>) and render returns FilterRenderResult (Result<bool, &'static str>). The bool answers “is animation still running?”.

use core::future::Future;
use waterui::graphics::{
    FilterContext, FilterInput, FilterOutput, FilterRenderResult, FilterSetupResult, GpuFilter, wgpu,
};

struct CustomFilter {
    pipeline: Option<wgpu::RenderPipeline>,
    bind_group_layout: Option<wgpu::BindGroupLayout>,
    sampler: Option<wgpu::Sampler>,
    animating: bool,
}

impl GpuFilter for CustomFilter {
    fn setup(&mut self, ctx: &FilterContext) -> impl Future<Output = FilterSetupResult> {
        // build pipelines from ctx.device, ctx.queue, ctx.input_format, ctx.output_format,
        // and (when present) ctx.pipeline_cache.
        async { Ok(()) }
    }

    fn render(&mut self, input: &FilterInput, output: &FilterOutput) -> FilterRenderResult {
        // render input.view -> output.view. Return Ok(true) while interpolating.
        Ok(self.animating)
    }
}

Apply it using FilterViewExt::filter:

fn custom_filtered() -> impl View {
    text("Hello").filter(CustomFilter::default())
}

FilteredView::new is the lower-level wrapper – it takes an AnyView and the filter directly:

use waterui::AnyView;
use waterui::graphics::FilteredView;

fn custom_filtered() -> impl View {
    FilteredView::new(AnyView::new(text("Hello")), CustomFilter::default())
}

The filtrate-core Filter trait

WaterUI’s high-level filters sit on top of the filtrate-core crate, which provides a pure-data Filter trait with parameter arrays. FilterAdapter bridges that into GpuFilter:

filtrate_core::Filter
    -> FilterAdapter<F>  (implements GpuFilter)
        -> AppliedFilter (type-erased metadata on the view)
            -> backend renders

Filter provides:

• COLOR_ONLY – whether the filter only modifies pixel colors (no spatial sampling).
• Params – a ParamArray type for reactive parameters.
• params() – returns the current parameter values.

FilterGraph (internal) enables stage collection for pass planning, animation watcher installation for reactive parameters, and pass fusion.

Composing filters in practice

Photo editor effect stack

use filtrate_core::filters::{Brightness, Contrast, Saturation};

fn photo_adjustments(
    url: waterui::Url,
    blur: Binding<f64>,
    brightness: Binding<f64>,
    contrast: Binding<f64>,
    saturation: Binding<f64>,
) -> impl View {
    Photo::new(url)
        .blur(blur)
        .then(Brightness(brightness.computed()))
        .then(Contrast(contrast.computed()))
        .then(Saturation(saturation.computed()))
}

Frosted glass

use filtrate_core::filters::{Brightness, Saturation};

fn frosted_glass(content: impl View) -> impl View {
    content
        .blur(20.0)
        .then(Brightness(0.05))
        .then(Saturation(1.2))
}

Dramatic black-and-white

use filtrate_core::filters::{Contrast, Vignette};

fn dramatic_bw(url: waterui::Url) -> impl View {
    Photo::new(url)
        .grayscale(1.0)
        .then(Contrast(1.6))
        .then(Vignette(0.6, 0.4))
}

Performance notes

• Pass fusion: consecutive color-only filters fuse into a single fragment shader pass. Five colour filters cost roughly the same as one.
• Spatial filters: blur and sharpen use compute shaders with intermediate textures. Each spatial filter is a separate pass.
• Texture captures: the backend captures the child view to a texture before filtering. For GpuSurface children, the backend can sample the existing texture without an extra capture step.
• Animation: when filter parameters change with animation context, FilterAdapter keeps the surface dirty until the animation settles. Spring animations finish naturally; bezier animations run for a fixed duration.
• Scratch textures: multi-pass filters ping-pong between two scratch textures. They are allocated lazily and resized only when needed.

Next

Filters transform existing content. To create new visual content from scratch on the GPU, continue to Particle systems.

Particle Systems

In this chapter, you will:

• Build GPU-accelerated particle effects with the ParticleSystem view
• Configure emitters, motion, collisions, and blend modes from a single chain
• Use built-in shapes for fireworks, rain, snow, and ambient effects
• Apply collision and particle-particle interaction without writing shaders
• Render particle systems offscreen for visual testing

Picture confetti bursting across the screen when a user completes a purchase, or snowflakes drifting gently behind a winter-themed card. Particle effects bring delight and motion to an app – and with WaterUI’s ParticleSystem view, you describe the effect declaratively and the GPU does the rest.

Feature flag: Particles live behind the particle feature on waterui. Enable it in Cargo.toml (waterui = { version = "...", features = ["particle"] }) before importing waterui::particle.

Quick Start

use waterui::prelude::*;
use waterui::particle::ParticleSystem;
use core::f32::consts::PI;

fn rain() -> impl View {
    ParticleSystem::new(5_000)
        .emit_from_rect(1.5, 0.0)
        .at(0.5, -0.05)
        .rate(800.0)
        .life(0.8..1.3)
        .speed(1.8..2.2)
        .angle(PI * 0.49..PI * 0.51)
        .size(0.002..0.004)
        .color(
            Color::srgb(255, 255, 255).with_opacity(0.5),
            Color::transparent(),
        )
        .stretch_with_velocity()
        .gravity(0.0, 2.5)
}

ParticleSystem is itself a View, so it composes with vstack, zstack, frames, and any other layout primitive in the framework.

A WaterUI preview image illustrating a confetti particle emitter. Example source.

How It Works

ParticleSystem builds an internal ParticleConfig through a flat modifier chain. When the view is rendered, it materializes a GPU surface that:

1. Allocates a particle storage buffer sized to max_particles.
2. Runs a compute shader each frame to emit, advance, and recycle particles.
3. Renders all live particles in a single instanced draw call.
4. Returns needs_redraw() = true while at least one particle is alive.

Coordinates are normalized: [0.0, 0.0] is the top-left of the system’s frame and [1.0, 1.0] is the bottom-right. Sizes, gravity, and emitter offsets all use the same normalized space, which means an effect looks identical at any output resolution.

Configuring the Emitter

The emitter controls where particles spawn and how often.

use waterui::particle::ParticleSystem;

ParticleSystem::new(2_000)
    .emit_from_circle(0.05)
    .at(0.5, 0.5)
    .rate(400.0);

Particle Properties

Each particle is randomized within the ranges you provide.

use waterui::particle::{ParticleShape, ParticleSystem};
use core::f32::consts::TAU;

ParticleSystem::new(1_500)
    .emit_from_point()
    .at(0.5, 0.8)
    .rate(120.0)
    .life(0.6..1.4)
    .speed(0.4..0.9)
    .angle(0.0..TAU)
    .size(0.01..0.03)
    .shape(ParticleShape::Circle)
    .softness(0.6);

Environment Forces

Once particles spawn, world-space forces shape their motion.

ParticleSystem::new(3_000)
    .emit_from_rect(1.0, 0.05)
    .at(0.5, 0.0)
    .rate(900.0)
    .life(1.0..2.0)
    .speed(0.0..0.2)
    .gravity(0.0, 0.4)
    .wind(0.05, 0.0)
    .turbulence(0.6)
    .drag(0.98);

Blending and Compositing

Use additive() for fire, sparks, and glow effects where overlapping particles should brighten:

use waterui::particle::ParticleSystem;
use core::f32::consts::PI;

fn embers() -> impl View {
    ParticleSystem::new(2_000)
        .emit_from_point()
        .at(0.5, 0.95)
        .rate(300.0)
        .life(0.7..1.4)
        .speed(0.4..0.8)
        .angle(-PI * 0.6..-PI * 0.4)
        .size(0.005..0.012)
        .color(
            Color::srgb(255, 196, 96),
            Color::srgb(255, 64, 16).with_opacity(0.0),
        )
        .gravity(0.0, -0.4)
        .additive()
}

The default is BlendMode::Alpha (standard premultiplied alpha blending).