iocraft

You can define your own reusable UI components using the #[component] macro. A component function takes hooks: Hooks as an argument and returns an object that implements Into<AnyElement<'static>>.

Inside a component, you can use hooks like use_state for managing local state and use_future for running asynchronous tasks (e.g., timers or network requests). To run an interactive component in a fullscreen terminal application, use element!(ComponentName).render_loop() inside an async executor like smol.

use iocraft::prelude::*;
use std::time::Duration;

#[component]
fn Counter(mut hooks: Hooks) -> impl Into<AnyElement<'static>> {
    let mut count = hooks.use_state(|| 0);

    hooks.use_future(async move {
        loop {
            smol::Timer::after(Duration::from_millis(100)).await;
            count += 1;
        }
    });

    element! {
        Text(color: Color::Blue, content: format!("counter: {}", count))
    }
}

fn main() {
    smol::block_on(element!(Counter).render_loop()).unwrap();
}

The iocraft-examples package contains several demonstrations of core features and patterns. Key examples include:

• Borders: Showcases various border styles (borders.rs).
• Calculator: Demonstrates clickable buttons and light/dark mode themes (calculator.rs).
• Context: Demonstrates custom context management using ContextProvider and use_context (context.rs).
• Dynamic Components: Renders components that spawn futures to update state (e.g., a counter incrementing every 100ms) (counter.rs).
• Forms: Uses mutable reference props to surface user input to a caller upon submission (form.rs).
• Fullscreen: Renders to an alternate terminal buffer to prevent user scrolling (fullscreen.rs).
• Layout & Positioning: Demonstrates absolute positioning for overlapping elements (overlap.rs) and scrollable text using ScrollView (scrolling.rs).
• Input & Output: Demonstrates keyboard input handling (use_input.rs) and continuous text logging above rendered components (use_output.rs).
• Asynchronous Data: Demonstrates loading data from remote APIs in response to user input (weather.rs).

The ContextProvider component allows you to provide a piece of data (a Context) to all its descendant components. Descendant components can then access this data using the use_context::<T>() hook.

ContextProvider is a transparent component, meaning it does not affect the layout of its children. You can provide context using different ownership models via Context::owned, Context::from_ref, or Context::from_mut.

# use iocraft::prelude::*;
struct NumberOfTheDay(i32);

#[component]
fn MyContextConsumer(hooks: Hooks) -> impl Into<AnyElement<'static>> {
    // Access the provided context using the type as the key
    let number = hooks.use_context::<NumberOfTheDay>();

    element! {
        View(border_style: BorderStyle::Round, border_color: Color::Cyan) {
            Text(content: "The number of the day is... ")
            Text(color: Color::Green, weight: Weight::Bold, content: number.0.to_string())
            Text(content: "!")
        }
    }
}

fn main() {
    element! {
        // Provide the context to the tree
        ContextProvider(value: Context::owned(NumberOfTheDay(42))) {
            MyContextConsumer
        }
    }
    .print();
}

In iocraft, Handler (immutable/clonable) and HandlerMut (mutable/non-clonable) are designed to be interoperable.

• Upgrading: You can convert a Handler<T> into a HandlerMut<'static, T> using From. This is useful when a component expects a mutable handler but you only have an immutable one.
• Usage Pattern: For component properties, prefer HandlerMut. If you need to share a single logic block across multiple UI elements (like two different buttons triggering the same action with different arguments), use Handler and the .bind() method.

// Example: Sharing a handler across multiple buttons using .bind()
// inside an element! macro context

let counter_handler: Handler<_> = hooks.use_async_handler(move |n| async move {
    counter += n;
});

element! {
    Fragment {
        Button(handler: counter_handler.bind(1), has_focus: true) {
            Text(content: "[ +1 ]")
        }
        Button(handler: counter_handler.bind(-1)) {
            Text(content: "[ -1 ]")
        }
    }
}

The use_ref hook allows you to store a value that can be modified but does not trigger a component re-render when changed. This is useful for imperative control, such as managing component handles or storing values that don't affect the UI directly.

Ref<T> is a copyable wrapper for the stored value. It is owned by the component and will panic if you attempt to access it after the component has been dropped (use try_read or try_write to avoid panics).

Warning on Deadlocks: Using .read() or .write() can cause deadlocks if you hold multiple references to the same Ref. Writes to a Ref will be blocked as long as any reference returned by .read() exists.

# use iocraft::prelude::*;
# #[component]
# fn FormField(mut hooks: Hooks) -> impl Into<AnyElement<'static>> {
# let mut value = hooks.use_state(|| "".to_string());
# let initial_cursor_position = 0;
let mut handle = hooks.use_ref_default::<TextInputHandle>();

hooks.use_effect(
    move || handle.write().set_cursor_offset(initial_cursor_position),
    (),
);

element! {
    View(
        background_color: Color::DarkGrey,
        width: 30,
    ) {
        TextInput(
            has_focus: true,
            value: value.to_string(),
            on_change: move |new_value| value.set(new_value),
            handle,
        )
    }
}
# }