Crate reratui

Expand description

§Reratui - A Modern, Reactive TUI Framework for Rust

Reratui brings React-inspired component architecture and hooks to terminal user interfaces, enabling developers to build complex, interactive TUI applications with clean, maintainable code.

§Features

Fiber Architecture - React-like fiber system with proper effect timing and state batching
Component-Based Architecture - Build modular UIs with reusable components
Hooks System - Manage state and side effects with React-like hooks
Async-First - Built on Tokio with first-class async/await support
Cross-Thread State Updates - Background tasks can safely update UI state

§Quick Start

use reratui::prelude::*;

struct Counter;

impl Component for Counter {
    fn render(&self, area: Rect, buffer: &mut Buffer) {
        let (count, set_count) = use_state(|| 0);

        if let Some(Event::Key(KeyEvent { code, kind: KeyEventKind::Press, .. })) = use_event() {
            match code {
                KeyCode::Char('j') => set_count.update(|n| n + 1),
                KeyCode::Char('k') => set_count.update(|n| n - 1),
                KeyCode::Char('q') => request_exit(),
                _ => {}
            }
        }

        let block = Block::default()
            .title("Counter")
            .borders(Borders::ALL);
        let paragraph = Paragraph::new(format!("Count: {}", count))
            .alignment(Alignment::Center)
            .block(block);
        paragraph.render(area, buffer);
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    render(|| Counter).await?;
    Ok(())
}

§Available Hooks

use_state - Local component state with batching
use_reducer - Complex state with actions
use_effect - Side effects with proper post-commit timing
use_context - Share data across components
use_ref - Mutable references
use_callback - Memoized callbacks
use_memo - Memoized values
use_event - Terminal event handling
use_interval - Periodic callbacks
use_timeout - Delayed callbacks

§Component Pattern

Implement the Component trait for your components:

use reratui::prelude::*;

struct MyComponent {
    title: String,
}

impl Component for MyComponent {
    fn render(&self, area: Rect, buffer: &mut Buffer) {
        let (state, set_state) = use_state(|| 0);
         
        // Custom layout logic
        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([Constraint::Length(3), Constraint::Min(0)])
            .split(area);
         
        // Render widgets directly
        let paragraph = Paragraph::new(self.title.clone());
        paragraph.render(chunks[0], buffer);
    }
}

§Key Types

FiberId - Unique identifier for a component instance
Fiber - A mounted component instance with its own hook state
FiberTree - Global fiber tree tracking all mounted components
Component - Trait for implementing components

§Examples

See the examples/ directory for:

counter_fiber - Basic state management and event handling
command_palette - Complex UI with animations and keyboard navigation

Re-exports§

pub use context_stack::ContextStack;
pub use element::Element;
pub use element::RenderableComponent;
pub use event::clear_current_event;
pub use event::get_current_event;
pub use event::peek_current_event;
pub use event::set_current_event;
pub use event::stop_event_propagation;
pub use fiber_tree::FiberTree;
pub use global_events::clear_global_handlers;
pub use global_events::on_global_event;
pub use global_events::process_global_event;
pub use panic_handler::setup_panic_handler;
pub use render_context::RenderContext;
pub use render_context::clear_render_context;
pub use render_context::init_render_context;
pub use render_context::is_render_context_initialized;
pub use render_context::with_render_context;
pub use render_context::with_render_context_mut;
pub use ratatui;

Modules§

components: Built-in components for common UI patterns.
context_stack: Context stack with proper lifecycle management.
element: Element module for the virtual DOM tree.
event: Event system for sharing terminal events between components.
fiber_tree: Fiber tree management for tracking all mounted component instances.
global_events: Global event handling for TUI applications
hooks: React-like hooks with proper semantics.
panic_handler: Panic handler for TUI applications
prelude: Prelude module for convenient imports
render_context: Consolidated render context for managing all thread-local state.
scheduler: Scheduler for state batching, effect execution, and reconciliation.

Structs§

AsyncPendingEffect: A pending async effect to be executed after commit
Block: A widget that renders borders, titles, and padding around other widgets.
Borders: Bitflags that can be composed to set the visible borders essentially on the block widget.
Buffer: A buffer that maps to the desired content of the terminal after the draw call
ComponentArea: Context value providing the render area to child components.
Fiber: A Fiber represents a mounted component instance with its own hook state. Named after React’s Fiber architecture.
FiberId: Unique identifier for a component instance (like React’s Fiber)
KeyEvent: Represents a key event.
KeyModifiers: Represents key modifiers (shift, control, alt, etc.).
Layout: The primary layout engine for dividing terminal space using constraints and direction.
Line: A line of text, consisting of one or more Spans.
Modifier: Modifier changes the way a piece of text is displayed.
Padding: Defines the padding for a Block.
Paragraph: A widget to display some text.
PendingEffect: A pending effect to be executed after commit
Rect: A rectangular area in the terminal.
RenderOptions: Options for configuring the render loop
Span: Represents a part of a line that is contiguous and where all characters share the same style.
StrictMode: Strict mode configuration for development
Style: Style lets you control the main characteristics of the displayed elements.
Text: A string split over one or more lines.
Wrap: Describes how to wrap text across lines.

Enums§

Color: ANSI Color
Constraint: A constraint that defines the size of a layout element.
Direction: Defines the direction of a layout.
Event: Represents an event.
KeyCode: Represents a key.
KeyEventKind: Represents a keyboard event kind.

Traits§

Component: A component trait that integrates with the fiber-based architecture.
Stylize: An extension trait for styling objects.
Widget: A Widget is a type that can be drawn on a Buffer in a given Rect.

Functions§

is_in_render_phase: Check if we’re currently in the render phase
is_strict_mode_enabled: Check if strict mode is enabled
render: New render function with React-like semantics
render_with_options: Render with custom options
request_exit: Request the render loop to exit
reset_component_position_counter: Resets the component position counter at the start of a render frame. This should be called by the runtime before each render phase.
reset_exit: Reset the exit flag (useful for tests)
set_strict_mode_enabled: Set strict mode enabled state
should_exit: Check if exit has been requested
warn_if_effect_during_render: Warn if an effect is executed during render phase (debug builds only)

Type Aliases§

Alignment: A type alias for HorizontalAlignment.
AsyncCleanupFn: Type alias for async cleanup functions returned by async effects
AsyncEffectFn: Type alias for async effect functions
AsyncEffectFuture: Type alias for the future returned by async effects
CleanupFn: Type alias for cleanup functions returned by effects

Crate reratui

Crate reratui Copy item path

§Reratui - A Modern, Reactive TUI Framework for Rust

§Features

§Quick Start

§Available Hooks

§Component Pattern

§Key Types

§Examples

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate reratui