Freya

Freya Best Practices

Freya is a cross-platform, native, declarative GUI library for Rust.

General rules:

• Do not write unnecessary comments in code.
• Do not use em dashes.
• Be simple, elegant, and concise.

Start by asking the user what they would like to do:

• Lint and improve existing code
• Refactor existing code
• Add a new feature

Components

Struct Components (for stateful UI)

#[derive(PartialEq)]
struct Counter {
    initial: i32,
}

impl Component for Counter {
    fn render(&self) -> impl IntoElement {
        let mut count = use_state(|| self.initial);
        label()
            .on_press(move |_| *count.write() += 1)
            .text(format!("Count: {}", count.read()))
    }
}

• #[derive(PartialEq)] is required - Freya uses it to skip re-rendering unchanged subtrees.
• Implement KeyExt and ChildrenExt when the component can be keyed or accept children.

ComponentOwned (when render needs to own self)

Component::render takes &self, so moving fields into closures forces let foo = self.foo.clone(); boilerplate. ComponentOwned::render takes self by value (the framework clones it for you), letting you move self directly. Requires #[derive(Clone)]. Reach for it only when you'd otherwise clone self (or several of its fields) inside render.

#[derive(PartialEq, Clone)]
struct Item { state: State<Vec<i32>>, i: usize }

impl ComponentOwned for Item {
    fn render(mut self) -> impl IntoElement {
        Button::new()
            .on_press(move |_| { self.state.write().remove(self.i); })
            .child("Remove")
    }
}

Function Components (app root only)

The app root is a plain function. Hooks like use_init_theme, use_init_radio_station, use_provide_context belong here.

fn app() -> impl IntoElement {
    rect().child("Hello, World!")
}

To pass data from main into the root, use the App trait:

struct MyApp { number: u8 }

impl App for MyApp {
    fn render(&self) -> impl IntoElement {
        label().text(self.number.to_string())
    }
}

Utility Functions (stateless, no hooks)

fn colored_label(color: Color, text: &str) -> impl IntoElement {
    label().color(color).text(text.to_string())
}

Reusable UI that uses hooks or props MUST be a Component (struct + impl Component). Plain functions are only for the app root and stateless helpers. Functions with hooks won't benefit from diffing/memoization and can't be keyed or accept reactive props cleanly.

Elements

Built-in element constructors:

• rect() - layout primitive (direction, alignment, sizing, background, borders, corners, shadows, padding, scroll).
• label() - single-line text.
• paragraph() - multi-line / rich text via .text_span(...) children; also the target for use_editable.
• image(handle) - raster image; handle from static_bytes(...), dynamic_bytes(...), or asset loaders.

&str / String implement Into<Label>, so prefer rect().child("Hi") over rect().child(label().text("Hi")).

Element Builder Pattern

Elements use a fluent builder API. Never store an element in a variable to modify it later - chain all methods directly or use .maybe / .map.

// Good
rect()
    .background((255, 0, 0))
    .width(Size::fill())
    .height(Size::px(100.))
    .center()       // centers children both axes
    .expanded()     // fills available space in parent's main axis
    .horizontal()   // sets layout direction to horizontal
    .maybe(is_active, |el| el.child("Active"))
    .map(some_value, |el, v| el.child(v.to_string()))

// Bad - storing to modify later
let mut element = rect();

Common layout shorthands: .center() centers children on both axes; .expanded() makes the element fill all remaining space along the parent's main axis (equivalent to flex: 1 in CSS); .horizontal() and .vertical() set the layout direction (prefer them over .direction(Direction::Horizontal/Vertical)).

Conditional and Dynamic Rendering

rect()
    .maybe(show_badge, |el| el.child("New"))          // bool condition
    .map(large_size, |el, size| el.height(size))      // Option<T>, passes value
    .maybe_child(optional_element)                    // Option<impl IntoElement>

• .maybe(bool, |el| el) - applies the callback when the condition is true
• .map(Option<T>, |el, val| el) - applies the callback when the Option is Some, passing the inner value
• .maybe_child(Option<impl IntoElement>) - appends a child only when Some

Name the element argument el in .maybe / .map callbacks (not r, rect, e, etc.).

Prefer one outer .maybe / .map over several consecutive .maybe_child calls gated on the same condition - it keeps the gating in one place and avoids re-evaluating the same predicate.

// Good, single .maybe wraps all conditional children
rect()
    .maybe(show, |el| {
        el.child(Title::new("Hi"))
            .child(Content::new().child("Hello"))
            .child(Footer::new())
    })

