Skip to main content

Crate tui

Crate tui 

Source
Expand description

§tui

A lightweight, composable terminal UI library for building full-screen CLI apps.

§Core Primitives

  • Component — trait for reusable widgets with event handling and rendering
  • Event — unified input events (key, paste, mouse, tick, resize)
  • Frame — rendered output: lines + cursor position
  • Layout — vertical section composition into a Frame
  • Renderer — efficient diff-based terminal renderer (feature: runtime)
  • TerminalSession — raw-mode lifecycle management (feature: runtime)

§Quick Start

The library provides composable building blocks — your app owns its event loop and state machine.

use tui::{Component, Event, Frame, KeyCode, Line, ViewContext};

// Define your app state and use Component for child widgets
struct MyWidget { count: i32 }

impl Component for MyWidget {
    type Message = ();
    async fn on_event(&mut self, event: &Event) -> Option<Vec<()>> {
        if let Event::Key(key) = event {
            match key.code {
                KeyCode::Char('j') => self.count += 1,
                KeyCode::Char('k') => self.count -= 1,
                _ => return None,
            }
        }
        Some(vec![])
    }
    fn render(&mut self, _ctx: &ViewContext) -> Frame {
        Frame::new(vec![Line::new(format!("Count: {}", self.count))])
    }
}

Convert crossterm events with Event::try_from(crossterm_event) — it filters key releases and maps resize events automatically.

§Built-in Widgets

  • Panel — bordered container
  • Form, TextField, NumberField — form inputs
  • Checkbox, RadioSelect, MultiSelect — selection controls
  • SelectList — scrollable list with selection
  • Spinner — animated progress indicator
  • Combobox — fuzzy-searchable picker (feature: picker)
  • FocusRing — Tab/BackTab focus traversal

§Feature Flags

FeatureDescriptionDefault
syntaxSyntax highlighting via syntectyes
pickerFuzzy combobox pickeryes
testingTest utilities (TestTerminal, render_component)no

Disable defaults for lower-level use:

[dependencies]
tui = { version = "0.1", default-features = false }

§License

MIT

Modules§

test_picker
testing

Structs§

Checkbox
Boolean toggle rendered as [x] / [ ].
Combobox
Cursor
Logical cursor position within a component’s rendered output.
DiffLine
A single line in a diff, tagged with its change type.
DiffPreview
A preview of changed lines for an edit operation.
FocusRing
Tracks which child in a list of focusable items is currently focused.
Form
A multi-field form rendered as a tabbed pane.
FormField
A single field within a Form.
Frame
Logical component output: lines plus cursor state.
FuzzyMatcher
KeyEvent
Represents a key event.
KeyEventState
Represents extra state about the key event.
KeyModifiers
Represents key modifiers (shift, control, alt, etc.).
Layout
Stacks content sections vertically with automatic cursor offset tracking.
Line
A single line of styled terminal output, composed of Spans.
MouseEvent
Represents a mouse event.
MultiSelect
Multi-select from a list of options, rendered as checkboxes with a cursor.
NumberField
Numeric input field supporting integers or floats.
Panel
A bordered panel for wrapping content blocks with title/footer chrome.
RadioSelect
Single-select from a list of options, rendered as radio buttons.
Renderer
Pure TUI renderer with frame diffing and terminal state management.
SelectList
SelectOption
A single option in a selection list.
Span
A contiguous run of text sharing a single Style.
Spinner
SplitDiffCell
One side of a split diff row.
SplitDiffRow
A row in a side-by-side diff, pairing an old (left) line with a new (right) line.
Style
Text styling: foreground/background colors and attributes (bold, italic, etc.).
SyntaxHighlighter
Unified syntax-highlighting facade.
TerminalSession
TextField
Single-line text input with cursor tracking and navigation.
Theme
Full resolved theme for TUI rendering.
ViewContext
Environment passed to render methods: terminal size, theme.

Enums§

Color
Represents a color.
CrosstermEvent
Represents an event.
DiffTag
Tag indicating the kind of change a diff line represents.
Event
Events that a [Widget] can handle.
FocusOutcome
The result of FocusRing::handle_key.
FormFieldKind
The widget type backing a FormField.
FormMessage
Messages emitted by Form input handling.
KeyCode
Represents a key.
KeyEventKind
Represents a keyboard event kind.
MouseCapture
MouseEventKind
A mouse event kind.
PickerKey
PickerMessage
Generic message type for picker components.
RendererCommand
SelectListMessage
ThemeBuildError

Constants§

BORDER_H_PAD
Width consumed by left (“│ “) and right (” │“) borders.
BRAILLE_FRAMES
GUTTER_WIDTH
SEPARATOR
SEPARATOR_WIDTH

Traits§

Component
A component that can process events and emit typed messages.
Searchable
SelectItem

Functions§

classify_key
display_width_text
highlight_diff
Render a diff preview with syntax-highlighted context/removed/added lines.
merge
Merge two event outcomes. None (ignored) yields to the other. Messages are concatenated in order.
pad_text_to_width
Pads text with trailing spaces to reach target_width display columns. Returns the original text unchanged if it already meets or exceeds the target.
render_diff
Renders a diff preview, choosing split or unified based on terminal width and whether the diff has removals.
render_markdown
soft_wrap_line
spawn_terminal_event_task
split_blank_panel
split_render_cell
terminal_size
truncate_line
Truncates a styled line to fit within max_width display columns.
truncate_text
Truncates text to fit within max_width display columns, appending “…” if truncated. Returns the original string borrowed when no truncation is needed.
wrap_selection
Wrapping navigation helper for selection indices. delta of -1 moves up, +1 moves down, wrapping at boundaries.