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

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 (GTK4) from one Rust codebase. An experimental self-drawn backend (Hydrolysis, powered by Vello) and a terminal UI backend are also under development.
• Type-safe: Leverage Rust’s type system, ownership, and lifetimes to eliminate whole categories of runtime errors at compile time.
• Reactive: Powered by the nami crate, every Binding<T>, Computed<T>, and Signal automatically propagates 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, reactive state with nami, 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.

Each chapter contains runnable code examples. Clone the repository and use water create --playground to set up sandbox projects as you follow along.

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")
                .state(&counter)
                .action(|State(c): State<Binding<i32>>| c.set(c.get() - 1)),
            button("Increment")
                .state(&counter)
                .action(|State(c): State<Binding<i32>>| c.set(c.get() + 1)),
        )),
    ))
}

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

waterui_ffi::export!();

This single file compiles and runs on iOS, Android, macOS, and Linux without any platform-specific code. Notice how you declare what you want – a text display and two buttons – and WaterUI handles the rest. No platform #[cfg] blocks, no conditional compilation, no separate codebases.

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.