// Bad, same predicate repeated per child
rect()
    .maybe_child(show.then(|| Title::new("Hi")))
    .maybe_child(show.then(|| Content::new().child("Hello")))
    .maybe_child(show.then(|| Footer::new()))

Events

Attach handlers via builder methods on any element. Handlers receive Event<T>; use move closures to capture state.

rect()
    .on_press(move |_| { /* left click, tap, or Enter/Space when focused */ })
    .on_key_down(move |e: Event<KeyboardEventData>| { /* only while focused */ })
    .on_wheel(move |e| { /* scroll delta */ })
    .on_pointer_enter(move |_| { /* hover begin (mouse or touch) */ })

Catalog (all prefixed on_):

• Press: press (left/tap/Enter/Space), all_press (any mouse button), secondary_down (right-click).
• Mouse: mouse_up, mouse_down, mouse_move.
• Pointer (mouse + touch unified): pointer_press, pointer_down, pointer_move, pointer_enter, pointer_leave, pointer_over, pointer_out.
• Keyboard (require focus): key_down, key_up.
• Wheel: wheel.
• Touch: touch_start, touch_end, touch_move, touch_cancel.
• File drop: file_drop.
• Layout: sized (measured size changed).
• Global (no hit-test; use sparingly): global_pointer_up, global_pointer_down, global_pointer_move, global_key_down, global_key_up, global_file_hover, global_file_hover_cancelled.
• Capture (run before regular handlers): capture_global_pointer_up, capture_global_pointer_move.

Prefer on_press over raw mouse/pointer events for interactive elements: it covers click, tap, and keyboard activation, so accessibility comes free. Use on_mouse_* / on_pointer_* only when you need pointer-specific behavior (drag handles, canvas tools).

Event<T> has two cancellation methods, plus .map(...) / .try_map(...) to transform inner data:

• .stop_propagation(): don't bubble this event to ancestor handlers. No effect on events that don't bubble (move/enter/leave, capture, global).
• .prevent_default(): don't fire the follow-up events this one triggers (e.g. in on_mouse_up, suppresses the on_pointer_press and on_global_pointer_up that would follow).

Callback props on custom components

Use EventHandler<T> for callback props; closures convert via .into().

#[derive(PartialEq)]
struct Confirm { on_accept: EventHandler<()> }

impl Component for Confirm {
    fn render(&self) -> impl IntoElement {
        let on_accept = self.on_accept;
        Button::new().on_press(move |_| on_accept.call(())).child("OK")
    }
}

Confirm { on_accept: (move |()| println!("yes")).into() }

EventHandler<T> is Copy; capture directly in move closures.

Focus and Accessibility

Focusable elements need a stable AccessibilityId from use_a11y() (one per focusable node), attached via .a11y_id(...) and .a11y_focusable(true). Track focus state with use_focus(id).

#[derive(PartialEq)]
struct FocusableBox;

impl Component for FocusableBox {
    fn render(&self) -> impl IntoElement {
        let a11y_id = use_a11y();
        let focus = use_focus(a11y_id);

        rect()
            .a11y_id(a11y_id)
            .a11y_focusable(true)
            .a11y_role(AccessibilityRole::Button)
            .on_press(move |_| println!("activated"))
            .maybe(focus() == Focus::Keyboard, |el| {
                el.border(Border::new().fill(Color::BLUE).width(2.))
            })
            .child("Click or Tab to me")
    }
}

Focus variants:

• Focus::Not - not focused.
• Focus::Pointer - focused by mouse/touch (no focus ring needed).
• Focus::Keyboard - focused via Tab (render a focus ring).
• focus.is_focused() matches Pointer or Keyboard.

on_press already fires on Enter/Space when focused, so keyboard activation is free. For raw key handling, KeyboardEventExt::is_press_event(&event) detects the OS activation gesture (Enter/Space; Ctrl+Alt+Space on macOS with VoiceOver).

Other a11y builders: .a11y_role(...), .a11y_alt("description"), .a11y_auto_focus(true), .a11y_member_of(other_id), .a11y_builder(|node| { /* raw accesskit::Node */ }).

Read the focused id globally via Platform::get().focused_accessibility_id.

Hooks

Hooks are prefixed with use_ (e.g. use_state, use_animation). Follow these rules:

1. Only call hooks at the top level of render - never inside conditionals, loops, or closures.
2. Hooks must be called in the same order on every render.
3. Never call hooks inside event handlers - call them at the top of render and capture the values in move closures instead.
4. Never call hooks inside loops - the number of hook calls must be constant across renders.
5. Never call hooks outside of components - hooks only work inside a render method or a function component.
6. Never call hooks inside async tasks - spawn callbacks are async and cannot call hooks; capture state before spawning. Some hooks have non-hook counterparts that are safe to call in async contexts (e.g. use_consume → consume_context()).

