textual-tui

Textual TUI Development

Build rich terminal user interfaces in Python using the Textual framework (v8.x).

Quick Start

pip install textual

Minimal app:

from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Static

class MyApp(App):
    TITLE = "My App"
    CSS_PATH = "app.tcss"  # or use CSS = "..." inline

    BINDINGS = [
        ("q", "quit", "Quit"),
    ]

    def compose(self) -> ComposeResult:
        yield Header()
        yield Static("Hello, World!")
        yield Footer()

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

Run in dev mode for live CSS editing:

textual run --dev app.py

Core Architecture

App Lifecycle

1. compose() — Yield widgets to build the initial UI (called once per screen)
2. on_mount() — Post-composition setup (fetch data, configure state)
3. run() — Enters terminal mode, starts event loop
4. exit(return_value) — Leaves terminal mode

Widget Composition

Widgets are composed declaratively by yielding them from compose(). Use containers for layout:

from textual.containers import Horizontal, Vertical, Grid
from textual.widgets import Button, Input, Static

def compose(self) -> ComposeResult:
    yield Header()
    with Horizontal():
        with Vertical(id="sidebar"):
            yield Button("New", id="new")
            yield Button("Open", id="open")
        with Vertical(id="main"):
            yield Input(placeholder="Search...")
            yield Static("Content area")
    yield Footer()

The with context manager syntax nests widgets inside containers.

Dynamic Widget Mounting

Add or remove widgets at runtime:

async def on_button_pressed(self, event: Button.Pressed) -> None:
    await self.mount(Static("New widget"), after=self.query_one("#main"))
    self.query_one("#old").remove()

Layout

Three layout modes, set on the parent container:

Vertical (Default)

Children stack top-to-bottom. They expand to fill width automatically.