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.
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
Example source code referenced throughout these docs (317 entries). 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 |
Dictionary lookup app searching an API as you type (+tcss) |
| on_decorator.tcss |
Centers buttons horizontally with margin spacing |
| on_decorator01.py |
Handles multiple button actions with if/elif in single handler |
| on_decorator02.py |
Uses @on decorator to route button events to separate handlers |
| prevent.py |
Demonstrates prevent context manager to suppress input change events |
Getting Started
| File |
Description |
| console.py |
Simulates a screenshot of the Textual devtools console |
Guide (root)
| File |
Description |
| dom1.py |
Minimal empty Textual app skeleton |
| dom2.py |
App composing Header and Footer widgets |
| dom3.py |
Dialog with question text and Yes/No buttons |
| dom4.py |
Dialog with question and buttons using external CSS (+tcss) |
| structure.py |
Clock widget rendering current datetime with interval refresh |
Guide: Actions
| File |
Description |
| actions01.py |
Action setting screen background color on key press |
| actions02.py |
Action invoked via run_action with string syntax |
| actions03.py |
Actions triggered by markup click links to set background |
| actions04.py |
Actions with key bindings and click links for background color |
| actions05.py |
Widget-level actions with ColorSwitcher on two Static widgets (+tcss) |
| actions06.py |
Paginated app with check_action disabling next/previous bindings (+tcss) |
| actions07.py |
Paginated app using reactive bindings=True for auto refresh |
Guide: Animation
| File |
Description |
| animation01.py |
Animates widget opacity from 1.0 to 0.0 over two seconds |
| animation01_static.py |
Stati |
…(truncated)
1---2name: bx-textual3description: Textual TUI framework documentation reference Use when this capability is needed.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## Getting Started2122| Page | Description |23|---------------------------------------|--------------------------------------------------------|24| [Getting Started](getting_started.md) | Installation and first steps with Textual |25| [Tutorial](tutorial.md) | Step-by-step tutorial building a stopwatch application |26| [FAQ](FAQ.md) | Frequently asked questions |27| [Help](help.md) | Getting help and reporting issues |28| [Roadmap](roadmap.md) | Project roadmap and planned features |29| [Linux Console](linux-console.md) | Notes on running Textual in the Linux console |3031---3233## Guide3435The 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).3637| Page | Description |38|---------------------------------------------|----------------------------------------------------------------------|39| [App Basics](guide/app.md) | Creating and running Textual applications |40| [Textual CSS](guide/CSS.md) | Styling with Textual CSS, the DOM, and selectors |41| [Actions](guide/actions.md) | Allow-listed functions with string syntax for links and key bindings |42| [Animation](guide/animation.md) | Visual effects such as movement, blending, and fading |43| [Command Palette](guide/command_palette.md) | Built-in command palette for quick access to app functionality |44| [Content](guide/content.md) | Specifying and formatting widget content |45| [Themes](guide/design.md) | Built-in themes and creating custom themes |46| [Devtools](guide/devtools.md) | Development tools for debugging Textual apps |47| [Events and Messages](guide/events.md) | Event handling and the message system |48| [Input](guide/input.md) | Responding to key presses and mouse actions |49| [Layout](guide/layout.md) | Arranging widgets with vertical, horizontal, grid, and dock layouts |50| [DOM Queries](guide/queries.md) | Finding and updating widgets using CSS selectors in Python |51| [Reactivity](guide/reactivity.md) | Reactive attributes for simplified app state management |52| [Screens](guide/screens.md) | Creating screens and switching between them |53| [Styles](guide/styles.md) | Applying styles to create user interfaces |54| [Testing](guide/testing.md) | Writing tests for Textual applications |55| [Widgets](guide/widgets.md) | Exploring widgets and creating custom widgets |56| [Workers](guide/workers.md) | Concurrency and the Worker API |5758---5960## Widgets6162Reference 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.6364| Page | Description |65|--------------------------------------------------|------------------------------------------------------------------------------|66| [Button](widgets/button.md) | A simple button with a variety of semantic styles |67| [Checkbox](widgets/checkbox.md) | A classic checkbox control |68| [Collapsible](widgets/collapsible.md) | Content that may be toggled on and off by clicking a title |69| [ContentSwitcher](widgets/content_switcher.md) | A widget for containing and switching display between multiple child widgets |70| [DataTable](widgets/data_table.md) | A powerful data table with configurable cursors |71| [Digits](widgets/digits.md) | Display numbers in tall characters |72| [DirectoryTree](widgets/directory_tree.md) | A tree view of files and folders |73| [Footer](widgets/footer.md) | A footer to display and interact with key bindings |74| [Header](widgets/header.md) | A header to display the app's title and subtitle |75| [Input](widgets/input.md) | A control to enter text |76| [Label](widgets/label.md) | A simple text label |77| [Link](widgets/link.md) | A clickable link that opens a URL |78| [ListItem](widgets/list_item.md) | An item within a ListView |79| [ListView](widgets/list_view.md) | Display a list of items (items may be other widgets) |80| [LoadingIndicator](widgets/loading_indicator.md) | Display an animation while data is loading |81| [Log](widgets/log.md) | Display and update lines of text (such as from a file) |82| [Markdown](widgets/markdown.md) | Display a Markdown document |83| [MarkdownViewer](widgets/markdown_viewer.md) | Display and interact with a Markdown document with navigation |84| [MaskedInput](widgets/masked_input.md) | A control to enter input according to a template mask |85| [OptionList](widgets/option_list.md) | Display a vertical list of options |86| [Placeholder](widgets/placeholder.md) | Display placeholder content while designing a UI |87| [Pretty](widgets/pretty.md) | Display a pretty-formatted Rich renderable |88| [ProgressBar](widgets/progress_bar.md) | A configurable progress bar with ETA and percentage complete |89| [RadioButton](widgets/radiobutton.md) | A simple radio button |90| [RadioSet](widgets/radioset.md) | A collection of radio buttons that enforces uniqueness |91| [RichLog](widgets/rich_log.md) | Display and update text in a scrolling panel |92| [Rule](widgets/rule.md) | A rule widget to separate content, similar to an HTML `<hr>` tag |93| [Select](widgets/select.md) | Select from a number of possible options |94| [SelectionList](widgets/selection_list.md) | Select multiple values from a list of options |95| [Sparkline](widgets/sparkline.md) | Display numerical data as a sparkline |96| [Static](widgets/static.md) | Displays simple static content; typically used as a base class |97| [Switch](widgets/switch.md) | An on/off control, inspired by toggle buttons |98| [TabbedContent](widgets/tabbed_content.md) | A combination of Tabs and ContentSwitcher to navigate static content |99| [Tabs](widgets/tabs.md) | A row of tabs you can select with the mouse or navigate with keys |100| [TextArea](widgets/text_area.md) | A multi-line text area with syntax highlighting |101| [Toast](widgets/toast.md) | A notification message widget used by the built-in notify system |102| [Tree](widgets/tree.md) | A tree control with expandable nodes |103104---105106## Styles107108CSS styles for customizing appearance and layout. Each style page links to related properties and CSS types. See [styles/index.md](styles/index.md).109110### Subsections111112| Section | Description |113|------------------------------------------------------|----------------------------|114| [Grid](styles/grid/index.md) | Grid layout properties |115| [Links](styles/links/index.md) | Link styling properties |116| [Scrollbar Colors](styles/scrollbar_colors/index.md) | Scrollbar color properties |117118### Style Properties119120| Page | Description |121|--------------------------------------------------------------------|----------------------------------------------------------------|122| [Align](styles/align.md) | Defines how a widget's children are aligned |123| [Background](styles/background.md) | Sets the background color of a widget |124| [Background-tint](styles/background_tint.md) | Modifies the background color by tinting it with a new color |125| [Border](styles/border.md) | Enables the drawing of a box around a widget |126| [Border-subtitle-align](styles/border_subtitle_align.md) | Sets the horizontal alignment for the border subtitle |127| [Border-subtitle-background](styles/border_subtitle_background.md) | Sets the background color of the border subtitle |128| [Border-subtitle-color](styles/border_subtitle_color.md) | Sets the color of the border subtitle |129| [Border-subtitle-style](styles/border_subtitle_style.md) | Sets the text style of the border subtitle |130| [Border-title-align](styles/border_title_align.md) | Sets the horizontal alignment for the border title |131| [Border-title-background](styles/border_title_background.md) | Sets the background color of the border title |132| [Border-title-color](styles/border_title_color.md) | Sets the color of the border title |133| [Border-title-style](styles/border_title_style.md) | Sets the text style of the border title |134| [Box-sizing](styles/box_sizing.md) | Determines how the width and height of a widget are calculated |135| [Color](styles/color.md) | Sets the text color of a widget |136| [Content-align](styles/content_align.md) | Aligns content inside a widget |137| [Display](styles/display.md) | Defines whether a widget is displayed or not |138| [Dock](styles/dock.md) | Fixes a widget to the edge of a container |139| [Hatch](styles/hatch.md) | Fills a widget's background with a repeating character pattern |140| [Height](styles/height.md) | Sets a widget's height |141| [Keyline](styles/keyline.md) | Draws lines around child widgets in a container |142| [Layer](styles/layer.md) | Defines the layer a widget belongs to |143| [Layers](styles/layers.md) | Defines an ordered set of layers |144| [Layout](styles/layout.md) | Defines how a widget arranges its children |145| [Margin](styles/margin.md) | Specifies spacing around a widget |146| [Max-height](styles/max_height.md) | Sets a maximum height for a widget |147| [Max-width](styles/max_width.md) | Sets a maximum width for a widget |148| [Min-height](styles/min_height.md) | Sets a minimum height for a widget |149| [Min-width](styles/min_width.md) | Sets a minimum width for a widget |150| [Offset](styles/offset.md) | Defines an offset for the position of a widget |151| [Opacity](styles/opacity.md) | Sets the opacity of a widget |152| [Outline](styles/outline.md) | Draws a box around the content area of a widget |153| [Overflow](styles/overflow.md) | Specifies if and when scrollbars should be displayed |154| [Padding](styles/padding.md) | Specifies spacing around the content of a widget |155| [Pointer](styles/pointer.md) | Sets the shape of the mouse pointer when over a widget |156| [Position](styles/position.md) | Modifies what offset is applied to |157| [Scrollbar-gutter](styles/scrollbar_gutter.md) | Reserves space for a vertical scrollbar |158| [Scrollbar-size](styles/scrollbar_size.md) | Defines the width of scrollbars |159| [Scrollbar-visibility](styles/scrollbar_visibility.md) | Shows or hides scrollbars |160| [Text-align](styles/text_align.md) | Sets the text alignment in a widget |161| [Text-opacity](styles/text_opacity.md) | Blends the foreground color with the background color |162| [Text-overflow](styles/text_overflow.md) | Defines what happens when text overflows |163| [Text-style](styles/text_style.md) | Sets the style for the text in a widget |164| [Text-wrap](styles/text_wrap.md) | Sets how Textual should wrap text |165| [Tint](styles/tint.md) | Blends a color with the whole widget |166| [Visibility](styles/visibility.md) | Determines whether a widget is visible or not |167| [Width](styles/width.md) | Sets a widget's width |168169### Grid Properties170171| Page | Description |172|---------------------------------------------|----------------------------------------------------------------|173| [Column-span](styles/grid/column_span.md) | Specifies how many columns a widget will span in a grid layout |174| [Grid-columns](styles/grid/grid_columns.md) | Defines the width of the columns of the grid |175| [Grid-gutter](styles/grid/grid_gutter.md) | Sets the spacing between adjacent cells in the grid |176| [Grid-rows](styles/grid/grid_rows.md) | Defines the height of the rows of the grid |177| [Grid-size](styles/grid/grid_size.md) | Sets the number of columns and rows in a grid layout |178| [Row-span](styles/grid/row_span.md) | Specifies how many rows a widget will span in a grid layout |179180### Link Styles181182| Page | Description |183|----------------------------------------------------------------|------------------------------------------------------------------|184| [Link-background](styles/links/link_background.md) | Sets the background color of the link |185| [Link-background-hover](styles/links/link_background_hover.md) | Sets the background color of the link when the cursor is over it |186| [Link-color](styles/links/link_color.md) | Sets the color of the link text |187| [Link-color-hover](styles/links/link_color_hover.md) | Sets the color of the link text when the cursor is over it |188| [Link-style](styles/links/link_style.md) | Sets the text style for the link text |189| [Link-style-hover](styles/links/link_style_hover.md) | Sets the text style for the link text when the cursor is over it |190191### Scrollbar Color Properties192193| Page | Description |194|---------------------------------------------------------------------------------------|----------------------------------------------------------------------|195| [Scrollbar-background](styles/scrollbar_colors/scrollbar_background.md) | Sets the background color of the scrollbar |196| [Scrollbar-background-active](styles/scrollbar_colors/scrollbar_background_active.md) | Sets the scrollbar background color when the thumb is being dragged |197| [Scrollbar-background-hover](styles/scrollbar_colors/scrollbar_background_hover.md) | Sets the scrollbar background color when the cursor is over it |198| [Scrollbar-color](styles/scrollbar_colors/scrollbar_color.md) | Sets the color of the scrollbar thumb |199| [Scrollbar-color-active](styles/scrollbar_colors/scrollbar_color_active.md) | Sets the scrollbar thumb color when it is being dragged |200| [Scrollbar-color-hover](styles/scrollbar_colors/scrollbar_color_hover.md) | Sets the scrollbar thumb color when the cursor is over it |201| [Scrollbar-corner-color](styles/scrollbar_colors/scrollbar_corner_color.md) | Sets the color of the gap between horizontal and vertical scrollbars |202203---204205## Events206207Reference 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).208209| Page | Description |210|--------------------------------------------------|--------------------------------------------|211| [AppBlur](events/app_blur.md) | Sent when the application loses focus |212| [AppFocus](events/app_focus.md) | Sent when the application gains focus |213| [Blur](events/blur.md) | Sent when a widget loses focus |214| [Click](events/click.md) | Sent when a widget is clicked |215| [DescendantBlur](events/descendant_blur.md) | Sent when a descendant widget loses focus |216| [DescendantFocus](events/descendant_focus.md) | Sent when a descendant widget gains focus |217| [Enter](events/enter.md) | Sent when the mouse enters a widget |218| [Focus](events/focus.md) | Sent when a widget gains focus |219| [Hide](events/hide.md) | Sent when a widget is hidden |220| [Key](events/key.md) | Sent when a key is pressed |221| [Leave](events/leave.md) | Sent when the mouse leaves a widget |222| [Load](events/load.md) | Sent when the application is loading |223| [Mount](events/mount.md) | Sent when a widget is mounted to the DOM |224| [MouseCapture](events/mouse_capture.md) | Sent when a widget captures the mouse |225| [MouseDown](events/mouse_down.md) | Sent when a mouse button is pressed |226| [MouseMove](events/mouse_move.md) | Sent when the mouse moves over a widget |227| [MouseRelease](events/mouse_release.md) | Sent when a widget releases the mouse |228| [MouseScrollDown](events/mouse_scroll_down.md) | Sent when the mouse scrolls down |229| [MouseScrollLeft](events/mouse_scroll_left.md) | Sent when the mouse scrolls left |230| [MouseScrollRight](events/mouse_scroll_right.md) | Sent when the mouse scrolls right |231| [MouseScrollUp](events/mouse_scroll_up.md) | Sent when the mouse scrolls up |232| [MouseUp](events/mouse_up.md) | Sent when a mouse button is released |233| [Paste](events/paste.md) | Sent when text is pasted into the terminal |234| [Print](events/print.md) | Sent when the app receives a print request |235| [Resize](events/resize.md) | Sent when a widget is resized |236| [ScreenResume](events/screen_resume.md) | Sent when a screen is resumed |237| [ScreenSuspend](events/screen_suspend.md) | Sent when a screen is suspended |238| [Show](events/show.md) | Sent when a widget becomes visible |239| [Unmount](events/unmount.md) | Sent when a widget is removed from the DOM |240241---242243## CSS Types244245CSS 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).246247| Page | Description |248|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|249| [<border>](css_types/border.md) | Border style type — used by border, outline |250| [<color>](css_types/color.md) | Color type — used by 23 style properties (background, color, tint, border colors, link colors, scrollbar colors) |251| [<hatch>](css_types/hatch.md) | Hatch character type — used by hatch |252| [<horizontal>](css_types/horizontal.md) | Horizontal position — used by align, content-align, border-title-align, border-subtitle-align |253| [<integer>](css_types/integer.md) | Integer type — used by column-span, row-span, grid-size, grid-gutter, margin, padding, scrollbar-size |254| [<keyline>](css_types/keyline.md) | Keyline style type — used by keyline |255| [<name>](css_types/name.md) | Name identifier type — used by layer, layers |256| [<number>](css_types/number.md) | Number type (int or decimal) — used by opacity, text-opacity |257| [<overflow>](css_types/overflow.md) | Overflow mode type — used by overflow |258| [<percentage>](css_types/percentage.md) | Percentage type — used by 22 style properties (color alphas, opacity, background, tint) |259| [<pointer>](css_types/pointer.md) | Mouse cursor shape type — used by pointer |260| [<position>](css_types/position.md) | Offset application mode — used by position |261| [<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 |262| [<text-align>](css_types/text_align.md) | Text alignment type — used by text-align |263| [<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 |264| [<vertical>](css_types/vertical.md) | Vertical position — used by align, content-align |265266---267268## API Reference269270Module-level API reference. Each API stub links to its corresponding guide page for in-depth coverage. See [api/index.md](api/index.md).271272| Module | Description |273|----------------------------------------------------------|----------------------------------------------|274| [textual.app](api/app.md) | The App class and related utilities |275| [textual.await_complete](api/await_complete.md) | AwaitComplete for background work completion |276| [textual.await_remove](api/await_remove.md) | AwaitRemove for widget removal |277| [textual.binding](api/binding.md) | Key bindings |278| [textual.cache](api/cache.md) | Caching utilities |279| [textual.color](api/color.md) | Color handling and manipulation |280| [textual.command](api/command.md) | Command palette |281| [textual.compose](api/compose.md) | Compose utility |282| [textual.constants](api/constants.md) | Framework constants |283| [textual.containers](api/containers.md) | Layout containers |284| [textual.content](api/content.md) | Content rendering |285| [textual.coordinate](api/coordinate.md) | Coordinate data type |286| [textual.dom](api/dom_node.md) | DOM node base class |287| [textual.errors](api/errors.md) | Exception classes |288| [textual.events](api/events.md) | Event classes |289| [textual.filter](api/filter.md) | Display filters |290| [textual.fuzzy](api/fuzzy_matcher.md) | Fuzzy matching |291| [textual.geometry](api/geometry.md) | Geometry primitives |292| [textual.getters](api/getters.md) | Getter utilities |293| [textual.highlight](api/highlight.md) | Syntax highlighting |294| [textual.layout](api/layout.md) | Layout engine |295| [textual.lazy](api/lazy.md) | Lazy loading |296| [textual (logger)](api/logger.md) | Root logger |297| [textual.logging](api/logging.md) | Logging utilities |298| [textual.map_geometry](api/map_geometry.md) | Map geometry data structure |299| [textual.markup](api/markup.md) | Markup processing |300| [textual.message](api/message.md) | Message base class |301| [textual.message_pump](api/message_pump.md) | Message pump |302| [textual.on](api/on.md) | The on decorator for event handling |303| [textual.pilot](api/pilot.md) | Testing pilot |304| [textual.css.query](api/query.md) | DOM query API |305| [textual.reactive](api/reactive.md) | Reactive attributes |306| [textual.renderables](api/renderables.md) | Rich renderables for widgets |307| [textual.screen](api/screen.md) | Screen class |308| [textual.scroll_view](api/scroll_view.md) | Scroll view widget |309| [textual.scrollbar](api/scrollbar.md) | Scrollbar widget |310| [textual.signal](api/signal.md) | Signal for pub/sub messaging |311| [textual.strip](api/strip.md) | Strip rendering |312| [textual.style](api/style.md) | Style data type |313| [textual.suggester](api/suggester.md) | Input suggestion |314| [textual.system_commands](api/system_commands_source.md) | System commands |315| [textual.timer](api/timer.md) | Timer utilities |316| [textual.types](api/types.md) | Type exports |317| [textual.validation](api/validation.md) | Input validation |318| [textual.walk](api/walk.md) | DOM tree walking |319| [textual.widget](api/widget.md) | Widget base class |320| [textual.work](api/work.md) | Work decorator |321| [textual.worker](api/worker.md) | Worker class |322| [textual.worker_manager](api/worker_manager.md) | Worker manager |323324---325326## How-To Guides327328Practical articles covering various Textual topics. Each guide links to relevant reference pages and guide sections. See [how-to/index.md](how-to/index.md).329330| Guide | Description |331|--------------------------------------------------------|-------------------------------------------------------------|332| [Center Things](how-to/center-things.md) | Different ways to center widgets, text, and content |333| [Design a Layout](how-to/design-a-layout.md) | Tips for designing your application layout from scratch |334| [Package with Hatch](how-to/package-with-hatch.md) | How to package and publish a Textual app using Hatch |335| [Render and Compose](how-to/render-and-compose.md) | Understanding the difference between render() and compose() |336| [Style Inline Apps](how-to/style-inline-apps.md) | Customizing the appearance of inline-mode apps |337| [Work with Containers](how-to/work-with-containers.md) | Using container widgets to arrange layout |338339---340341## Examples342343Example source code referenced throughout these docs (317 entries). Files marked *(+tcss)* have a companion `.tcss` stylesheet with the same base name.344345### App346347| File | Description |348|---------------------------------------------------------|----------------------------------------------------------------------|349| [event01.py](examples/app/event01.py) | Demonstrates changing screen background color on key press events |350| [question01.py](examples/app/question01.py) | Simple yes/no question app returning button press result |351| [question02.py](examples/app/question02.py) | Question app with external TCSS stylesheet for grid layout *(+tcss)* |352| [question03.py](examples/app/question03.py) | Question app with inline CSS grid layout styling |353| [question_title01.py](examples/app/question_title01.py) | Question app with Header widget, title, and subtitle |354| [question_title02.py](examples/app/question_title02.py) | Question app updating title and subtitle on key events |355| [simple01.py](examples/app/simple01.py) | Minimal empty Textual App subclass definition |356| [simple02.py](examples/app/simple02.py) | Minimal Textual app with run entry point |357| [suspend.py](examples/app/suspend.py) | Demonstrates suspending the app to run an external editor |358| [suspend_process.py](examples/app/suspend_process.py) | Demonstrates Ctrl+Z key binding to suspend the process |359| [widgets01.py](examples/app/widgets01.py) | Welcome widget app that exits on button press |360| [widgets02.py](examples/app/widgets02.py) | Mounts Welcome widget dynamically on any key press |361| [widgets03.py](examples/app/widgets03.py) | Dynamically mounts Welcome widget and changes button label |362| [widgets04.py](examples/app/widgets04.py) | Async mount of Welcome widget with button label update |363364### Events365366| File | Description |367|--------------------------------------------------------|----------------------------------------------------------------------|368| [custom01.py](examples/events/custom01.py) | Custom message event with ColorButton posting Selected messages |369| [dictionary.py](examples/events/dictionary.py) | Dictionary lookup app searching an API as you type *(+tcss)* |370| [on_decorator.tcss](examples/events/on_decorator.tcss) | Centers buttons horizontally with margin spacing |371| [on_decorator01.py](examples/events/on_decorator01.py) | Handles multiple button actions with if/elif in single handler |372| [on_decorator02.py](examples/events/on_decorator02.py) | Uses @on decorator to route button events to separate handlers |373| [prevent.py](examples/events/prevent.py) | Demonstrates prevent context manager to suppress input change events |374375### Getting Started376377| File | Description |378|---------------------------------------------------|--------------------------------------------------------|379| [console.py](examples/getting_started/console.py) | Simulates a screenshot of the Textual devtools console |380381### Guide (root)382383| File | Description |384|---------------------------------------------|---------------------------------------------------------------|385| [dom1.py](examples/guide/dom1.py) | Minimal empty Textual app skeleton |386| [dom2.py](examples/guide/dom2.py) | App composing Header and Footer widgets |387| [dom3.py](examples/guide/dom3.py) | Dialog with question text and Yes/No buttons |388| [dom4.py](examples/guide/dom4.py) | Dialog with question and buttons using external CSS *(+tcss)* |389| [structure.py](examples/guide/structure.py) | Clock widget rendering current datetime with interval refresh |390391### Guide: Actions392393| File | Description |394|-----------------------------------------------------|----------------------------------------------------------------------------|395| [actions01.py](examples/guide/actions/actions01.py) | Action setting screen background color on key press |396| [actions02.py](examples/guide/actions/actions02.py) | Action invoked via run_action with string syntax |397| [actions03.py](examples/guide/actions/actions03.py) | Actions triggered by markup click links to set background |398| [actions04.py](examples/guide/actions/actions04.py) | Actions with key bindings and click links for background color |399| [actions05.py](examples/guide/actions/actions05.py) | Widget-level actions with ColorSwitcher on two Static widgets *(+tcss)* |400| [actions06.py](examples/guide/actions/actions06.py) | Paginated app with check_action disabling next/previous bindings *(+tcss)* |401| [actions07.py](examples/guide/actions/actions07.py) | Paginated app using reactive bindings=True for auto refresh |402403### Guide: Animation404405| File | Description |406|------------------------------------------------------------------------|-----------------------------------------------------------|407| [animation01.py](examples/guide/animator/animation01.py) | Animates widget opacity from 1.0 to 0.0 over two seconds |408| [animation01_static.py](examples/guide/animator/animation01_static.py) | Stati409410…(truncated)
tomevault-io