Textual — Rapid Application Development Framework for the Terminal

What it is

Textual is a Python framework for building terminal user interfaces (TUIs) with CSS-based styling, async event handling, and over 20 built-in widgets. Built on top of Rich, Textual lets you create applications that run both in the terminal and in a web browser through Textual Web.

Textual is for Python developers who want to build interactive command-line applications with modern UI patterns -- data tables, tree views, tabs, modals, and forms -- without leaving the terminal.

How it saves time or tokens

Building interactive terminal UIs with curses or blessed requires managing screen buffers, input handling, and rendering manually. Textual provides a component model similar to web frameworks: you compose widgets, style them with CSS, and handle events with async callbacks.

The CSS styling system means you can iterate on appearance without changing Python code. Change colors, spacing, and layout by editing a .tcss file, and the app updates live with textual-dev.

How to use

1. Install Textual and the dev tools:

pip install textual textual-dev

1. Create a basic app:

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

class HelloApp(App):
    CSS = 'Button { margin: 1; }'

    def compose(self) -> ComposeResult:
        yield Header()
        yield Button('Click me', id='hi')
        yield Footer()

    def on_button_pressed(self, event: Button.Pressed) -> None:
        self.notify('Button clicked')

if __name__ == '__main__':
    HelloApp().run()

1. Run with live CSS reloading:

textual run --dev my_app.py

Example

A data table with sortable columns:

from textual.app import App, ComposeResult
from textual.widgets import DataTable

class TableApp(App):
    def compose(self) -> ComposeResult:
        yield DataTable()

    def on_mount(self) -> None:
        table = self.query_one(DataTable)
        table.add_columns('Name', 'Language', 'Stars')
        table.add_rows([
            ('Textual', 'Python', '25000'),
            ('Rich', 'Python', '49000'),
            ('Charm', 'Go', '15000'),
        ])

if __name__ == '__main__':
    TableApp().run()

This renders a sortable, scrollable table in the terminal with keyboard navigation.

Related on TokRepo

• Coding AI tools -- developer frameworks and tools
• Automation tools -- CLI tool development

Common pitfalls

• Textual's CSS is not standard web CSS. It supports a subset of properties with terminal-specific additions like dock, layer, and offset. Check the Textual CSS reference for supported properties.
• Async event handling means you need to understand Python's asyncio. Long-running synchronous code in event handlers blocks the UI. Use run_worker() for background tasks.
• Terminal capabilities vary. Textual works best in modern terminals (iTerm2, Windows Terminal, Kitty). Older terminals may not render all widgets correctly.