telex - tui

A reactive TUI framework for Rust, inspired by React's component model.

Declare your UI, manage state with hooks, and let Telex handle the rendering. If you've used React, this will feel familiar. If you haven't, it's a clean way to build terminal apps without wrestling raw cells.

Quick Start

From the repo

Clone, browse, run:

git clone https://github.com/telex-tui/telex-tui/
cd telex-tui

# Interactive example browser — best way to get a feel for things
./run-examples.sh

# Or run one directly
cargo run -p telex-tui --example 02_counter

Press F1 in any example to see what it demonstrates.

There are 39 numbered examples covering everything from hello world to an embedded terminal emulator. See the Examples Guide for the full list.

As a dependency

cargo new my-app && cd my-app
cargo add telex-tui

use telex::prelude::*;

struct App;

impl Component for App {
    fn render(&self, cx: Scope) -> View {
        let count = state!(cx, || 0);

        View::vstack()
            .child(View::text(format!("Count: {}", count.get())))
            .child(
                View::button()
                    .label("+")
                    .on_press(with!(count => move || count.update(|n| *n += 1)))
                    .build()
            )
            .build()
    }
}

fn main() {
    telex::run(App).unwrap();
}

What's in the box

State & hooks — state! macro for order-independent reactive state. effect! and effect_once! for side effects. stream! and async_data! for background work. channel!/port! for external events, interval! for timers, reducer! for state machines. All single-threaded — no Arc, no Send bounds.

Layout — VStack, HStack, Box with flex, min/max constraints, and percentage sizing. Split panes for resizable panels. Tabs, modals, menus.

Widgets — Text, TextInput, TextArea, Button, Checkbox, RadioGroup, List, Table, Tree, Tabs, ProgressBar, StatusBar, MenuBar, Modal, Form, Toast, Markdown, Split, Slider, and more. Builder pattern or view! macro — your choice.

Focus management — Tab navigation, modal focus containment, cursor navigation, initial focus. Focus indicators appear only when the user starts navigating.

Theming — 14 built-in themes: catppuccin, dracula, gruvbox, nord, tokyo night, and others. One line to switch.

Unicode — Proper grapheme cluster handling. Emoji, CJK, combining characters all render at correct widths.

Streaming — text_stream! macro for token-by-token rendering. The kind of thing you need for LLM output. For general-purpose external events, use channel!/port!.

Example: AI Chat App

The repo includes a multi-provider chat app in examples/chat/ — a real application built with Telex that supports Anthropic, OpenAI, Gemini, and Ollama:

export GEMINI_API_KEY="..."   # or ANTHROPIC_API_KEY, OPENAI_API_KEY
cargo run -p chat

No API key? It falls back to mock responses so you can still see the UI. See the chat example for full configuration.

Experimental Features

These work, but expect rough edges:

• Terminal widget — Run bash, vim, htop inside your TUI (example 33)
• Canvas — Pixel-level drawing via Kitty graphics protocol (example 29)
• Image — PNG/JPEG/GIF display via Kitty protocol (example 30)

Canvas and Image require a Kitty-compatible terminal (Kitty, Ghostty, WezTerm).

Documentation

Project Structure

telex-tui/
├── crates/
│   ├── telex/           # Core framework + 39 examples
│   └── telex-macro/     # view!, state!, effect!, effect_once!, with!, stream!, async_data!, text_stream!, terminal!, channel!, port!, interval!, reducer! proc macros
├── examples/
│   ├── chat/            # AI chat app (multi-provider)
│   ├── layout-playground/
│   ├── layout-showcase/
│   └── perf-test/
└── docs/                # Book, architecture, design docs

Contributing

Issues and PRs welcome. If you hit a rendering bug, the test harness makes it straightforward to reproduce:

use telex::testing::TestApp;

let mut app = TestApp::new(|_cx: Scope| {
    View::text("content that renders wrong")
}).with_size(60, 10);

app.assert_visible("expected");

cargo test -p telex-tui

License

MIT — see LICENSE.

Copyright (c) 2025 Mark Branion