0
# Textual
1

2
A comprehensive Python framework for building modern Text User Interface (TUI) applications that work both in terminals and web browsers. Textual provides a complete widget ecosystem, CSS-like styling, event-driven programming, and deployment flexibility for creating professional interactive applications across platforms.
3

4
## Package Information
5

6
- **Package Name**: textual
7
- **Language**: Python
8
- **Installation**: `pip install textual`
9

10
## Core Imports
11

12
```python
13
from textual.app import App
14
from textual.widget import Widget
15
from textual.screen import Screen
16
```
17

18
Common widget imports:
19

20
```python
21
from textual.widgets import Button, Input, Static
22
from textual.containers import Container, ScrollableContainer
23
```
24

25
Event handling and utilities:
26

27
```python
28
from textual import on, log
29
from textual.reactive import Reactive
30
```
31

32
## Basic Usage
33

34
```python
35
from textual.app import App
36
from textual.containers import Container
37
from textual.widgets import Button, Static
38

39
class BasicApp(App):
40
    """A basic Textual application."""
41
    
42
    def compose(self):
43
        """Compose the UI."""
44
        yield Container(
45
            Static("Hello, Textual!"),
46
            Button("Click me!", id="click-btn"),
47
            Button("Exit", id="exit-btn")
48
        )
49
    
50
    def on_button_pressed(self, event: Button.Pressed):
51
        """Handle button presses."""
52
        if event.button.id == "exit-btn":
53
            self.exit()
54
        elif event.button.id == "click-btn":
55
            self.log("Button was clicked!")
56

57
if __name__ == "__main__":
58
    app = BasicApp()
59
    app.run()
60
```
61

62
## Architecture
63

64
Textual uses a component-based architecture with several key concepts:
65

66
- **App**: The main application class that manages screens, styling, and execution
67
- **Screen**: A full-screen view that can contain widgets (like pages in a web app)
68
- **Widget**: Individual UI components that can be composed together
69
- **DOM**: Widget hierarchy with CSS-like querying and styling
70
- **Events**: Message-driven system for handling user interactions and system events
71
- **Reactive**: Automatic UI updates when data changes
72
- **CSS**: Familiar styling system with layout algorithms
73

74
This design enables building complex applications from reusable components while maintaining familiar web-like development patterns adapted for terminal interfaces.
75

76
## Capabilities
77

78
### Core Framework
79

80
Essential application framework classes and decorators for building Textual applications, including the main App class, base Widget class, screen management, and event handling decorators.
81

82
```python { .api }
83
__version__: str  # Package version string
84

85
class App:
86
    def run(self) -> None: ...
87
    def push_screen(self, screen: Screen) -> None: ...
88
    def pop_screen(self) -> Screen: ...
89
    def exit(self, result=None) -> None: ...
90

91
class Widget:
92
    def compose(self) -> ComposeResult: ...
93
    def render(self) -> RenderableType: ...
94
    def on_mount(self) -> None: ...
95

96
def on(*selectors, **kwargs): ...
97
def work(exclusive=False, thread=False): ...
98
```
99

100
[Core Framework](./core-framework.md)
101

102
### Widget Library
103

104
Complete collection of built-in UI components including input controls (Button, Input, TextArea), display widgets (Static, Label, DataTable), navigation components (Tabs, Tree), and utility widgets (ProgressBar, LoadingIndicator).
105

106
```python { .api }
107
class Button(Widget):
108
    def __init__(self, label, *, variant="default", disabled=False, **kwargs): ...
109

110
class Input(Widget):
111
    def __init__(self, value="", placeholder="", **kwargs): ...
112

113
class DataTable(Widget):
114
    def add_column(self, key, *, label=None, **kwargs): ...
115
    def add_row(self, *cells, **kwargs): ...
116

117
class Static(Widget):
118
    def __init__(self, renderable="", **kwargs): ...
119
```
120

121
[Widget Library](./widgets.md)
122

123
### Event System
124

125
Comprehensive event handling system for user interactions, widget lifecycle, and system events, including keyboard input, mouse interactions, focus management, and custom message passing.
126

127
```python { .api }
128
class Event:
129
    def prevent_default(self) -> None: ...
130
    def stop(self) -> None: ...
131

132
class Key(Event):
133
    key: str
134
    character: str | None
135

136
class Mouse(Event):
137
    x: int
138
    y: int
139
    button: int
140

141
class Message:
142
    def __init__(self) -> None: ...
143
```
144

145
[Event System](./events.md)
146

147
### Styling and Layout
148

149
CSS-like styling system with layout algorithms, reactive properties for automatic UI updates, color management, and geometric utilities for precise UI positioning and sizing.
150

151
```python { .api }
152
class Styles:
153
    def __init__(self): ...
154
    def __setattr__(self, name: str, value: Any): ...
155

156
def reactive(default=None, *, layout=False, repaint=True): ...
157

158
class Color:
159
    def __init__(self, r: int, g: int, b: int, a: float = 1.0): ...
160
    
161
class Size:
162
    def __init__(self, width: int, height: int): ...
163
```
164

165
[Styling and Layout](./styling.md)
166

167
### Content and Rendering
168

169
Rich content system for displaying formatted text, custom renderables for specialized visualizations, and content processing utilities for handling complex text layouts and styling.
170

171
```python { .api }
172
class Content:
173
    def __init__(self, text: str = "", spans=None): ...
174

175
class Strip:
176
    def __init__(self): ...
177
    def render(self, console, options): ...
178

179
def walk_children(node: DOMNode, *, reverse=False): ...
180
def walk_depth_first(root: DOMNode): ...
181
```
182

183
[Content and Rendering](./content.md)
184

185
### Testing and Development
186

187
Programmatic testing framework with the Pilot class for automated UI testing, command palette system for built-in development tools, and logging utilities for debugging applications.
188

189
```python { .api }
190
class Pilot:
191
    def __init__(self, app: App): ...
192
    async def press(self, *keys: str): ...
193
    async def click(self, selector: str = None): ...
194

195
class CommandPalette(Widget):
196
    def __init__(self): ...
197

198
def log(*args, **kwargs): ...
199
```
200

201
[Testing and Development](./testing.md)
202

203
## Types
204

205
```python { .api }
206
from typing import Union, Iterator, Any
207
from rich.console import RenderableType
208

209
ComposeResult = Iterator[Widget]
210
MessageTarget = Union[Widget, Screen, App]
211
CSSPathType = Union[str, list[str]]
212
```