Reference

Widget reference

Every widget, modifier and role in compose-rust's schema. The schema is closed: the renderer interprets exactly this list and nothing else. A widget kind it does not recognise produces a ProtocolError event rather than a crash.

Widgets

The names are Compose's. Each widget has a fixed tag in WidgetKind, and the Kotlin interpreter has one renderer function for each.

Modifiers

In Compose a Modifier applies to any composable, and the same is true here: every widget takes every modifier, including Text and Spacer. On the wire a modifier list is a sequence of fixed-size values, and the renderer rebuilds it into a Compose Modifier chain.

Unset is not zero. A modifier you did not write sends nothing at all. No padding and a padding of zero look the same on screen, but only one of them should cost a record.

The role vocabulary

Widgets emit roles, not literals. A role names a job ("the accent colour", "the heading rung", "a medium corner"), and the renderer resolves it against the active design system. That is what lets one tree come out as Material 3 on one machine and Liquid Glass on another. Design systems explains how the system is chosen. All of these types exist in 0.0.1.

Paint and Color

Anywhere a colour is taken, the type is Paint: a role, a literal ARGB value, or a registered brush such as a gradient.

use compose_rust::{Color, ColorRole, Paint};

let accent = Paint::Role(ColorRole::Primary);          // resolved by the design system
let brand = Paint::Literal(Color::rgb(0x1b6ef3));     // opaque, 0xRRGGBB
let veil = Paint::Literal(Color::argb(0x80ff0000));    // 0xAARRGGBB

A literal is the escape hatch. It survives a design-system change unchanged. That is sometimes what you want, such as a brand colour, and usually not, such as a colour that reads on a light page and disappears on a dark one. For brand colours, a Palette is better; see Application colours.

ColorRole: 45 roles

Every role that names ink is paired with the surface it reads on. OnPrimary is the ink for something filled with Primary, and so on.

Reach for SurfaceContainer when a panel has to be visible against the page. Material 3 gives Surface and Background the same value on purpose and shows depth through tonal containers instead. A panel filled with Surface on a page of Background is drawn correctly and cannot be seen. Every supported design system makes SurfaceContainer visible against the page.

TypeRole: nine rungs

ShapeRole, SpaceRole and MotionRole

ShapeRole is None, ExtraSmall, Small, Medium, Large and Full. The radius is the design system's answer, and Full means a capsule.

SpaceRole is None, Xs, Sm, Md, Lg, Xl and Xxl. Density differs per design system, which is the reason to spell a gap as a role rather than a number of dp.

MotionRole is Instant, Quick, Standard, Slow and Emphasized. Each design system gives them its own duration and curve.

IconRole

An icon is addressed by what it is for, never by a platform icon name: Back, Forward, Close, Search, Add, Check, Settings, More, Home, List, Inbox, Menu and History. The role is what lets one declaration come out as an SF Symbol under Apple's systems and a Material Symbol under Material 3.

Layout and text enums

Window size

The UI is described in Rust and measured by the renderer, so the only way Rust learns the window's width is for the renderer to report it. window_size() returns a WindowSize with width_dp, height_dp and class, plus is_compact(), is_medium() and is_expanded(). It exists in 0.0.1.

Only a class change is reported. The renderer sends one event when the class changes and nothing in between. Dragging a window from 700 dp to 800 dp wakes nothing in Rust, because a size that changed every layout pass would run Rust code every layout pass. Before the first measurement the value is Compact at 0 by 0, because a one-column layout works at any width.

Navigation, Sheet and Scaffold already adapt without being asked, by moving nodes the renderer already has. Use the window size for the decisions the widgets cannot make for you, such as two columns instead of one.

Where each widget keeps its state

Application state is yours, and UI-local state is the renderer's. These are the places that surprise people, because a widget looks controlled and is not, or the other way round.

Extensions

An extension is a compile-time pair of source files, one Rust and one Kotlin, built into both sides. It is not a runtime plugin: a deployed renderer cannot load a new widget, because the schema hash would no longer match. The crate ships one worked example, LinearProgressIndicator, with a single progress: f32 property.

Adding your own means registering the widget and property tags in compose-rust/src/extensions.rs and rendering the new kind in a paired Kotlin renderer. Extension widget tags start at 100, so they never collide with a core widget added later.