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

class Counter(Widget):
    count = reactive(0)  # Auto-refreshes on change

    def render(self) -> str:
        return f"Count: {self.count}"

Features:

• •Validation: validate_<attr>() methods constrain values
• •Watchers: watch_<attr>() methods react to changes
• •Computed properties: compute_<attr>() for derived values
• •Recompose: Rebuild widget tree when data changes

CSS Styling (TCSS)

Textual uses CSS-like syntax for styling:

Button {
    background: $primary;
    margin: 1;
}

#submit-button {
    background: $success;
}

.danger {
    background: $error;
}

Benefits:

• •Separation of concerns (style vs logic)
• •Live reload during development
• •Theme system with semantic colors
• •Responsive layout with FR units

Common Patterns

Basic App Template

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

class MyApp(App):
    CSS_PATH = "app.tcss"

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

    def on_mount(self) -> None:
        """Called after app starts."""
        pass

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

Widget Communication

Follow "Attributes down, messages up":

# Parent sets child attributes (down)
child.value = 10

# Child posts messages to parent (up)
class ChildWidget(Widget):
    class Updated(Message):
        def __init__(self, value: int) -> None:
            super().__init__()
            self.value = value

    def update_value(self) -> None:
        self.post_message(self.Updated(self.value))

# Parent handles child messages
class ParentWidget(Widget):
    def on_child_widget_updated(self, message: ChildWidget.Updated) -> None:
        self.log(f"Child updated: {message.value}")

Testing Pattern

import pytest
from my_app import MyApp

@pytest.mark.asyncio
async def test_button_click():
    app = MyApp()
    async with app.run_test() as pilot:
        # Simulate user interaction
        await pilot.click("#submit-button")

        # CRITICAL: Wait for message processing
        await pilot.pause()

        # Assert state changed
        result = app.query_one("#status")
        assert "Success" in str(result.renderable)

Best Practices

Design Process

1. •Sketch First: Draw UI layout on paper before coding
2. •Work Outside-In: Implement fixed elements (header/footer) first, then flexible content
3. •Use Docking: Fix elements with dock: top/bottom/left/right
4. •FR Units: Use 1fr for flexible sizing that fills available space
5. •Container Widgets: Leverage Vertical, Horizontal, Grid for layouts

Code Organization

Prefer composition over inheritance:

# Good: Compose from smaller widgets
class UserCard(Widget):
    def compose(self) -> ComposeResult:
        with Vertical():
            yield Avatar()
            yield UserName()
            yield UserEmail()

Separate concerns:

# UI in widgets/
class UserPanel(Widget):
    def __init__(self) -> None:
        super().__init__()
        self.service = UserService()  # Business logic

# Business logic in business_logic/
class UserService:
    async def fetch_user(self, user_id: int) -> User:
        # API calls, data processing
        pass

External CSS for apps:

class MyApp(App):
    CSS_PATH = "app.tcss"  # Enables live reload

Performance

1. •Target 60fps for smooth terminal rendering
2. •Use Static widget for cached rendering
3. •Cache expensive operations with @lru_cache
4. •Use immutable objects for data structures
5. •Workers for async operations to avoid blocking UI

Accessibility

• •Full keyboard navigation support
• •Set can_focus = True on interactive widgets
• •Provide meaningful key bindings
• •Use semantic color variables ($primary, $error)
• •Test with different terminal sizes

Common Errors & Solutions

1. Forgetting async/await

# WRONG
def on_button_pressed(self):
    self.mount(Widget())

# RIGHT
async def on_button_pressed(self):
    await self.mount(Widget())

2. Missing pilot.pause() in tests

# WRONG - race condition
async def test_feature():
    await pilot.click("#button")
    assert app.query_one("#status").text == "Done"

# RIGHT
async def test_feature():
    await pilot.click("#button")
    await pilot.pause()  # Wait for processing
    assert app.query_one("#status").text == "Done"

3. Modifying reactives in init

# WRONG - triggers watchers too early
def __init__(self):
    super().__init__()
    self.count = 10

# RIGHT - use set_reactive or on_mount
def __init__(self):
    super().__init__()
    self.set_reactive(MyWidget.count, 10)

4. Blocking the event loop

# WRONG
def on_button_pressed(self):
    response = requests.get("https://api.example.com")  # Blocks UI!

# RIGHT - use workers
from textual.worker import work

@work(exclusive=True)
async def on_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

Project Structure

Medium/Large Apps:

project/
├── src/
│   ├── app.py              # Main App class
│   ├── screens/
│   │   ├── main_screen.py
│   │   └── settings_screen.py
│   ├── widgets/
│   │   ├── status_bar.py
│   │   └── data_grid.py
│   └── business_logic/
│       ├── models.py
│       └── services.py
├── static/
│   └── app.tcss           # External CSS
├── tests/
│   ├── test_app.py
│   └── test_widgets/
└── pyproject.toml

Instructions for Assistance

When helping users with Textual:

1. •Assess Context: Understand their app structure and goals
2. •Check Basics: Verify imports, async/await, and lifecycle methods
3. •Provide Examples: Show concrete, runnable code
4. •Explain Patterns: Describe why a pattern is recommended
5. •Test Guidance: Include testing code when implementing features
6. •Debug Support: Use console logging and visual debugging tips
7. •Best Practices: Suggest improvements for maintainability

Always consider:

• •App complexity (simple vs multi-screen)
• •State management needs (local vs global)
• •Performance requirements
• •Testing strategy
• •Code organization and maintainability

Additional Resources

For detailed reference information:

• •quick-reference.md: Concise templates, patterns, and cheat sheets
• •guide.md: Comprehensive architecture, design principles, and best practices
• •Official Documentation: https://textual.textualize.io

Quick Reference Highlights

Useful Built-in Widgets

Input & Selection:

• •Button, Checkbox, Input, RadioButton, Select, Switch, TextArea

Display:

• •Label, Static, Pretty, Markdown, MarkdownViewer

Data:

• •DataTable, ListView, Tree, DirectoryTree

Containers:

• •Header, Footer, Tabs, TabbedContent, Vertical, Horizontal, Grid

Key Lifecycle Methods

def __init__(self) -> None:
    """Widget created - don't modify reactives here."""
    super().__init__()

def compose(self) -> ComposeResult:
    """Build child widgets."""
    yield ChildWidget()

def on_mount(self) -> None:
    """After mounted - safe to modify reactives."""
    self.set_interval(1, self.update)

def on_unmount(self) -> None:
    """Before removal - cleanup resources."""
    pass

Common CSS Patterns

/* Docking */
#header { dock: top; height: 3; }
#sidebar { dock: left; width: 30; }

/* Flexible sizing */
#content { width: 1fr; height: 1fr; }

/* Grid layout */
#container {
    layout: grid;
    grid-size: 3 2;
    grid-columns: 1fr 2fr 1fr;
}

/* Theme colors */
Button {
    background: $primary;
    color: $text;
}

Button:hover {
    background: $primary-lighten-1;
}

Summary

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.