Capture hook values in move closures for event handlers:

let mut state = use_state(|| false);
let on_click = move |_| state.set(true); // capture, not call inside handler
rect().on_press(on_click)

State Management

Local State

let mut count = use_state(|| 0);
*count.write() += 1;          // write
let n = *count.read();        // read
count.set(5);                 // convenience setter
count.set_if_modified(5);     // only writes (and notifies) if the new value differs

use_state returns a Copy type (State<T>). No .clone() needed when passing it around.

Avoid drop() on guards from .read()/.write(); guards release on scope exit. Prefer a smaller scope ({ let v = state.read(); ... }) or copying the value out (let n = *count.read();). Only use explicit drop(guard) when you must release a borrow before re-borrowing in the same scope.

Prefer set_if_modified over set when the new value may equal the current (syncing external/derived values, handlers that may fire unchanged). It skips the write and avoids waking subscribers. Requires T: PartialEq. set_if_modified_and_then(value, || { ... }) runs a callback only on actual change.

Pass local state to child components:

#[derive(PartialEq)]
struct Child(State<i32>);

Global State - Freya Radio

Use Freya Radio for large or deeply nested app state where you need surgical, fine-grained updates - only the components subscribed to a specific channel re-render when that channel changes. This makes it well-suited for complex UIs (e.g. a tab system where each tab has independent state, or a big data model where different parts of the UI subscribe to different slices).

Define your state and a channel enum that maps to the parts of the state that can change independently:

#[derive(Default, Clone)]
struct AppState {
    count: i32,
    name: String,
}

#[derive(PartialEq, Eq, Clone, Debug, Copy, Hash)]
enum AppChannel {
    Count,
    Name,
}

impl RadioChannel<AppState> for AppChannel {}

Initialize once in the root component, then subscribe from any descendant:

// Root
use_init_radio_station::<AppState, AppChannel>(AppState::default);

// Any component - only re-renders when AppChannel::Count changes
let mut radio = use_radio(AppChannel::Count);
radio.read().count;
radio.write().count += 1;

For channels where a write to one should also notify subscribers of another, override derive_channel:

impl RadioChannel<AppState> for AppChannel {
    fn derive_channel(self, _state: &AppState) -> Vec<Self> {
        match self {
            // Writing to Count also notifies Name subscribers
            AppChannel::Count => vec![self, AppChannel::Name],
            AppChannel::Name => vec![self],
        }
    }
}

For complex state transitions, implement the reducer pattern with DataReducer:

impl DataReducer for AppState {
    type Channel = AppChannel;
    type Action = AppAction;

    fn reduce(&mut self, action: AppAction) -> ChannelSelection<AppChannel> {
        match action {
            AppAction::Increment => { self.count += 1; }
            AppAction::SetName(n) => { self.name = n; }
        }
        ChannelSelection::Current
    }
}

// Then in a component:
radio.apply(AppAction::Increment);

Readable / Writable (type-erased abstractions)

Readable<T> and Writable<T> are type-erased wrappers over any reactive value of type T. Use them as component props so the component works regardless of where the state lives: local State<T>, a Memo<T>, a radio slice, or a plain owned value. Both are PartialEq (always equal) and Clone, usable directly as component fields.

#[derive(PartialEq)]
struct NameInput { name: Writable<String> }

impl Component for NameInput {
    fn render(&self) -> impl IntoElement {
        Input::new(self.name.clone()) // Input is two-way bound to the Writable
    }
}

// Caller side: any source converts via `into_writable()` / `into_readable()`
NameInput { name: local_name.into_writable() }            // from State<String>
NameInput { name: name_slice.into_writable() }            // from a RadioSliceMut

Conversions:

• State<T> → Writable<T> / Readable<T> via IntoWritable / IntoReadable.
• Memo<T> → Readable<T> via IntoReadable.
• RadioSlice → Readable<T>; RadioSliceMut → Readable<T> or Writable<T>.
• Writable<T> → Readable<T> via From (downgrade write access).
• Plain owned T → Readable<T> via From (non-reactive; tests, defaults).

API surface:

• Readable<T>: read() (subscribes), peek() (no subscription).
• Writable<T>: read(), peek(), write(), plus WritableUtils helpers (set, set_if_modified, with_mut, ...). Subscriptions and notifications route to the original source.

