TUI Architecture & Concepts

The first design decision of any UI library is who remembers what is on the screen.

Ratatui’s documentation states its model plainly: it uses immediate-mode rendering with intermediate buffers, so each frame the application redraws every widget it wants visible. Bubble Tea sits in between: the application owns the model and the View method turns the model into a string, which makes it immediate in spirit, while the library’s renderer decides what to write. Retained toolkits such as Textual and Terminal.Gui keep a tree of live widgets, much like a desktop GUI toolkit.

"Immediate" describes the application’s code, not the bytes sent to the terminal. Every library discussed here diffs the new frame against the previous one before writing, so redrawing everything in memory does not mean rewriting everything on the wire. That is the subject of the rendering section below.

Every TUI is the same three-step loop, whatever it is called in a given library:

Two timing policies exist. In an event-driven loop the program sleeps until an event arrives and redraws only then; this is the cheapest and what Bubble Tea, Textual and ncurses programs do. In a tick-driven loop the program also wakes at a fixed rate (for example 30 times per second) to advance animations or poll background state, which is what a dashboard needs and what Ratatui’s async recipes use. Ratatui’s Terminal::draw does not wait for events itself; the application’s loop decides when to call it, and a resize does not trigger a redraw until the application draws again.

In raw mode the terminal sends the program bytes, not characters in lines. Everything above that is the library’s decoder.

The exact byte sequences, the modes and the terminal queries are documented in Escape Sequences & Terminal Capabilities. Two points matter for architecture. First, the legacy encoding cannot report key releases or most modifier combinations; the Kitty keyboard protocol and the Windows console input records can, and libraries expose that as an event kind. crossterm’s Event type has Key, Mouse, Paste, Resize, FocusGained and FocusLost variants, Paste is emitted only when bracketed paste is enabled, and is_key_press is false for key release and repeat events. Second, on Windows the console reports both the press and the release of a key, so a program that reacts to every key event handles each key twice unless it filters on the event kind; Ratatui’s FAQ lists this as a known cause of duplicate key events. Match on the press kind on every platform and the same code is correct everywhere.

A terminal is a grid of cells. Each cell holds one grapheme (usually one character), a foreground and background colour and a set of attributes such as bold and underline. A TUI library models the grid in memory as a buffer and renders in four steps, shown in the figure:

Ratatui documents exactly this behaviour: Terminal::draw passes a Frame to a closure, and after the closure returns Ratatui diffs the result against the previous frame and writes only the changes. The first frame has no previous buffer, so every cell is written once, which is why a TUI’s first paint is the largest write.

Source: Ratatui — crate documentation, rendering and Terminal::draw

Writing a frame as several small writes can show a half-drawn screen: the terminal may paint between two writes, which looks like tearing or flicker. Terminals that implement synchronized output (private mode 2026, a community specification from the Contour terminal’s vt-extensions repository, not an ECMA-48 or ISO standard) hold the display while the application writes between ESC [ ? 2026 h and ESC [ ? 2026 l and show the frame atomically. Terminals that do not know the mode ignore it, so wrapping every frame is harmless; whether a given terminal honours it is not guaranteed by any standard.

Layout answers "which rectangle does this widget draw into". Four families are in use.

The practical rules are the same in every family. Compute layout from the current terminal size on every frame, not once at start, because a resize can happen at any time. Give the one flexible region (the list of books) the "rest of the space" and fix the small ones (a one-row status bar). Decide what happens below a minimum size: a TUI that panics or draws garbage at 20 columns is a common bug report. Terminal cells are not square and not pixels, so there is no sub-cell positioning; sizes are whole columns and rows.

The loop of the previous sections needs a rule for where state lives and how events change it. Three patterns recur.

A TUI changes the terminal on entry and must undo every change on exit, however it exits.

The undo steps must run on every exit path:

Ratatui packages the whole lifecycle in three functions. ratatui::run initialises the terminal, runs a closure and restores the terminal on exit, and it installs a panic hook; ratatui::init and ratatui::restore give manual control, and init_with_options accepts a custom Viewport such as an inline one. The Ratatui documentation points to the backend for what initialisation switches on; with the crossterm backend (the default) that is raw mode and the alternate screen.

Source: Ratatui — crate documentation (run, init, restore, Terminal::draw); crossterm — Event

The same lifecycle exists in every library under other names: ncurses programs call initscr and must call endwin, Textual’s App.run enters and leaves application mode, Terminal.Gui pairs Init with shutdown. Libraries cannot restore after a crash they never see, so a program that mixes the library with its own raw terminal calls must still restore on its own.

The loop must never block. A slow operation inside update (a network call to a library service, a file scan) freezes the screen and the keys typed meanwhile pile up. The standard structure is a loop that waits on one stream of events fed by several producers:

Each library supplies one mechanism: a tea.Cmd that runs in its own goroutine, a Textual worker, an async task and an action channel in Ratatui’s Tokio recipe. The common rule is that workers never touch the UI or the state directly. They send a message, and the loop applies it. Long work needs a way to cancel (drop the sender, a cancellation token, context.Context) and a way to show progress without redrawing faster than the screen can change. Cap the redraw rate: a worker that sends a thousand progress messages per second should cause at most one frame per tick.

Keyboard-only interfaces need an explicit idea of which element receives the next key. A text box must take printable keys while a list takes j and k, and global shortcuts such as q must not fire while the search box has the focus.

Retained toolkits provide focus as a feature: Textual widgets can take focus, Ink offers a focus hook, Terminal.Gui, as a retained toolkit, manages focus between its views. Immediate-mode libraries leave it to the application: keep a focus field in the model (List, Details, Search), route every key event to the focused component first, then to the global bindings, and draw the focused pane with a distinct border. Provide Tab and Shift-Tab to cycle, and make a visible focus indicator that does not rely on colour alone. Modal states (a confirmation dialog) are the same idea with a stack: the top of the stack gets the keys.

The table lists the libraries most used for the Bookshelf scenario. "Windows" means that the library supports the Windows console or Windows Terminal natively, as far as its own documentation shows; where the documentation is silent that is said.

The licence and platform columns come from each project’s own repository or documentation; check them against the release you use. Prefer the library that matches the language the rest of the tool is written in: a polyglot shelf (Go core, Rust TUI) doubles the build and release work for little gain. Within a language, choose by paradigm: Elm style (Ratatui with TEA, Bubble Tea) for programs where state is the interesting part, retained toolkits (Textual, Terminal.Gui) for form-heavy applications, and curses-style libraries for portability to old systems.

A TUI is a stream of cursor moves and characters, not a tree of semantic elements, and no library changes that. Screen readers follow the terminal’s text output and the cursor, so a program that redraws regions of the screen, moves the cursor around the layout or animates will be read as a series of fragments; there is no official guidance from the screen-reader projects for TUIs, so none is given here. What the community and the GitHub CLI team recommend for terminal programs applies to TUIs a fortiori: keep the cursor on the element that has the focus, do not rely on colour or animation alone, use the 16 ANSI colours so users can theme them, and avoid constant redraws.

The robust answer is architectural. Treat the TUI as one view over operations that also exist as plain commands: shelf list, shelf add, shelf loan and shelf return work without a screen, can be scripted, tested, read aloud and used by agents, and shelf tui calls the same functions. The design rule, "the TUI is a view over the command line", is on the TUIs vs. CLIs page, and the broader topics (plain modes, never colour-only meaning, contrast, localisation) are on Accessibility & Internationalization. Testing approaches (buffer assertions, snapshots, a real pseudo-terminal) are on Testing Terminal Apps & TUIs.