textual

Textual

Write current, compiling Textual code (pinned to 8.2.7, Python ≥3.9, Rich 15.0.0) and refuse the pre-1.0 / 0.x patterns the model remembers from training — the 1.0 (Dec 2024) and 2.0 (Feb 2025) releases were hard breaks. The body is the load-bearing 20%: one mental model and one run-verified example per concept. Everything enumerable — the full widget catalog, every TCSS rule, the streaming model, testing, deploy, migration — lives in references/. Open the matching reference before writing nontrivial code in that area.

Mental model

Textual is a retained, reactive, DOM-like framework — the opposite of Ratatui's immediate mode and Bubble Tea's MVU. You build a tree of widget objects once, then mutate their state; Textual re-renders only the affected parts, like a web framework. It is async-native (asyncio) and styled with Textual CSS (TCSS), not layout math.

Four nouns carry everything:

• App — the application and event loop; App().run() (or await run_async()). Holds screens, handles input, owns the @work workers.
• Screen — a full-window container you push/pop; the default screen hosts your compose(). Modals/dialogs are screens.
• Widget — a node in the DOM tree. Leaf widgets draw themselves (render()); compound widgets yield children (compose()).
• DOM + TCSS — widgets form a tree you query with query_one/query (CSS selectors) and style with TCSS. Mutating a widget's reactive state schedules a repaint.

App, compose, and lifecycle

compose() runs once to build the tree; never touch widgets there — the DOM isn't mounted yet. Wait for on_mount, then resolve widgets by selector with query_one.

from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Button, Label

class CounterApp(App):
    BINDINGS = [("a", "add", "Add"), ("q", "quit", "Quit")]   # key → action_* → footer hint

    def compose(self) -> ComposeResult:        # build the tree ONCE
        yield Header()
        yield Label("count: 0", id="lbl")
        yield Button("hit", id="btn")
        yield Footer()

    def on_mount(self) -> None:                 # DOM is live; safe to touch widgets
        self.count = 0

    def action_add(self) -> None:               # bound to "a"
        self.count += 1
        self.query_one("#lbl", Label).update(f"count: {self.count}")

if __name__ == "__main__":
    CounterApp().run()