photon-ui

A blazing fast, minimal terminal UI framework for Rust.

Photon UI is a lightweight, high-performance TUI library built on crossterm. It features a custom differential renderer that only redraws what changed, ANSI-aware text wrapping, OSC 8 hyperlink support, terminal image rendering (Kitty and iTerm2 protocols), and a component-based architecture.

Features

• Differential renderer — Only updates cells that changed between frames, minimizing terminal output and improving performance.
• Component-based architecture — Build UIs by composing simple, reusable Component trait implementations.
• Built-in components — Text, truncated text, boxes, spacers, input fields, multi-line editors, select lists, settings toggles, loaders, markdown, and image widgets.
• Dual editing modes — Both Emacs and vim keybindings for Input and Editor components, switchable at runtime.
• Terminal image support — Render images inline using the Kitty graphics protocol or iTerm2 inline images.
• ANSI-aware text handling — Properly measures and wraps text containing ANSI escape sequences, Unicode, and grapheme clusters.
• Overlays — Position floating content with anchor-based constraints (center, top-left, bottom-right, etc.).
• Focus management — The TUI runtime handles focus cycling and routes input events to the focused component.
• Zero unnecessary dependencies — Core functionality relies only on crossterm, unicode-width, unicode-segmentation, pulldown-cmark, base64, and thiserror.

Quick start

Add photon-ui to your Cargo.toml:

[dependencies]
photon-ui = "0.1"

Build a simple app:

use photon_ui::{Component, TUI, Rendered, RenderError, TestTerminal};
use photon_ui::components::Text;

let mut tui = TUI::new(Box::new(TestTerminal::new(80, 24)));
tui.mount(Box::new(Text::new("Hello, world!", 0, 0)));
tui.render_frame().unwrap();

For a real application, use ProcessTerminal to drive the actual terminal:

use photon_ui::{TUI, Event};
use photon_ui::terminal::ProcessTerminal;
use photon_ui::components::{Text, Input};
use std::time::Duration;

fn main() -> std::io::Result<()> {
    let mut term = ProcessTerminal::new();
    term.start()?;

    let mut tui = TUI::new(Box::new(term));
    tui.mount(Box::new(Text::new("Name:", 0, 0)));
    tui.mount(Box::new(Input::new()));

    loop {
        tui.render_frame()?;

        if crossterm::event::poll(Duration::from_millis(100))? {
            let event = match crossterm::event::read()? {
                crossterm::event::Event::Key(key) => Event::Key(key),
                crossterm::event::Event::Resize(w, h) => Event::Resize(w, h),
                other => continue,
            };
            tui.handle_input(&event);
        }
    }
}

Components

Architecture

Component trait

Every visible element implements the Component trait:

pub trait Component {
    fn render(&self, width: u16) -> Result<Rendered, RenderError>;
    fn handle_input(&mut self, event: &Event) -> InputResult;
    fn as_focusable(&self) -> Option<&dyn Focusable>;
    fn as_focusable_mut(&mut self) -> Option<&mut dyn Focusable>;
}

• render produces the lines of text (and optional cursor or image commands) for the current frame.
• handle_input receives events when the component has focus.
• Focusable components participate in the tab order managed by TUI.

Renderer

The Renderer tracks the previous frame and computes a minimal set of cursor movements and writes needed to update the terminal. This avoids clearing the screen or redrawing unchanged content.

TUI runtime

TUI owns the terminal backend, manages a stack of components, handles focus cycling (Tab / Shift+Tab), and supports overlays positioned with Anchor and OverlayConstraints.

Input modes

Both Input and Editor support Emacs and vim editing styles:

Enable vim mode at construction time or toggle it at runtime with set_vim_mode_enabled.

Running the demo

The included demo showcases every component across four pages:

cargo run --example demo

Controls: