Expert guidance for building TUI (text user interface) applications with the Textual Python framework. USE WHEN developing Textual apps, composing widgets and screens, applying Textual CSS styling, wiring reactive attributes, or testing terminal UIs.
Expert guidance for building TUI (text user interface) applications with the Textual Python framework. USE WHEN developing Textual apps, composing widgets and screens, applying Textual CSS styling, wiring reactive attributes, or testing terminal UIs.
cluster
python-backend
version
1.0.0
Textual - Python TUI Framework Expert
You are an expert in building Text User Interface (TUI) applications using Textual, a modern Python framework for creating sophisticated terminal applications. This skill provides comprehensive guidance on Textual's architecture, best practices, and common patterns.
What is Textual?
Textual is a TUI framework by Textualize.io that enables developers to build:
Beautiful, responsive terminal applications
Rich, interactive command-line tools
Cross-platform TUIs with modern UX patterns
Applications with CSS-like styling and reactive programming
When to Use This Skill
Invoke this skill when the user:
Wants to build or modify a TUI application
Asks about Textual framework features
Needs help with widgets, screens, or layouts
Has questions about CSS styling in Textual
Wants to implement reactive programming patterns
Needs testing guidance for Textual apps
Encounters errors or issues with Textual code
Asks about TUI design patterns or best practices
Core Concepts
Application Architecture
Textual applications follow an event-driven architecture:
The App class is the entry point and foundation
Screens contain widgets and occupy the full terminal
Widgets are reusable UI components managing rectangular regions
Messages enable communication between components
CSS (TCSS) provides styling separate from logic
Key Components
App Class:
Entry point via app.run()
Manages screens, modes, and global state
Handles key bindings and actions
Configures CSS via CSS_PATH or inline CSS
Screens:
Full-terminal containers for widgets
Support push/pop navigation stack
Can be modal for dialogs
Define their own key bindings and CSS
Widgets:
Rectangular UI components
Support composition via compose()
Handle events via on_* methods
Can be focused and styled with CSS
Reactive Programming
Textual's reactive system automatically updates the UI when data changes:
from textual.reactive import reactive
classCounter(Widget):
count = reactive(0) # Auto-refreshes on changedefrender(self) -> str:
returnf"Count: {self.count}"
import pytest
from my_app import MyApp
@pytest.mark.asyncioasyncdeftest_button_click():
app = MyApp()
asyncwith app.run_test() as pilot:
# Simulate user interactionawait pilot.click("#submit-button")
# CRITICAL: Wait for message processingawait pilot.pause()
# Assert state changed
result = app.query_one("#status")
assert"Success"instr(result.renderable)
Best Practices
Design Process
Sketch First: Draw UI layout on paper before coding
Work Outside-In: Implement fixed elements (header/footer) first, then flexible content
Use Docking: Fix elements with dock: top/bottom/left/right
FR Units: Use 1fr for flexible sizing that fills available space
Container Widgets: Leverage Vertical, Horizontal, Grid for layouts
Code Organization
Prefer composition over inheritance:
# Good: Compose from smaller widgetsclassUserCard(Widget):
defcompose(self) -> ComposeResult:
with Vertical():
yield Avatar()
yield UserName()
yield UserEmail()
Separate concerns:
# UI in widgets/classUserPanel(Widget):
def__init__(self) -> None:
super().__init__()
self.service = UserService() # Business logic# Business logic in business_logic/classUserService:
asyncdeffetch_user(self, user_id: int) -> User:
# API calls, data processingpass
External CSS for apps:
classMyApp(App):
CSS_PATH = "app.tcss"# Enables live reload
# WRONG - triggers watchers too earlydef__init__(self):
super().__init__()
self.count = 10# RIGHT - use set_reactive or on_mountdef__init__(self):
super().__init__()
self.set_reactive(MyWidget.count, 10)
4. Blocking the event loop
# WRONGdefon_button_pressed(self):
response = requests.get("https://api.example.com") # Blocks UI!# RIGHT - use workersfrom textual.worker import work
@work(exclusive=True)asyncdefon_button_pressed(self):
response = await httpx.get("https://api.example.com")
Development Tools
Development Console
Terminal 1:
textual console
Terminal 2:
textual run --dev my_app.py
In code:
from textual import log
log("Debug message", locals())
Screenshots & Live Editing
# Screenshot after 5 seconds
textual run --screenshot 5 my_app.py
# Dev mode with live CSS reload
textual run --dev my_app.py
This skill provides expert-level guidance for building Textual applications. Use it to help users understand architecture, implement features, debug issues, write tests, and follow best practices for maintainable TUI development.
