API overview

Most apps need one import:

use crownui::prelude::*;

This reference documents that import, the entry points at the crate root and the extension points in crownui::ext. Each page shows a usage example and the exact signature, then lists every parameter, builder method and return value.

Where things live#

The prelude groups into a few kinds of items:

• Views and structure: component, show, keyed, for_each, error_boundary, bind, View, ViewSeq, AnyView, Element, IntoProp.
• Widgets: vstack, hstack, zstack, spacer, divider, text, button, toggle, text_field, scroll_view, lazy_list, lazy_vstack, lazy_grid, canvas, image, cover_image, svg, icon, popover, with LazyListOptions, ScrollOptions and ScrollHandle.
• Modifier traits and their values: Styled, Listeners, Semantic, Event, PointerEvents, ColorScheme.
• State: Cx, Runtime, Signal, Memo, Store.
• Values: Color, rgb, rgba, WHITE, BLACK, TRANSPARENT, Point, Size, Rect, Vector, CornerRadii, CornerShape, Shadow, Spring, Curve, GridTrack, Role.
• Windows: AppConfig, FramePacing, LayerOptions, Layer, Anchor, LayerExtent, LayerMargin, KeyboardInteractivity, Material, MaterialBlur, MaterialShadow, Capabilities, CursorIcon, AppWindows.
• Clipboard and drag and drop: ClipboardData, DragSource, DragIcon, DragOutcome, DndAction, DndActions.

Conventions#

Builders are lowercase nouns#

A view builder is a function named like a SwiftUI view: vstack, text, button. It returns an Element you chain modifiers on.

vstack((text("Title"), button("OK")))

Modifiers are Tailwind names#

Style methods use Tailwind class names with literal values in logical pixels. .p(16.0) is Tailwind's p-4. Variants take a closure: .hover(|style| ..), .dark(|style| ..).

text("Hello").p(16.0).rounded(8.0).hover(|style| style.opacity(0.8))

Listeners are DOM names#

Handlers are named after DOM events (on_click, on_key_down, on_input) and get (&mut Cx, &mut Event<T>). Events bubble. A handler calls event.stop_propagation() to stop them and event.prevent_default() to cancel the default action.

button("Save").on_click(|cx, event| {
    event.stop_propagation();
    save(cx);
})

Any property takes a value or a reactive source#

A parameter typed impl IntoProp<T> takes a literal, a Signal<T>, a Memo<T> or a bind(move |rt| ..). With a literal the property is fixed. With the others it updates when its source changes.

let width = cx.signal(320.0);
vstack(()).w(320.0);                                  // fixed
vstack(()).w(width);                                  // follows the signal
vstack(()).w(bind(move |rt| width.get(rt) * 2.0));    // follows an expression

State goes through &mut Cx#

Cx derefs to the reactive runtime. Signal reads and writes both take it mutably, so read into a local first, then write.

let initial = todo.with(cx, |todo| todo.done); // read
let done = cx.signal(initial);                  // then write

No macros#

Every API is a real function, method or type. There is no macro in the authoring API.

Errors#

The entry points return Result<(), RunError>.

pub enum RunError {
    Graphics(GraphicsError),
    Platform(String),
    Thread(std::io::Error),
}

Problems that do not stop the app are logged through tracing with a stable code such as CUI0402. The errors page lists every code with its fix.

Cargo features#

Default features are wayland, impeller, tokio, mcp and accessibility. static and audio are off. run and run_windows exist only with wayland and impeller on, and cx.spawn needs tokio.

Stability#

CrownUI is pre-1.0. Under Cargo's semver rules for 0.x crates, a minor release such as 0.2 can change any API on these pages. The repository keeps a snapshot of every crate's public API in api/*.txt, and cargo xtask api --check fails when the API changes without the snapshot being updated, so every API change is visible in review. Check the changelog before you upgrade.

Reference#

Running an app#

State#

Structure#

Views#

Modifiers#

Kit, testing and extension#