Textual Framework Documentation
Textual is a Python framework for building terminal and web UIs by Textualize.io. See index.md for the landing page.
Tables below map topics to markdown files. Use the Read tool to load referenced files identified as relevant for full details.
Start with the most specific section: Widgets for widget docs, Styles for CSS properties,
Events for event handlers, API Reference for module-level API, Examples for runnable code.
Documents are cross-referenced: each page has a "See also" section linking to related pages.
CSS type pages have "Used by" sections listing all style properties that accept that type.
API stubs link to their corresponding guide pages for in-depth explanations.
In the Examples section, entries marked (+tcss) have a companion .tcss stylesheet.
Names that behave the opposite way from how they read
Measured on textual 8.2.8. Three of these four cost a real defect in one session, and none of them
announces itself - the code runs, and the wrong behaviour looks like a styling or data problem
somewhere else. Check them before debugging outward.
| Name |
What it reads as |
What it actually does |
App.display |
"the thing my app displays" |
display is DOMNode's show/hide PROPERTY. Assigning a settings object, a renderable or any model to self.display does not set content - it sets visibility, and rendering breaks in a way that points nowhere near the assignment. Name your own attribute anything else. |
Widget.check_action() |
one boolean: may this action run |
THREE-valued, and the two falsey answers differ: False HIDES the binding from the footer and the palette, None shows it GREYED OUT, True allows it. Returning False where you meant "visible but disabled" makes the key silently vanish from the UI. |
DataTable.add_column(width=N) |
a column that wraps or ellipsizes at N |
A HARD CLIP at N with no ellipsis. text-overflow never reaches the cell either, because cells render through Rich rather than through the CSS box - so the usual fix is inert and the text simply disappears at the boundary. Truncate in your own cell text if you want a marker. |
DataTable.RowHighlighted |
"my table's row changed" |
Fires for EVERY DataTable on screen, in composition order at mount, so a screen with two tables gets both handlers on startup before the user touches anything. Gate on event.data_table (or event.control) being the table you mean; an if on the row index will not do it. |
And the one that works exactly as documented, recorded because it is the natural thing to distrust
once the four above have burned you: overflow-x: auto resolves to virtual_size.width > width,
so a fixed-width scroll strip gates its own scrollbar correctly with no length comparison in user
code.
The vendored docs carry one local fix
widgets/progress_bar.md diverges from upstream by two lines, deliberately. Its reactive-attributes
table wrote the type as `float | None` with the pipe unescaped, so GFM split the cell there
and the DEFAULT column was consumed by the second half of the type - the table rendered with a
column's worth of content gone while still looking well formed. The pipes are now escaped and the
two Default cells restored to None, read off the installed library (textual 8.2.8) rather than
inferred, matching the progress row that was never broken.
Re-apply this if these files are ever re-synced from upstream. Every other vendored file is an
untouched mirror.
Getting Started
| Page |
Description |
| Getting Started |
Installation and first steps with Textual |
| Tutorial |
Step-by-step tutorial building a stopwatch application |
| FAQ |
Frequently asked questions |
| Help |
Getting help and reporting issues |
| Roadmap |
Project roadmap and planned features |
| Linux Console |
Notes on running Textual in the Linux console |
Guide
The Textual guide covers core concepts for building terminal applications. Each guide page links to related guides, widgets, styles, and events. See guide/index.md.
| Page |
Description |
| App Basics |
Creating and running Textual applications |
| Textual CSS |
Styling with Textual CSS, the DOM, and selectors |
| Actions |
Allow-listed functions with string syntax for links and key bindings |
| Animation |
Visual effects such as movement, blending, and fading |
| Command Palette |
Built-in command palette for quick access to app functionality |
| Content |
Specifying and formatting widget content |
| Themes |
Built-in themes and creating custom themes |
| Devtools |
Development tools for debugging Textual apps |
| Events and Messages |
Event handling and the message system |
| Input |
Responding to key presses and mouse actions |
| Layout |
Arranging widgets with vertical, horizontal, grid, and dock layouts |
| DOM Queries |
Finding and updating widgets using CSS selectors in Python |
| Reactivity |
Reactive attributes for simplified app state management |
| Screens |
Creating screens and switching between them |
| Styles |
Applying styles to create user interfaces |
| Testing |
Writing tests for Textual applications |
| Widgets |
Exploring widgets and creating custom widgets |
| Workers |
Concurrency and the Worker API |
Widgets
Reference documentation for all built-in widgets. Each widget page includes a "See also" section linking to related widgets, events, and guide pages. See widgets/index.md or the Widget Gallery for an overview.
| Page |
Description |
| Button |
A simple button with a variety of semantic styles |
| Checkbox |
A classic checkbox control |
| Collapsible |
Content that may be toggled on and off by clicking a title |
| ContentSwitcher |
A widget for containing and switching display between multiple child widgets |
| DataTable |
A powerful data table with configurable cursors |
| Digits |
Display numbers in tall characters |
| DirectoryTree |
A tree view of files and folders |
| Footer |
A footer to display and interact with key bindings |
| Header |
A header to display the app's title and subtitle |
| Input |
A control to enter text |
| Label |
A simple text label |
| Link |
A clickable link that opens a URL |
| ListItem |
An item within a ListView |
| ListView |
Display a list of items (items may be other widgets) |
| LoadingIndicator |
Display an animation while data is loading |
| Log |
Display and update lines of text (such as from a file) |
| Markdown |
Display a Markdown document |
| MarkdownViewer |
Display and interact with a Markdown document with navigation |
| MaskedInput |
A control to enter input according to a template mask |
| OptionList |
Display a vertical list of options |
| Placeholder |
Display placeholder content while designing a UI |
| Pretty |
Display a pretty-formatted Rich renderable |
| ProgressBar |
A configurable progress bar with ETA and percentage complete |
| RadioButton |
A simple radio button |
| RadioSet |
A collection of radio buttons that enforces uniqueness |
| RichLog |
Display and update text in a scrolling panel |
| Rule |
A rule widget to separate content, similar to an HTML <hr> tag |
| Select |
Select from a number of possible options |
| SelectionList |
Select multiple values from a list of options |
| Sparkline |
Display numerical data as a sparkline |
| Static |
Displays simple static content; typically used as a base class |
| Switch |
An on/off control, inspired by toggle buttons |
| TabbedContent |
A combination of Tabs and ContentSwitcher to navigate static content |
| Tabs |
A row of tabs you can select with the mouse or navigate with keys |
| TextArea |
A multi-line text area with syntax highlighting |
| Toast |
A notification message widget used by the built-in notify system |
| Tree |
A tree control with expandable nodes |
Styles
CSS styles for customizing appearance and layout. Each style page links to related properties and CSS types. See styles/index.md.
Subsections
| Section |
Description |
| Grid |
Grid layout properties |
| Links |
Link styling properties |
| Scrollbar Colors |
Scrollbar color properties |
Style Properties
| Page |
Description |
| Align |
Defines how a widget's children are aligned |
| Background |
Sets the background color of a widget |
| Background-tint |
Modifies the background color by tinting it with a new color |
| Border |
Enables the drawing of a box around a widget |
| Border-subtitle-align |
Sets the horizontal alignment for the border subtitle |
| Border-subtitle-background |
Sets the background color of the border subtitle |
| Border-subtitle-color |
Sets the color of the border subtitle |
| Border-subtitle-style |
Sets the text style of the border subtitle |
| Border-title-align |
Sets the horizontal alignment for the border title |
| Border-title-background |
Sets the background color of the border title |
| Border-title-color |
Sets the color of the border title |
| Border-title-style |
Sets the text style of the border title |
| Box-sizing |
Determines how the width and height of a widget are calculated |
| Color |
Sets the text color of a widget |
| Content-align |
Aligns content inside a widget |
| Display |
Defines whether a widget is displayed or not |
| Dock |
Fixes a widget to the edge of a container |
| Hatch |
Fills a widget's background with a repeating character pattern |
| Height |
Sets a widget's height |
| Keyline |
Draws lines around child widgets in a container |
| Layer |
Defines the layer a widget belongs to |
| Layers |
Defines an ordered set of layers |
| Layout |
Defines how a widget arranges its children |
| Margin |
Specifies spacing around a widget |
| Max-height |
Sets a maximum height for a widget |
| Max-width |
Sets a maximum width for a widget |
| Min-height |
Sets a minimum height for a widget |
| Min-width |
Sets a minimum width for a widget |
| Offset |
Defines an offset for the position of a widget |
| Opacity |
Sets the opacity of a widget |
| Outline |
Draws a box around the content area of a widget |
| Overflow |
Specifies if and when scrollbars should be displayed |
| Padding |
Specifies spacing around the content of a widget |
| Pointer |
Sets the shape of the mouse pointer when over a widget |
| Position |
Modifies what offset is applied to |
| Scrollbar-gutter |
Reserves space for a vertical scrollbar |
| Scrollbar-size |
Defines the width of scrollbars |
| Scrollbar-visibility |
Shows or hides scrollbars |
| Text-align |
Sets the text alignment in a widget |
| Text-opacity |
Blends the foreground color with the background color |
| Text-overflow |
Defines what happens when text overflows |
| Text-style |
Sets the style for the text in a widget |
| Text-wrap |
Sets how Textual should wrap text |
| Tint |
Blends a color with the whole widget |
| Visibility |
Determines whether a widget is visible or not |
| Width |
Sets a widget's width |
Grid Properties
| Page |
Description |
| Column-span |
Specifies how many columns a widget will span in a grid layout |
| Grid-columns |
Defines the width of the columns of the grid |
| Grid-gutter |
Sets the spacing between adjacent cells in the grid |
| Grid-rows |
Defines the height of the rows of the grid |
| Grid-size |
Sets the number of columns and rows in a grid layout |
| Row-span |
Specifies how many rows a widget will span in a grid layout |
Link Styles
| Page |
Description |
| Link-background |
Sets the background color of the link |
| Link-background-hover |
Sets the background color of the link when the cursor is over it |
| Link-color |
Sets the color of the link text |
| Link-color-hover |
Sets the color of the link text when the cursor is over it |
| Link-style |
Sets the text style for the link text |
| Link-style-hover |
Sets the text style for the link text when the cursor is over it |
Scrollbar Color Properties
| Page |
Description |
| Scrollbar-background |
Sets the background color of the scrollbar |
| Scrollbar-background-active |
Sets the scrollbar background color when the thumb is being dragged |
| Scrollbar-background-hover |
Sets the scrollbar background color when the cursor is over it |
| Scrollbar-color |
Sets the color of the scrollbar thumb |
| Scrollbar-color-active |
Sets the scrollbar thumb color when it is being dragged |
| Scrollbar-color-hover |
Sets the scrollbar thumb color when the cursor is over it |
| Scrollbar-corner-color |
Sets the color of the gap between horizontal and vertical scrollbars |
Events
Reference for all built-in events. Each event page links to complementary events, related widgets, and the events guide. See events/index.md or the Events guide.
| Page |
Description |
| AppBlur |
Sent when the application loses focus |
| AppFocus |
Sent when the application gains focus |
| Blur |
Sent when a widget loses focus |
| Click |
Sent when a widget is clicked |
| DescendantBlur |
Sent when a descendant widget loses focus |
| DescendantFocus |
Sent when a descendant widget gains focus |
| Enter |
Sent when the mouse enters a widget |
| Focus |
Sent when a widget gains focus |
| Hide |
Sent when a widget is hidden |
| Key |
Sent when a key is pressed |
| Leave |
Sent when the mouse leaves a widget |
| Load |
Sent when the application is loading |
| Mount |
Sent when a widget is mounted to the DOM |
| MouseCapture |
Sent when a widget captures the mouse |
| MouseDown |
Sent when a mouse button is pressed |
| MouseMove |
Sent when the mouse moves over a widget |
| MouseRelease |
Sent when a widget releases the mouse |
| MouseScrollDown |
Sent when the mouse scrolls down |
| MouseScrollLeft |
Sent when the mouse scrolls left |
| MouseScrollRight |
Sent when the mouse scrolls right |
| MouseScrollUp |
Sent when the mouse scrolls up |
| MouseUp |
Sent when a mouse button is released |
| Paste |
Sent when text is pasted into the terminal |
| Print |
Sent when the app receives a print request |
| Resize |
Sent when a widget is resized |
| ScreenResume |
Sent when a screen is resumed |
| ScreenSuspend |
Sent when a screen is suspended |
| Show |
Sent when a widget becomes visible |
| Unmount |
Sent when a widget is removed from the DOM |
CSS Types
CSS types define the values that Textual CSS styles accept. Each type page includes a "Used by" section listing all style properties that accept it. See css_types/index.md.
| Page |
Description |
|
Border style type - used by border, outline |
|
Color type - used by 23 style properties (background, color, tint, border colors, link colors, scrollbar colors) |
|
Hatch character type - used by hatch |
|
Horizontal position - used by align, content-align, border-title-align, border-subtitle-align |
|
Integer type - used by column-span, row-span, grid-size, grid-gutter, margin, padding, scrollbar-size |
|
Keyline style type - used by keyline |
|
Name identifier type - used by layer, layers |
|
Number type (int or decimal) - used by opacity, text-opacity |
|
Overflow mode type - used by overflow |
|
Percentage type - used by 22 style properties (color alphas, opacity, background, tint) |
|
Mouse cursor shape type - used by pointer |
|
Offset application mode - used by position |
|
Length type (number + unit or auto) - used by width, height, min/max dimensions, margin, padding, offset, grid-columns, grid-rows |
|
Text alignment type - used by text-align |
|
Text style type - used by text-style, border-title-style, border-subtitle-style, link-style, link-style-hover |
|
Vertical position - used by align, content-align |
API Reference
Module-level API reference. Each API stub links to its corresponding guide page for in-depth coverage. See api/index.md.
| Module |
Description |
| textual.app |
The App class and related utilities |
| textual.await_complete |
AwaitComplete for background work completion |
| textual.await_remove |
AwaitRemove for widget removal |
| textual.binding |
Key bindings |
| textual.cache |
Caching utilities |
| textual.color |
Color handling and manipulation |
| textual.command |
Command palette |
| textual.compose |
Compose utility |
| textual.constants |
Framework constants |
| textual.containers |
Layout containers |
| textual.content |
Content rendering |
| textual.coordinate |
Coordinate data type |
| textual.dom |
DOM node base class |
| textual.errors |
Exception classes |
| textual.events |
Event classes |
| textual.filter |
Display filters |
| textual.fuzzy |
Fuzzy matching |
| textual.geometry |
Geometry primitives |
| textual.getters |
Getter utilities |
| textual.highlight |
Syntax highlighting |
| textual.layout |
Layout engine |
| textual.lazy |
Lazy loading |
| textual (logger) |
Root logger |
| textual.logging |
Logging utilities |
| textual.map_geometry |
Map geometry data structure |
| textual.markup |
Markup processing |
| textual.message |
Message base class |
| textual.message_pump |
Message pump |
| textual.on |
The on decorator for event handling |
| textual.pilot |
Testing pilot |
| textual.css.query |
DOM query API |
| textual.reactive |
Reactive attributes |
| textual.renderables |
Rich renderables for widgets |
| textual.screen |
Screen class |
| textual.scroll_view |
Scroll view widget |
| textual.scrollbar |
Scrollbar widget |
| textual.signal |
Signal for pub/sub messaging |
| textual.strip |
Strip rendering |
| textual.style |
Style data type |
| textual.suggester |
Input suggestion |
| textual.system_commands |
System commands |
| textual.timer |
Timer utilities |
| textual.types |
Type exports |
| textual.validation |
Input validation |
| textual.walk |
DOM tree walking |
| textual.widget |
Widget base class |
| textual.work |
Work decorator |
| textual.worker |
Worker class |
| textual.worker_manager |
Worker manager |
How-To Guides
Practical articles covering various Textual topics. Each guide links to relevant reference pages and guide sections. See how-to/index.md.
| Guide |
Description |
| Center Things |
Different ways to center widgets, text, and content |
| Design a Layout |
Tips for designing your application layout from scratch |
| Package with Hatch |
How to package and publish a Textual app using Hatch |
| Render and Compose |
Understanding the difference between render() and compose() |
| Style Inline Apps |
Customizing the appearance of inline-mode apps |
| Work with Containers |
Using container widgets to arrange layout |
Examples
310 example programs (companion .tcss stylesheets folded in via the (+tcss) marker). Files marked (+tcss) have a companion .tcss stylesheet with the same base name.
App
| File |
Description |
| event01.py |
Demonstrates changing screen background color on key press events |
| question01.py |
Simple yes/no question app returning button press result |
| question02.py |
Question app with external TCSS stylesheet for grid layout (+tcss) |
| question03.py |
Question app with inline CSS grid layout styling |
| question_title01.py |
Question app with Header widget, title, and subtitle |
| question_title02.py |
Question app updating title and subtitle on key events |
| simple01.py |
Minimal empty Textual App subclass definition |
| simple02.py |
Minimal Textual app with run entry point |
| suspend.py |
Demonstrates suspending the app to run an external editor |
| suspend_process.py |
Demonstrates Ctrl+Z key binding to suspend the process |
| widgets01.py |
Welcome widget app that exits on button press |
| widgets02.py |
Mounts Welcome widget dynamically on any key press |
| widgets03.py |
Dynamically mounts Welcome widget and changes button label |
| widgets04.py |
Async mount of Welcome widget with button label update |
Events
| File |
Description |
| custom01.py |
Custom message event with ColorButton posting Selected messages |
| [dictionary.py](e |
|
…(truncated)
1---2name: coding-python-textual3description: Use when building terminal or web UIs in Python with Textual - App, compose(), widgets (DataTable, Button, Input, Tree), reactive attributes, Textual CSS (TCSS) styling, screens, workers, events, or testing with Pilot.4---56# Textual Framework Documentation78Textual is a Python framework for building terminal and web UIs by [Textualize.io](https://www.textualize.io). See [index.md](index.md) for the landing page.910Tables below map topics to markdown files. Use the Read tool to load referenced files identified as relevant for full details.11Start with the most specific section: Widgets for widget docs, Styles for CSS properties,12Events for event handlers, API Reference for module-level API, Examples for runnable code.13Documents are cross-referenced: each page has a "See also" section linking to related pages.14CSS type pages have "Used by" sections listing all style properties that accept that type.15API stubs link to their corresponding guide pages for in-depth explanations.16In the Examples section, entries marked (+tcss) have a companion .tcss stylesheet.1718---1920## Names that behave the opposite way from how they read2122Measured on textual 8.2.8. Three of these four cost a real defect in one session, and none of them23announces itself - the code runs, and the wrong behaviour looks like a styling or data problem24somewhere else. Check them before debugging outward.2526| Name | What it reads as | What it actually does |27|---------------------------------|----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|28| `App.display` | "the thing my app displays" | `display` is `DOMNode`'s show/hide PROPERTY. Assigning a settings object, a renderable or any model to `self.display` does not set content - it sets visibility, and rendering breaks in a way that points nowhere near the assignment. Name your own attribute anything else. |29| `Widget.check_action()` | one boolean: may this action run | THREE-valued, and the two falsey answers differ: `False` HIDES the binding from the footer and the palette, `None` shows it GREYED OUT, `True` allows it. Returning `False` where you meant "visible but disabled" makes the key silently vanish from the UI. |30| `DataTable.add_column(width=N)` | a column that wraps or ellipsizes at N | A HARD CLIP at N with no ellipsis. `text-overflow` never reaches the cell either, because cells render through Rich rather than through the CSS box - so the usual fix is inert and the text simply disappears at the boundary. Truncate in your own cell text if you want a marker. |31| `DataTable.RowHighlighted` | "my table's row changed" | Fires for EVERY `DataTable` on screen, in composition order at mount, so a screen with two tables gets both handlers on startup before the user touches anything. Gate on `event.data_table` (or `event.control`) being the table you mean; an `if` on the row index will not do it. |3233And the one that works exactly as documented, recorded because it is the natural thing to distrust34once the four above have burned you: `overflow-x: auto` resolves to `virtual_size.width > width`,35so a fixed-width scroll strip gates its own scrollbar correctly with no length comparison in user36code.3738### The vendored docs carry one local fix3940`widgets/progress_bar.md` diverges from upstream by two lines, deliberately. Its reactive-attributes41table wrote the type as `` `float | None` `` with the pipe unescaped, so GFM split the cell there42and the DEFAULT column was consumed by the second half of the type - the table rendered with a43column's worth of content gone while still looking well formed. The pipes are now escaped and the44two Default cells restored to `None`, read off the installed library (textual 8.2.8) rather than45inferred, matching the `progress` row that was never broken.4647Re-apply this if these files are ever re-synced from upstream. Every other vendored file is an48untouched mirror.4950---5152## Getting Started5354| Page | Description |55|---------------------------------------|--------------------------------------------------------|56| [Getting Started](getting_started.md) | Installation and first steps with Textual |57| [Tutorial](tutorial.md) | Step-by-step tutorial building a stopwatch application |58| [FAQ](FAQ.md) | Frequently asked questions |59| [Help](help.md) | Getting help and reporting issues |60| [Roadmap](roadmap.md) | Project roadmap and planned features |61| [Linux Console](linux-console.md) | Notes on running Textual in the Linux console |6263---6465## Guide6667The Textual guide covers core concepts for building terminal applications. Each guide page links to related guides, widgets, styles, and events. See [guide/index.md](guide/index.md).6869| Page | Description |70|---------------------------------------------|----------------------------------------------------------------------|71| [App Basics](guide/app.md) | Creating and running Textual applications |72| [Textual CSS](guide/CSS.md) | Styling with Textual CSS, the DOM, and selectors |73| [Actions](guide/actions.md) | Allow-listed functions with string syntax for links and key bindings |74| [Animation](guide/animation.md) | Visual effects such as movement, blending, and fading |75| [Command Palette](guide/command_palette.md) | Built-in command palette for quick access to app functionality |76| [Content](guide/content.md) | Specifying and formatting widget content |77| [Themes](guide/design.md) | Built-in themes and creating custom themes |78| [Devtools](guide/devtools.md) | Development tools for debugging Textual apps |79| [Events and Messages](guide/events.md) | Event handling and the message system |80| [Input](guide/input.md) | Responding to key presses and mouse actions |81| [Layout](guide/layout.md) | Arranging widgets with vertical, horizontal, grid, and dock layouts |82| [DOM Queries](guide/queries.md) | Finding and updating widgets using CSS selectors in Python |83| [Reactivity](guide/reactivity.md) | Reactive attributes for simplified app state management |84| [Screens](guide/screens.md) | Creating screens and switching between them |85| [Styles](guide/styles.md) | Applying styles to create user interfaces |86| [Testing](guide/testing.md) | Writing tests for Textual applications |87| [Widgets](guide/widgets.md) | Exploring widgets and creating custom widgets |88| [Workers](guide/workers.md) | Concurrency and the Worker API |8990---9192## Widgets9394Reference documentation for all built-in widgets. Each widget page includes a "See also" section linking to related widgets, events, and guide pages. See [widgets/index.md](widgets/index.md) or the [Widget Gallery](widget_gallery.md) for an overview.9596| Page | Description |97|--------------------------------------------------|------------------------------------------------------------------------------|98| [Button](widgets/button.md) | A simple button with a variety of semantic styles |99| [Checkbox](widgets/checkbox.md) | A classic checkbox control |100| [Collapsible](widgets/collapsible.md) | Content that may be toggled on and off by clicking a title |101| [ContentSwitcher](widgets/content_switcher.md) | A widget for containing and switching display between multiple child widgets |102| [DataTable](widgets/data_table.md) | A powerful data table with configurable cursors |103| [Digits](widgets/digits.md) | Display numbers in tall characters |104| [DirectoryTree](widgets/directory_tree.md) | A tree view of files and folders |105| [Footer](widgets/footer.md) | A footer to display and interact with key bindings |106| [Header](widgets/header.md) | A header to display the app's title and subtitle |107| [Input](widgets/input.md) | A control to enter text |108| [Label](widgets/label.md) | A simple text label |109| [Link](widgets/link.md) | A clickable link that opens a URL |110| [ListItem](widgets/list_item.md) | An item within a ListView |111| [ListView](widgets/list_view.md) | Display a list of items (items may be other widgets) |112| [LoadingIndicator](widgets/loading_indicator.md) | Display an animation while data is loading |113| [Log](widgets/log.md) | Display and update lines of text (such as from a file) |114| [Markdown](widgets/markdown.md) | Display a Markdown document |115| [MarkdownViewer](widgets/markdown_viewer.md) | Display and interact with a Markdown document with navigation |116| [MaskedInput](widgets/masked_input.md) | A control to enter input according to a template mask |117| [OptionList](widgets/option_list.md) | Display a vertical list of options |118| [Placeholder](widgets/placeholder.md) | Display placeholder content while designing a UI |119| [Pretty](widgets/pretty.md) | Display a pretty-formatted Rich renderable |120| [ProgressBar](widgets/progress_bar.md) | A configurable progress bar with ETA and percentage complete |121| [RadioButton](widgets/radiobutton.md) | A simple radio button |122| [RadioSet](widgets/radioset.md) | A collection of radio buttons that enforces uniqueness |123| [RichLog](widgets/rich_log.md) | Display and update text in a scrolling panel |124| [Rule](widgets/rule.md) | A rule widget to separate content, similar to an HTML `<hr>` tag |125| [Select](widgets/select.md) | Select from a number of possible options |126| [SelectionList](widgets/selection_list.md) | Select multiple values from a list of options |127| [Sparkline](widgets/sparkline.md) | Display numerical data as a sparkline |128| [Static](widgets/static.md) | Displays simple static content; typically used as a base class |129| [Switch](widgets/switch.md) | An on/off control, inspired by toggle buttons |130| [TabbedContent](widgets/tabbed_content.md) | A combination of Tabs and ContentSwitcher to navigate static content |131| [Tabs](widgets/tabs.md) | A row of tabs you can select with the mouse or navigate with keys |132| [TextArea](widgets/text_area.md) | A multi-line text area with syntax highlighting |133| [Toast](widgets/toast.md) | A notification message widget used by the built-in notify system |134| [Tree](widgets/tree.md) | A tree control with expandable nodes |135136---137138## Styles139140CSS styles for customizing appearance and layout. Each style page links to related properties and CSS types. See [styles/index.md](styles/index.md).141142### Subsections143144| Section | Description |145|------------------------------------------------------|----------------------------|146| [Grid](styles/grid/index.md) | Grid layout properties |147| [Links](styles/links/index.md) | Link styling properties |148| [Scrollbar Colors](styles/scrollbar_colors/index.md) | Scrollbar color properties |149150### Style Properties151152| Page | Description |153|--------------------------------------------------------------------|----------------------------------------------------------------|154| [Align](styles/align.md) | Defines how a widget's children are aligned |155| [Background](styles/background.md) | Sets the background color of a widget |156| [Background-tint](styles/background_tint.md) | Modifies the background color by tinting it with a new color |157| [Border](styles/border.md) | Enables the drawing of a box around a widget |158| [Border-subtitle-align](styles/border_subtitle_align.md) | Sets the horizontal alignment for the border subtitle |159| [Border-subtitle-background](styles/border_subtitle_background.md) | Sets the background color of the border subtitle |160| [Border-subtitle-color](styles/border_subtitle_color.md) | Sets the color of the border subtitle |161| [Border-subtitle-style](styles/border_subtitle_style.md) | Sets the text style of the border subtitle |162| [Border-title-align](styles/border_title_align.md) | Sets the horizontal alignment for the border title |163| [Border-title-background](styles/border_title_background.md) | Sets the background color of the border title |164| [Border-title-color](styles/border_title_color.md) | Sets the color of the border title |165| [Border-title-style](styles/border_title_style.md) | Sets the text style of the border title |166| [Box-sizing](styles/box_sizing.md) | Determines how the width and height of a widget are calculated |167| [Color](styles/color.md) | Sets the text color of a widget |168| [Content-align](styles/content_align.md) | Aligns content inside a widget |169| [Display](styles/display.md) | Defines whether a widget is displayed or not |170| [Dock](styles/dock.md) | Fixes a widget to the edge of a container |171| [Hatch](styles/hatch.md) | Fills a widget's background with a repeating character pattern |172| [Height](styles/height.md) | Sets a widget's height |173| [Keyline](styles/keyline.md) | Draws lines around child widgets in a container |174| [Layer](styles/layer.md) | Defines the layer a widget belongs to |175| [Layers](styles/layers.md) | Defines an ordered set of layers |176| [Layout](styles/layout.md) | Defines how a widget arranges its children |177| [Margin](styles/margin.md) | Specifies spacing around a widget |178| [Max-height](styles/max_height.md) | Sets a maximum height for a widget |179| [Max-width](styles/max_width.md) | Sets a maximum width for a widget |180| [Min-height](styles/min_height.md) | Sets a minimum height for a widget |181| [Min-width](styles/min_width.md) | Sets a minimum width for a widget |182| [Offset](styles/offset.md) | Defines an offset for the position of a widget |183| [Opacity](styles/opacity.md) | Sets the opacity of a widget |184| [Outline](styles/outline.md) | Draws a box around the content area of a widget |185| [Overflow](styles/overflow.md) | Specifies if and when scrollbars should be displayed |186| [Padding](styles/padding.md) | Specifies spacing around the content of a widget |187| [Pointer](styles/pointer.md) | Sets the shape of the mouse pointer when over a widget |188| [Position](styles/position.md) | Modifies what offset is applied to |189| [Scrollbar-gutter](styles/scrollbar_gutter.md) | Reserves space for a vertical scrollbar |190| [Scrollbar-size](styles/scrollbar_size.md) | Defines the width of scrollbars |191| [Scrollbar-visibility](styles/scrollbar_visibility.md) | Shows or hides scrollbars |192| [Text-align](styles/text_align.md) | Sets the text alignment in a widget |193| [Text-opacity](styles/text_opacity.md) | Blends the foreground color with the background color |194| [Text-overflow](styles/text_overflow.md) | Defines what happens when text overflows |195| [Text-style](styles/text_style.md) | Sets the style for the text in a widget |196| [Text-wrap](styles/text_wrap.md) | Sets how Textual should wrap text |197| [Tint](styles/tint.md) | Blends a color with the whole widget |198| [Visibility](styles/visibility.md) | Determines whether a widget is visible or not |199| [Width](styles/width.md) | Sets a widget's width |200201### Grid Properties202203| Page | Description |204|---------------------------------------------|----------------------------------------------------------------|205| [Column-span](styles/grid/column_span.md) | Specifies how many columns a widget will span in a grid layout |206| [Grid-columns](styles/grid/grid_columns.md) | Defines the width of the columns of the grid |207| [Grid-gutter](styles/grid/grid_gutter.md) | Sets the spacing between adjacent cells in the grid |208| [Grid-rows](styles/grid/grid_rows.md) | Defines the height of the rows of the grid |209| [Grid-size](styles/grid/grid_size.md) | Sets the number of columns and rows in a grid layout |210| [Row-span](styles/grid/row_span.md) | Specifies how many rows a widget will span in a grid layout |211212### Link Styles213214| Page | Description |215|----------------------------------------------------------------|------------------------------------------------------------------|216| [Link-background](styles/links/link_background.md) | Sets the background color of the link |217| [Link-background-hover](styles/links/link_background_hover.md) | Sets the background color of the link when the cursor is over it |218| [Link-color](styles/links/link_color.md) | Sets the color of the link text |219| [Link-color-hover](styles/links/link_color_hover.md) | Sets the color of the link text when the cursor is over it |220| [Link-style](styles/links/link_style.md) | Sets the text style for the link text |221| [Link-style-hover](styles/links/link_style_hover.md) | Sets the text style for the link text when the cursor is over it |222223### Scrollbar Color Properties224225| Page | Description |226|---------------------------------------------------------------------------------------|----------------------------------------------------------------------|227| [Scrollbar-background](styles/scrollbar_colors/scrollbar_background.md) | Sets the background color of the scrollbar |228| [Scrollbar-background-active](styles/scrollbar_colors/scrollbar_background_active.md) | Sets the scrollbar background color when the thumb is being dragged |229| [Scrollbar-background-hover](styles/scrollbar_colors/scrollbar_background_hover.md) | Sets the scrollbar background color when the cursor is over it |230| [Scrollbar-color](styles/scrollbar_colors/scrollbar_color.md) | Sets the color of the scrollbar thumb |231| [Scrollbar-color-active](styles/scrollbar_colors/scrollbar_color_active.md) | Sets the scrollbar thumb color when it is being dragged |232| [Scrollbar-color-hover](styles/scrollbar_colors/scrollbar_color_hover.md) | Sets the scrollbar thumb color when the cursor is over it |233| [Scrollbar-corner-color](styles/scrollbar_colors/scrollbar_corner_color.md) | Sets the color of the gap between horizontal and vertical scrollbars |234235---236237## Events238239Reference for all built-in events. Each event page links to complementary events, related widgets, and the events guide. See [events/index.md](events/index.md) or the [Events guide](guide/events.md).240241| Page | Description |242|--------------------------------------------------|--------------------------------------------|243| [AppBlur](events/app_blur.md) | Sent when the application loses focus |244| [AppFocus](events/app_focus.md) | Sent when the application gains focus |245| [Blur](events/blur.md) | Sent when a widget loses focus |246| [Click](events/click.md) | Sent when a widget is clicked |247| [DescendantBlur](events/descendant_blur.md) | Sent when a descendant widget loses focus |248| [DescendantFocus](events/descendant_focus.md) | Sent when a descendant widget gains focus |249| [Enter](events/enter.md) | Sent when the mouse enters a widget |250| [Focus](events/focus.md) | Sent when a widget gains focus |251| [Hide](events/hide.md) | Sent when a widget is hidden |252| [Key](events/key.md) | Sent when a key is pressed |253| [Leave](events/leave.md) | Sent when the mouse leaves a widget |254| [Load](events/load.md) | Sent when the application is loading |255| [Mount](events/mount.md) | Sent when a widget is mounted to the DOM |256| [MouseCapture](events/mouse_capture.md) | Sent when a widget captures the mouse |257| [MouseDown](events/mouse_down.md) | Sent when a mouse button is pressed |258| [MouseMove](events/mouse_move.md) | Sent when the mouse moves over a widget |259| [MouseRelease](events/mouse_release.md) | Sent when a widget releases the mouse |260| [MouseScrollDown](events/mouse_scroll_down.md) | Sent when the mouse scrolls down |261| [MouseScrollLeft](events/mouse_scroll_left.md) | Sent when the mouse scrolls left |262| [MouseScrollRight](events/mouse_scroll_right.md) | Sent when the mouse scrolls right |263| [MouseScrollUp](events/mouse_scroll_up.md) | Sent when the mouse scrolls up |264| [MouseUp](events/mouse_up.md) | Sent when a mouse button is released |265| [Paste](events/paste.md) | Sent when text is pasted into the terminal |266| [Print](events/print.md) | Sent when the app receives a print request |267| [Resize](events/resize.md) | Sent when a widget is resized |268| [ScreenResume](events/screen_resume.md) | Sent when a screen is resumed |269| [ScreenSuspend](events/screen_suspend.md) | Sent when a screen is suspended |270| [Show](events/show.md) | Sent when a widget becomes visible |271| [Unmount](events/unmount.md) | Sent when a widget is removed from the DOM |272273---274275## CSS Types276277CSS types define the values that Textual CSS styles accept. Each type page includes a "Used by" section listing all style properties that accept it. See [css_types/index.md](css_types/index.md).278279| Page | Description |280|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|281| [<border>](css_types/border.md) | Border style type - used by border, outline |282| [<color>](css_types/color.md) | Color type - used by 23 style properties (background, color, tint, border colors, link colors, scrollbar colors) |283| [<hatch>](css_types/hatch.md) | Hatch character type - used by hatch |284| [<horizontal>](css_types/horizontal.md) | Horizontal position - used by align, content-align, border-title-align, border-subtitle-align |285| [<integer>](css_types/integer.md) | Integer type - used by column-span, row-span, grid-size, grid-gutter, margin, padding, scrollbar-size |286| [<keyline>](css_types/keyline.md) | Keyline style type - used by keyline |287| [<name>](css_types/name.md) | Name identifier type - used by layer, layers |288| [<number>](css_types/number.md) | Number type (int or decimal) - used by opacity, text-opacity |289| [<overflow>](css_types/overflow.md) | Overflow mode type - used by overflow |290| [<percentage>](css_types/percentage.md) | Percentage type - used by 22 style properties (color alphas, opacity, background, tint) |291| [<pointer>](css_types/pointer.md) | Mouse cursor shape type - used by pointer |292| [<position>](css_types/position.md) | Offset application mode - used by position |293| [<scalar>](css_types/scalar.md) | Length type (number + unit or auto) - used by width, height, min/max dimensions, margin, padding, offset, grid-columns, grid-rows |294| [<text-align>](css_types/text_align.md) | Text alignment type - used by text-align |295| [<text-style>](css_types/text_style.md) | Text style type - used by text-style, border-title-style, border-subtitle-style, link-style, link-style-hover |296| [<vertical>](css_types/vertical.md) | Vertical position - used by align, content-align |297298---299300## API Reference301302Module-level API reference. Each API stub links to its corresponding guide page for in-depth coverage. See [api/index.md](api/index.md).303304| Module | Description |305|----------------------------------------------------------|----------------------------------------------|306| [textual.app](api/app.md) | The App class and related utilities |307| [textual.await_complete](api/await_complete.md) | AwaitComplete for background work completion |308| [textual.await_remove](api/await_remove.md) | AwaitRemove for widget removal |309| [textual.binding](api/binding.md) | Key bindings |310| [textual.cache](api/cache.md) | Caching utilities |311| [textual.color](api/color.md) | Color handling and manipulation |312| [textual.command](api/command.md) | Command palette |313| [textual.compose](api/compose.md) | Compose utility |314| [textual.constants](api/constants.md) | Framework constants |315| [textual.containers](api/containers.md) | Layout containers |316| [textual.content](api/content.md) | Content rendering |317| [textual.coordinate](api/coordinate.md) | Coordinate data type |318| [textual.dom](api/dom_node.md) | DOM node base class |319| [textual.errors](api/errors.md) | Exception classes |320| [textual.events](api/events.md) | Event classes |321| [textual.filter](api/filter.md) | Display filters |322| [textual.fuzzy](api/fuzzy_matcher.md) | Fuzzy matching |323| [textual.geometry](api/geometry.md) | Geometry primitives |324| [textual.getters](api/getters.md) | Getter utilities |325| [textual.highlight](api/highlight.md) | Syntax highlighting |326| [textual.layout](api/layout.md) | Layout engine |327| [textual.lazy](api/lazy.md) | Lazy loading |328| [textual (logger)](api/logger.md) | Root logger |329| [textual.logging](api/logging.md) | Logging utilities |330| [textual.map_geometry](api/map_geometry.md) | Map geometry data structure |331| [textual.markup](api/markup.md) | Markup processing |332| [textual.message](api/message.md) | Message base class |333| [textual.message_pump](api/message_pump.md) | Message pump |334| [textual.on](api/on.md) | The on decorator for event handling |335| [textual.pilot](api/pilot.md) | Testing pilot |336| [textual.css.query](api/query.md) | DOM query API |337| [textual.reactive](api/reactive.md) | Reactive attributes |338| [textual.renderables](api/renderables.md) | Rich renderables for widgets |339| [textual.screen](api/screen.md) | Screen class |340| [textual.scroll_view](api/scroll_view.md) | Scroll view widget |341| [textual.scrollbar](api/scrollbar.md) | Scrollbar widget |342| [textual.signal](api/signal.md) | Signal for pub/sub messaging |343| [textual.strip](api/strip.md) | Strip rendering |344| [textual.style](api/style.md) | Style data type |345| [textual.suggester](api/suggester.md) | Input suggestion |346| [textual.system_commands](api/system_commands_source.md) | System commands |347| [textual.timer](api/timer.md) | Timer utilities |348| [textual.types](api/types.md) | Type exports |349| [textual.validation](api/validation.md) | Input validation |350| [textual.walk](api/walk.md) | DOM tree walking |351| [textual.widget](api/widget.md) | Widget base class |352| [textual.work](api/work.md) | Work decorator |353| [textual.worker](api/worker.md) | Worker class |354| [textual.worker_manager](api/worker_manager.md) | Worker manager |355356---357358## How-To Guides359360Practical articles covering various Textual topics. Each guide links to relevant reference pages and guide sections. See [how-to/index.md](how-to/index.md).361362| Guide | Description |363|--------------------------------------------------------|-------------------------------------------------------------|364| [Center Things](how-to/center-things.md) | Different ways to center widgets, text, and content |365| [Design a Layout](how-to/design-a-layout.md) | Tips for designing your application layout from scratch |366| [Package with Hatch](how-to/package-with-hatch.md) | How to package and publish a Textual app using Hatch |367| [Render and Compose](how-to/render-and-compose.md) | Understanding the difference between render() and compose() |368| [Style Inline Apps](how-to/style-inline-apps.md) | Customizing the appearance of inline-mode apps |369| [Work with Containers](how-to/work-with-containers.md) | Using container widgets to arrange layout |370371---372373## Examples374375310 example programs (companion `.tcss` stylesheets folded in via the *(+tcss)* marker). Files marked *(+tcss)* have a companion `.tcss` stylesheet with the same base name.376377### App378379| File | Description |380|---------------------------------------------------------|----------------------------------------------------------------------|381| [event01.py](examples/app/event01.py) | Demonstrates changing screen background color on key press events |382| [question01.py](examples/app/question01.py) | Simple yes/no question app returning button press result |383| [question02.py](examples/app/question02.py) | Question app with external TCSS stylesheet for grid layout *(+tcss)* |384| [question03.py](examples/app/question03.py) | Question app with inline CSS grid layout styling |385| [question_title01.py](examples/app/question_title01.py) | Question app with Header widget, title, and subtitle |386| [question_title02.py](examples/app/question_title02.py) | Question app updating title and subtitle on key events |387| [simple01.py](examples/app/simple01.py) | Minimal empty Textual App subclass definition |388| [simple02.py](examples/app/simple02.py) | Minimal Textual app with run entry point |389| [suspend.py](examples/app/suspend.py) | Demonstrates suspending the app to run an external editor |390| [suspend_process.py](examples/app/suspend_process.py) | Demonstrates Ctrl+Z key binding to suspend the process |391| [widgets01.py](examples/app/widgets01.py) | Welcome widget app that exits on button press |392| [widgets02.py](examples/app/widgets02.py) | Mounts Welcome widget dynamically on any key press |393| [widgets03.py](examples/app/widgets03.py) | Dynamically mounts Welcome widget and changes button label |394| [widgets04.py](examples/app/widgets04.py) | Async mount of Welcome widget with button label update |395396### Events397398| File | Description |399|--------------------------------------------------------|----------------------------------------------------------------------|400| [custom01.py](examples/events/custom01.py) | Custom message event with ColorButton posting Selected messages |401| [dictionary.py](e402403…(truncated)
bitranox