Python framework for building terminal and browser UIs. Provides widget-based DOM, CSS styling (.tcss), reactive attributes, event system, Workers API for concurrency, command palette, and theming. Use when building terminal UIs, CLI tools with rich interfaces, data dashboards, interactive forms, or any Python application requiring a graphical interface in the terminal.
Python framework for building terminal and browser UIs. Provides widget-based DOM, CSS styling (.tcss), reactive attributes, event system, Workers API for concurrency, command palette, and theming. Use when building terminal UIs, CLI tools with rich interfaces, data dashboards, interactive forms, or any Python application requiring a graphical interface in the terminal.
Textual is a Rapid Application Development (RAD) framework for Python, built by Textualize.io. It lets you build sophisticated user interfaces with a simple Python API that run in the terminal or a web browser (via textual-serve). Textual runs on Linux, macOS, Windows, and any OS where Python runs — including single-board computers and over SSH.
Key characteristics:
Widget-based DOM — hierarchical tree of widgets, each managing a rectangular screen region
CSS styling — .tcss files with selectors, pseudo-classes, and theme variables ($primary, $surface)
Reactive attributes — auto-refresh on value change, with watch/validate hooks
Event/message system — asyncio-powered message queues per widget, bubbling, custom messages
Screen stack — push/pop/switch screens for modal dialogs and navigation
Workers API — background coroutines and threads with state tracking
Command palette — built-in Ctrl+P palette for actions and theme switching
Inline mode — run apps beneath the shell prompt (non-fullscreen)
Devtools — live CSS editing, console logging via textual run --dev
When to Use
Building terminal user interfaces (TUIs) with Python
Creating interactive CLI tools that need buttons, forms, tables, or trees
Developing data dashboards or monitoring displays in the terminal
Prototyping UIs rapidly without browser tooling
Building apps that must run over SSH or on low-resource hardware
Every Textual application starts by subclassing App. Widgets are components that manage portions of the screen. The app composes widgets via a compose() generator method:
CSS selectors include type (Button), ID (#submit), class (.active), and pseudo-classes (:focus, :disabled).
Reactive Attributes
Reactive attributes auto-refresh the widget when changed. Create them with reactive() from textual.reactive:
from textual.reactive import reactive
from textual.widget import Widget
classCounter(Widget):
count = reactive(0)
defrender(self) -> str:
returnf"Count: {self.count}"
Use var() for reactive attributes that should not trigger refresh. Use watch_<name>() methods to observe changes, and validate_<name>() methods to constrain values.
Events and Messages
Textual uses an asyncio message queue per widget. Event handlers use the on_<event_name> naming convention or the @on(Event) decorator:
from textual import on
from textual.widgets import Button
classMyApp(App):
@on(Button.Pressed)defhandle_click(self, event: Button.Pressed) -> None:
self.bell()
Messages bubble up the DOM tree by default. Call event.stop() to prevent bubbling, or event.prevent_default() to skip base class handlers.
Key Bindings
Define key bindings with a BINDINGS class variable — a list of (key, action, description) tuples:
