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())
}