Prefer Readable<T> for read-only consumers; use Writable<T> only when the component must mutate.

Context API

Use context to make a value available to any descendant component without threading it through every prop. Prefer this over static variables, thread_local!, or global singletons - context is scoped to the component tree and plays well with Freya's reactivity.

// Provider: stores the value and makes it available to all descendants
fn app() -> impl IntoElement {
    use_provide_context(|| AppConfig { theme: Theme::Dark });
    rect().child(DeepChild {})
}

// Consumer: retrieve by type, walks up the tree until found
#[derive(PartialEq)]
struct DeepChild;
impl Component for DeepChild {
    fn render(&self) -> impl IntoElement {
        let config = use_consume::<AppConfig>();
        format!("Theme: {:?}", config.theme)
    }
}

Use use_try_consume::<T>() when the context may not be present. If context is not found, use_consume panics.

Context values are identified by type, so each distinct type gets its own slot. Providing the same type again in a deeper component shadows the ancestor's value for that subtree.

Context is the right tool for dependency injection (e.g. passing a DB client, config, or theme down the tree). For reactive shared state use Freya Radio; for passing state between a parent and immediate children, plain props or State<T> are simpler.

Choosing state type

• use_state - component-local state
• Context API - dependency injection and non-reactive shared values across the tree; prefer over statics
• Freya Radio - large/nested state, surgical per-channel updates, multi-window
• Readable/Writable - reusable components that don't care about backing storage

Derived State and Side Effects

For simple derived values, compute them directly in render - no hook needed:

let doubled = *count.read() * 2;

For expensive computations that should only re-run when their dependencies change, use use_memo. It subscribes to any State read inside the callback and caches the result:

let expensive = use_memo(move || {
    let n = *count.read(); // subscribed - reruns when count changes
    compute_something(n)
});
let value = expensive.read();

For side effects that should re-run when state changes (e.g. logging, triggering external systems), use use_side_effect. Do not use it to sync one state into another - derive values directly or use use_memo instead:

use_side_effect(move || {
    let value = *count.read(); // subscribed
    println!("count changed: {value}");
});

Async

Spawning tasks

Use Freya's spawn() (not tokio::spawn) for async work that updates the UI. Tasks spawned with spawn() are tied to Freya's reactivity system and can safely write to component state:

let mut data = use_state(|| None);

use_hook(move || {
    spawn(async move {
        let result = fetch_something().await;
        data.set(Some(result));
    });
});

use_hook runs once on mount, making it the right place for one-shot side effects. spawn returns a TaskHandle you can cancel if needed.

Async functions in components

Components and hooks are synchronous - you cannot await inside render. Prefer use_future for typical async work (see below). Only reach for use_hook + spawn when you need fine-grained control over the task lifecycle:

// Only when you need manual control
use_hook(move || {
    spawn(async move {
        let s = some_async_fn().await;
        result.set(s);
    });
});

use_future

use_future wraps this pattern: it starts an async task on mount and exposes its state as FutureState<D> (Pending, Loading, Fulfilled(D)):

let task = use_future(|| async {
    fetch_user(42).await
});

match &*task.state() {
    FutureState::Pending | FutureState::Loading => "Loading...",
    FutureState::Fulfilled(user) => user.name.as_str(),
}

Call task.start() to restart and task.cancel() to stop it.

freya-query (cached async data)

For data that should be cached, deduplicated, and automatically refetched, use freya-query (features = ["query"]):

// Define the query
#[derive(Clone, PartialEq, Hash, Eq)]
struct FetchUser;

impl QueryCapability for FetchUser {
    type Ok = String;
    type Err = String;
    type Keys = u32;

    async fn run(&self, user_id: &u32) -> Result<String, String> {
        Ok(format!("User {user_id}"))
    }
}

// Use it in a component
impl Component for UserProfile {
    fn render(&self) -> impl IntoElement {
        let query = use_query(Query::new(self.0, FetchUser));

        match &*query.read().state() {
            QueryStateData::Pending => "Loading...",
            QueryStateData::Settled { res, .. } => res.as_deref().unwrap_or("Error"),
            QueryStateData::Loading { .. } => "Refreshing...",
        }
    }
}

Multiple components using the same (capability, keys) pair share one cache entry. Invalidate with query.invalidate() or QueriesStorage::<FetchUser>::invalidate_all().await.

For write operations, use use_mutation + MutationCapability. The on_settled callback is the right place to invalidate related queries after a mutation.

Prefer freya-query over manual use_future + state when you need caching, background refetch, or deduplication.