This page covers the part of the Rust API that most apps need. It describes the authoring layer, aster_blueprint::ui, which is what the tutorials and the examples use. The full reference is the rustdoc of the crates and the guide rust/crates/aster-blueprint/docs/UI.md in the SDK. Nothing here is a frozen 1.0 API: the crates are version 0.1.0 and signatures can still change.
Which layer do I use?
| You want | Use | Where |
|---|---|---|
| A window or a browser canvas from Rust | the authoring layer aster_blueprint::ui plus a host | rust/crates/aster-blueprint, native/ui-host, web/aster-web |
| An app in any language, described as JSON | the C ABI | native/runtime (C ABI reference) |
| Pixels only, no widgets: rectangles, text runs, vectors, images | the renderer core aster_ui | rust/crates/aster-ui |
Start with the authoring layer. The renderer core is what the authoring layer is built on; reach for it only when you are building your own toolkit on top of CPU pixels.
Five types that cover most of it
| Type | What it is |
|---|---|
El | One element of the screen: text, a column, a card, a chart. You build trees of them with plain functions and chain modifiers. |
Store | Your app state: named values (bool, integer, float, text, lists, records). The screen is a function of it. |
Action | What an element does when activated: set, toggle or increment a state key, push to a list, copy text, change theme. Several can be combined with Action::seq. |
Theme | A set of design tokens: colours (Role), type scale (Type), spacing, radii. The same tree re-renders under any theme. |
App | The running app. It owns the scene, layout and interaction state. A host (a window, a browser canvas, a test) feeds it input and takes its pixels. |
The one import that brings in all of them:
use aster_blueprint::ui::prelude::*;The loop
- Write
fn screen(s: &Store) -> El. It reads state and returns a tree. It is called again after every change, so it must be pure. - Create
App::new(&theme, store).size(w, h).screen(screen)?. (screentakesimpl Fn(&Store) -> El + 'static, so it cannot borrow locals: use a plainfn, ormoveowned data in.) - Give the app to a host:
app.run_window_with(Options { .. }.from_env())opens a native window,Renderedframes go to a canvas in a browser, and for tests you drive it headless.
A complete interactive example (state, an element with an action, headless driving, a window), checked in this documentation pass:
use aster_blueprint::ui::prelude::*;
use aster_native::{Options, RunWindow};
fn screen(s: &Store) -> El {
col([
text(format!("Count: {}", s.int("count"))).style(Type::Headline),
text("Add one").pad(3).fill(Role::Accent).color(Role::OnAccent)
.radius(Radius::Md).id("add").role("button")
.a11y_label("Add one").focusable()
.on_click(Action::inc("count", 1)),
]).gap(3).pad(6)
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let store = Store::new().with("count", 0i64);
let mut app = App::new(&Theme::paper_dark(), store).size(480, 260).screen(screen)?;
if std::env::args().any(|a| a == "--headless") {
app.click_id("add")?;
app.click_id("add")?;
app.settle()?;
println!("count = {}", app.store().int("count"));
app.write_png("docs_counter.png")?;
return Ok(());
}
app.run_window_with(Options { title: "Counter".into(), ..Options::default() }.from_env())
}Source: native/ui-host/examples/docs_counter.rs, on a review branch (not in the main source yet).
The 20% you use every day
Layout
| Function | Use |
|---|---|
col([..]), row([..]) | vertical and horizontal stacks. A col stretches children; a row centres them (change with .align(..)). |
grid(n, items), grid_tracks(..) | equal columns, or tracks such as Track::Px(240.) and Track::Fr(1.). |
wrap([..]) | flowing chips and tags; reports its full multi-line height. |
overlay([..]) | layers; pin one with .place(Align::End, Align::Start). |
scroll(child) | a scrolling region. |
spacer() | flexible space in a row. |
Modifiers: .gap(n), .pad(n), .w(px), .h(px), .grow(f), .align(..), .fill(Role::..), .radius(Radius::Md), .elevation(0..=4).
Numbers are theme steps. gap(3) and pad(6) index the theme's spacing scale (0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64 px), not raw pixels. Raw pixels have their own names: .w(px), .h(px), .pad_px(px), .gap_px(px), .font_px(px).
Text
text("Hi")is a one-line label that never wraps. Style it:.style(Type::Headline),.muted(),.bold(),.mono().paragraph(long)(ortext(s).wrap_fit()) wraps to the width it is given, using real font measurement. Clamp with.max_lines(3).- Fonts are the bundled ones. Without the
native-fontsfeature, rendering returnsUiError::NativeFontsRequired.
Controls and state
Controls take the Store and a key. The key is the state name they read and write.
| Function | State it manages |
|---|---|
text_field(s, "name", "placeholder") | text |
switch(s, "key", "Label"), checkbox(..) | bool |
slider(s, "key", min, max, step) | number |
select(s, "key", &[("id", "Label")], "placeholder") | the chosen id |
tabs(s, "key", &[("id", "Label")]) | the selected tab |
dialog(s, "key", title, body, actions) | open or closed |
list(..), list_keyed(..) | a virtualised list (only visible rows are built) |
Any element becomes interactive with .id(".."), .role("button"), .focusable(), .a11y_label("..") and .on_click(Action::..). Common actions: Action::set("saved", true), Action::toggle("open"), Action::inc("count", 1), Action::push(..), Action::set_theme("paper_light"), Action::seq([..]). .selected_if(|s| ..) and .disabled_if(|s| ..) tie an element's look to state.
Components
Ready-made pieces: card, panel, heading, stat, badge, chip, meter, table, kv_list, app_bar, nav, avatar, progress_bar, skeleton, and the charts (line_chart, bar_chart, area_chart, pie_chart, donut_chart, scatter_chart, sparkline_line). rust/crates/aster-blueprint/docs/COMPONENTS.md and CHARTS.md list them.
Themes
Theme::paper_dark(), paper_light(), mission_dark(), mission_light(), mission_dusk(), high_contrast_dark(), high_contrast_light(). Colours are Role::Accent, Role::Success, Role::TextMuted and so on, never hard-coded values, so a theme switch re-tints everything. app.set_theme(&theme) switches at runtime. Theme::with_reduced_motion(true) honours the reduced-motion preference.
Motion
.animate(Prop::Scale, Transition::ms(300, Ease::Linear)) animates a property when the state it depends on changes. In tests, app.advance(ms) moves the clock by hand, so every in-between frame is reproducible. See tutorial 4.
Responsive layouts
responsive, stack_at, sidebar_layout, drawer, and the Viewport environment model (Device, Orientation, Density) adapt one screen to a phone, a desktop and a TV. See docs/RESPONSIVE.md.
One-shot rendering and testing
You do not need an App to make a picture:
let root = col([text("Hello").style(Type::Headline), badge("LIVE", Role::Success)]).pad(5);
let shot = Screen::new(&Theme::mission_dark())?.size(480, 240).render(&root)?;
shot.tree.assert_visible("Hello"); // every text and id is registered in the semantic tree
shot.png("hello.png")?;For interaction tests drive the App headless: click_id, type_text, set, advance, settle, then read app.store(), app.tree() (with audit_a11y()), app.image() or app.write_png(path). This is the same loop the C ABI exposes as aster_app_click, aster_app_type, aster_app_tree and aster_app_shot.
Hosts
| Host | Entry point | Notes |
|---|---|---|
| Native window | aster_native::{Options, RunWindow}, app.run_window_with(options) | Linux (X11 and Wayland) and Windows. Options::from_env() reads the host's diagnostic environment variables. |
| Browser canvas | web/aster-web compiled to wasm32-unknown-unknown | a small C ABI (aw_init, aw_step, aw_frame_ptr, ...) exposes the RGBA framebuffer; JavaScript copies it to a canvas. Single-threaded. |
| Headless | App::write_png, Screen::render | no display needed: tests, docs images, video frames. |
| Any language | native/runtime C ABI | JSON in, JSON events out. |
Where the examples are
| Example | Shows |
|---|---|
Tutorials 1 to 5 (native/ui-host/examples/tutorial_*.rs, web/aster-web/examples/tutorial_web.rs) | hello window, layout and text, forms and accessibility, animation, wasm in the browser. They ship on the documentation branch that adds the Learn section; the site's Learn pages carry the full source. |
native/ui-host/examples/docs_counter.rs (this page; on a review branch) | the smallest interactive loop |
native/ui-host/examples/settings_app.rs | a settings screen with real controls |
rust/crates/aster-blueprint/examples/ (start_dashboard, start_form, start_list_detail, settings_app, team_chat, library_browser, ops_dashboard) | the three starters and whole apps built from the kit; the examples folder has the full table |
native/runtime/samples/*.json | the same ideas as JSON views for the C ABI and the aster tool |
Honest limits
- The layer is 0.x: names and signatures can change before 1.0.
- The browser build is single-threaded and the tutorial canvas is a framebuffer only. Input, text entry, IME and accessibility need a host bridge on the web; the SDK's interactive web demo (
web/aster-web/demo/) is the reference adapter. - Performance depends on the scene and the machine. This page makes no performance claims; measured numbers are published separately with their method.