Textual App Lifecycle
Purpose
Understand and implement proper Textual application lifecycle patterns including initialization, mounting, screen management, background workers, and graceful shutdown. This is the foundation for building robust TUI applications.
Quick Start
from textual.app import App, ComposeResult
from textual.binding import Binding
from textual.widgets import Header, Footer, Static
from typing import ClassVar
class MyApp(App):
"""Minimal Textual application with proper lifecycle."""
TITLE = "My Application"
SUB_TITLE = "Powered by Textual"
BINDINGS: ClassVar[list[Binding]] = [
Binding("q", "quit", "Quit", show=True, priority=True),
Binding("ctrl+c", "quit", "Quit", show=False, priority=True),
]
def compose(self) -> ComposeResult:
"""Compose the application layout."""
yield Header(show_clock=True)
yield Static("Welcome to Textual!", id="content")
yield Footer()
def on_mount(self) -> None:
"""Handle application mount event."""
# Initialize application state, load configuration, etc.
self.notify("Application started", severity="information")
def action_quit(self) -> None:
"""Handle quit action with cleanup."""
self.exit()
if __name__ == "__main__":
app = MyApp()
app.run()Instructions
Step 1: Define App Class and Metadata
Create your App subclass with proper metadata and configuration:
from textual.app import App, ComposeResult
from textual.binding import Binding
from textual.screen import Screen
from typing import ClassVar
class MyApp(App[None]): # [T] is the return type for app.run()
"""Application description."""
# Metadata
TITLE = "Application Title"
SUB_TITLE = "Optional subtitle"
# Keyboard bindings
BINDINGS: ClassVar[list[Binding | tuple]] = [
Binding("q", "quit", "Quit", show=True, priority=True),
Binding("ctrl+c", "quit", "Quit", show=False, priority=True),
("r", "refresh", "Refresh"),
]
# CSS styling (inline or separate .css file)
CSS = """
Screen {
background: $surface;
}
"""
# Theme selection
THEME = "dracula" # Built-in themes: nord, dracula, monokai, solarized-dark, etc.Step 2: Implement Application Composition
Define compose() to return all top-level widgets:
def compose(self) -> ComposeResult:
"""Compose the application layout.
Yields:
Application components (Header, Footer, widgets, etc).
Yields immediately - don't use async here.
"""
yield Header(show_clock=True) # Optional header with clock
yield StaticContent() # Your custom widgets
yield Footer() # Optional footer with bindingsKey Points:
compose()is synchronous - don't useawait- Widgets are yielded in order (they appear top-to-bottom)
- Use Container, Horizontal, Vertical for layout
- Containers support CSS Grid layout
Step 3: Handle App Initialization (on_mount)
Implement on_mount() for initialization after all widgets are mounted:
def on_mount(self) -> None:
"""Handle application mount event.
Called after compose() completes and all widgets are mounted.
Use for:
- Loading configuration
- Initializing state
- Starting background workers
- Setting up timers
- Querying mounted widgets
"""
# Load configuration
try:
self._config = self._load_config()
except Exception as e:
self.notify(f"Config error: {e}", severity="error")
return
# Query and configure widgets
content = self.query_one("#content", Static)
content.update("Initialized!")
# Set up auto-refresh timer (runs every N seconds)
self.set_interval(5.0, self._on_timer)
# Start background worker
self.run_worker(self._background_task())
async def _background_task(self) -> None:
"""Background async task that runs concurrently."""
while True:
# Do async work (I/O, network, etc.)
await asyncio.sleep(1)
self._update_ui()
def _on_timer(self) -> None:
"""Called by timer periodically."""
# Synchronous callback - don't use await
passImportant Rules:
on_mount()is synchronous- Can use
self.query_one()to access widgets (they're mounted now) - Use
self.run_worker()to start async tasks - Use
self.set_interval()for periodic tasks - Use
self.notify()to show toast messages
Step 4: Implement Action Handlers
Actions are triggered by keybindings and can be async:
def action_refresh(self) -> None:
"""Synchronous action handler."""
self.run_worker(self._async_refresh())
async def _async_refresh(self) -> None:
"""Async action implementation."""
try:
# Do async work (fetch data, update UI)
data = await self._fetch_data()
await self._update_ui(data)
except Exception as e:
self.notify(f"Refresh failed: {e}", severity="error")
def action_quit(self) -> None:
"""Exit the application."""
# Cleanup happens automatically
self.exit()
def action_add_item(self) -> None:
"""Action with optional argument."""
self.run_worker(self._show_dialog())Pattern:
- Keybindings call action methods
- Actions can be sync or async
- For async work, use
self.run_worker() - Action methods are public (no leading underscore)
Step 5: Handle Screen Navigation
Switch between screens for modal dialogs, multi-screen apps:
class MyApp(App):
def action_show_settings(self) -> None:
"""Push settings screen on top of current screen."""
self.push_screen(SettingsScreen())
def action_close_settings(self) -> None:
"""Pop settings screen and return to previous."""
self.pop_screen()
class SettingsScreen(Screen):
"""Modal settings dialog."""
def compose(self) -> ComposeResult:
yield Static("Settings")
def on_mount(self) -> None:
"""Initialize settings screen."""
pass
def action_save(self) -> None:
"""Save settings and close."""
self.pop_screen() # Return to previous screen
def action_cancel(self) -> None:
"""Close without saving."""
self.pop_screen()Screen Stack:
push_screen()adds screen on top (modal behavior)pop_screen()removes top screenswitch_screen()replaces current screen- Screens can return values using
pop_screen(result)
Step 6: Implement Graceful Shutdown
Cleanup resources on application exit:
def on_unmount(self) -> None:
"""Handle application unmount/exit.
Called after widgets are unmounted but before app exits.
Use for cleanup: closing connections, saving state, etc.
"""
# Save state
if self._config:
self._config.save()
# Close connections
if self._connection:
self._connection.close()
# Cancel background tasks
# (Textual handles this automatically)
async def on_shutdown(self) -> None:
"""Called when application is shutting down.
This is async - use for async cleanup.
"""
# Close async connections
if self._async_client:
await self._async_client.close()Examples
Example 1: Dashboard with Auto-Refresh and Notifications
import asyncio
from textual.app import App, ComposeResult
from textual.binding import Binding
from textual.widgets import Header, Footer, Static, Container
from typing import ClassVar
class DashboardApp(App):
"""Dashboard that auto-refreshes data."""
TITLE = "Agent Dashboard"
BINDINGS: ClassVar[list[Binding]] = [
("q", "quit", "Quit"),
("r", "refresh", "Refresh"),
]
def __init__(self) -> None:
super().__init__()
self._data: dict | None = None
self._refresh_task_id: str | None = None
def compose(self) -> ComposeResult:
yield Header()
yield Container(
Static("Loading...", id="status"),
Static("", id="content"),
Static("", id="footer-info"),
)
yield Footer()
def on_mount(self) -> None:
"""Initialize dashboard on mount."""
# Start auto-refresh (every 3 seconds)
self.set_interval(3.0, self._silent_refresh)
# Initial load with notification
self.run_worker(self._refresh_with_notification())
async def _refresh_with_notification(self) -> None:
"""Refresh and show notification."""
try:
self._data = await self._fetch_data()
await self._update_display()
self.notify("Dashboard refreshed", severity="information")
except Exception as e:
self.notify(f"Refresh error: {e}", severity="error")
def _silent_refresh(self) -> None:
"""Auto-refresh without notification."""
self.run_worker(self._refresh_async())
async def _refresh_async(self) -> None:
"""Background refresh."""
try:
self._data = await self._fetch_data()
await self._update_display()
except Exception:
pass # Silent fail on background refresh
async def _fetch_data(self) -> dict:
"""Simulate fetching data from remote."""
await asyncio.sleep(0.5) # Simulate network delay
return {
"status": "running",
"agents": 3,
"cpu": 45.2,
"memory": 62.8,
}
async def _update_display(self) -> None:
"""Update display with current data."""
if not self._data:
return
status = self.query_one("#status", Static)
status.update(f"Status: {self._data['status']}")
content = self.query_one("#content", Static)
content.update(
f"Agents: {self._data['agents']}\n"
f"CPU: {self._data['cpu']:.1f}%\n"
f"Memory: {self._data['memory']:.1f}%"
)
def action_refresh(self) -> None:
"""Manual refresh action."""
self.run_worker(self._refresh_with_notification())
def on_unmount(self) -> None:
"""Cleanup on exit."""
# Textual automatically cancels timers and workers
pass
if __name__ == "__main__":
app = DashboardApp()
app.run()Example 2: Multi-Screen Application with Modal Dialog
from textual.app import App, ComposeResult
from textual.binding import Binding
from textual.containers import Container
from textual.screen import Screen
from textual.widgets import Header, Footer, Static, Button, Input
from typing import ClassVar
class MainScreen(Screen):
"""Main application screen."""
BINDINGS: ClassVar[list[Binding]] = [
("q", "quit", "Quit"),
("o", "open_dialog", "Open"),
]
def compose(self) -> ComposeResult:
yield Header()
yield Static("Main Screen", id="content")
yield Footer()
def action_open_dialog(self) -> None:
"""Open modal dialog."""
self.app.push_screen(ModalDialog())
class ModalDialog(Screen):
"""Modal dialog example."""
BINDINGS: ClassVar[list[Binding]] = [
("escape", "cancel", "Cancel"),
("enter", "confirm", "Confirm"),
]
CSS = """
ModalDialog {
align: center middle;
}
ModalDialog > Container {
width: 40;
height: 10;
border: solid $primary;
padding: 1;
}
"""
def compose(self) -> ComposeResult:
with Container():
yield Static("Dialog Title", id="dialog-title")
yield Input("Enter something:", id="dialog-input")
yield Button("OK", id="btn-ok")
yield Button("Cancel", id="btn-cancel")
def action_confirm(self) -> None:
"""Confirm and return data."""
input_field = self.query_one("#dialog-input", Input)
self.app.pop_screen(result=input_field.value)
def action_cancel(self) -> None:
"""Cancel without returning data."""
self.app.pop_screen()
class MultiScreenApp(App):
"""App with multiple screens."""
def compose(self) -> ComposeResult:
yield MainScreen()
if __name__ == "__main__":
app = MultiScreenApp()
app.run()Requirements
- Textual >= 0.45.0 (install with
pip install textual) - Python 3.9+ for type hints
- For syntax highlighting in TextArea:
pip install "textual[syntax]"
Common Pitfalls
1. Calling async functions synchronously:
# ❌ WRONG - can't await in sync context
def on_mount(self) -> None:
self._data = await self._fetch_data() # Error!
# ✅ CORRECT - use run_worker
def on_mount(self) -> None:
self.run_worker(self._load_data())2. Querying widgets before mount:
# ❌ WRONG - compose() runs before mount
def compose(self) -> ComposeResult:
yield Static("Test")
widget = self.query_one("#something") # Fails!
# ✅ CORRECT - query in on_mount or later
def on_mount(self) -> None:
widget = self.query_one("#something") # Works!3. Forgetting to set interval ID:
# ❌ Can't cancel later
self.set_interval(5.0, callback)
# ✅ Save ID if you need to cancel
self._timer_id = self.set_interval(5.0, callback)
# Later: self.remove_timer(self._timer_id)4. Not handling async errors in workers:
# ❌ Errors are silent
def on_mount(self) -> None:
self.run_worker(self._fetch_data())
# ✅ Handle errors
def on_mount(self) -> None:
self.run_worker(self._safe_fetch())
async def _safe_fetch(self) -> None:
try:
await self._fetch_data()
except Exception as e:
self.notify(f"Error: {e}", severity="error")See Also
- textual-event-messages.md - Event and message handling patterns
- textual-widget-development.md - Creating custom widgets
- textual-reactive-programming.md - Reactive attributes and watchers