Textual

Textual is a Python framework for building rich, interactive user interfaces that run in the terminal or in a web browser from the same codebase. It layers a reactive component model, a CSS-inspired styling system, and an async message-passing event loop on top of Rich, letting developers build apps out of widgets, layouts, and animations instead of hand-rolled ANSI escape codes.

Applications are built by subclassing App and composing a tree of Widget objects, each with typed reactive attributes that automatically trigger re-renders and CSS refresh when changed. A built-in dev console, snapshot testing tools, and a fuzzy-search command palette round out a workflow aimed at maintaining terminal apps for the long term, and the same app can be exposed over the web via textual serve or Textual Web without code changes.

What You Get

• App and Widget base classes - subclass App to define your program and compose a tree of prebuilt or custom Widget components.
• CSS-based styling system - style widgets with an external, hot-reloadable CSS-like syntax instead of hardcoded layout code.
• Reactive attributes - typed reactive() and var() descriptors that automatically trigger watchers, re-renders, and CSS updates on change.
• Built-in widget library - buttons, data tables, trees, inputs, text areas, markdown viewers, and more, all themeable out of the box.
• Dev console and command palette - a separate-terminal debug console for live logging, plus a fuzzy-search command palette baked into every app.
• Terminal-to-web serving - run any Textual app in a browser via textual serve with no code changes.

Common Use Cases

• Building developer tools and dashboards - engineers ship interactive CLIs, log viewers, and system dashboards without leaving the terminal.
• Rapid internal tooling - teams prototype admin panels and ops tools faster than a full web frontend, then optionally serve them over HTTP.
• Cross-platform desktop-like apps - a single codebase targets macOS, Linux, and Windows terminals plus the browser.
• Replacing legacy curses/ncurses apps - projects migrate off low-level terminal libraries to a typed, testable, async framework.

Under The Hood

Architecture Textual is a layered, async-first framework: App (src/textual/app.py) drives an asyncio event loop and owns the render/compositor cycle, Widget and DOMNode (widget.py, dom.py) form a tree of components each with their own message pump (message_pump.py) for decoupled event handling, and a dedicated CSS engine (css/stylesheet.py) parses and applies an external stylesheet syntax to that tree independently of widget logic. Typed reactive()/var() descriptors (reactive.py) bridge the two: changing an attribute triggers watchers, layout invalidation, and a compositor update without the developer wiring re-renders by hand. The result is a structure closer to a browser’s DOM + CSSOM + event loop than a typical procedural terminal library, and swapping the core compositor or message-pump abstraction would ripple through every widget in the tree.

Tech Stack Textual targets Python 3.9+ and is built directly on Rich (>=14.2.0) for terminal rendering primitives, with markdown-it-py, platformdirs, and typing-extensions as core dependencies; an optional syntax extra pulls in tree-sitter plus per-language grammars for the built-in code/text-area highlighting. The project builds and publishes via Poetry (with a parallel uv.lock), documents itself with MkDocs across online/offline/nav configs, and ships py.typed for downstream type checking.

Code Quality The repo carries 250+ test files under tests/, covering CSS parsing, widgets, layouts, animations, and workers, plus pytest-textual-snapshot for SVG-based visual regression testing, run through pytest-asyncio and pytest-xdist. Type checking is enforced with mypy, formatting with black, and linting with ruff; GitHub Actions workflows run CodeQL and a full package/test pipeline on every change, giving the codebase a typed, CI-gated quality bar that’s uncommon for TUI libraries.

API Design The public API favors declarative composition: apps implement compose() as a generator yielding widgets, style them from separate CSS text rather than constructor arguments, and react to state changes via typed reactive attributes instead of manual refresh calls. Because a running Textual app occupies the whole terminal, the framework also supplies its own out-of-process dev console for print-style debugging and an extensible, built-in command palette — both are small but telling investments in the developer experience of building software you can’t easily print() into.