How do I install the Textual API Reference skill?

Run npx skillmds@latest add cjthompson/textual-api-reference in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Textual API Reference skill do?

Use when working with Textual TUI widgets — looking up available components, reactive attributes, constructor parameters, or messages emitted It is listed under Integrations & APIs on SkillMD.

Is Textual API Reference safe to use?

SkillMD's automated safety review verdict for this skill is PASS. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Textual API Reference?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Textual API Reference free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Textual API Reference?

cjthompson (@cjthompson) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Textual API Reference by cjthompson

Name: Textual API Reference
Rating: 4.2 (5 reviews)
Author: cjthompson

Textual Widget API Reference

Overview

Complete reference for Textual's built-in widgets. Reactive attributes use reactive() and trigger re-renders on change.

Import path: from textual.widgets import Button, Input, DataTable, ...

Shared Attributes

These appear on multiple widgets; individual entries reference them rather than repeating the full definition.

Attribute	Type	Default	Widgets
`compact`	`bool`	`False`	Button, Footer, MaskedInput, OptionList, RadioSet, Select
`cursor_blink`	`bool`	`True`	Input, TextArea
`auto_scroll`	`bool`	`True`	Log, RichLog
`disabled`	`bool`	`False`	All focusable widgets (base Widget attribute)

ToggleButton base — Checkbox, RadioButton, and Switch all extend ToggleButton and share value (bool, False) as a reactive attribute.

Message convention — Every message has a .control attribute pointing to the posting widget. Many also carry a widget-named alias (.button on Button.Pressed, .checkbox on Checkbox.Changed, etc.).

Form Controls

Button

Clickable action trigger.

Attribute	Type	Default	Notes
`label`	`ContentText\|None`	`None`	Button text
`variant`	`str`	`"default"`	`"default"`, `"primary"`, `"success"`, `"warning"`, `"error"`
`disabled`	`bool`	`False`	→ see Shared
`compact`	`bool`	`False`	→ see Shared
`flat`	`bool`	`False`	Removes border
`active_effect_duration`	`float`	`0.2`	Click animation duration

Constructor extras: action (str), tooltip (str)

Messages: Button.Pressed (.button)

Checkbox

Boolean toggle; extends ToggleButton.

Attribute	Type	Default
`value`	`bool`	`False`

Constructor: label (str, positional — the checkbox text)

Messages: Checkbox.Changed (.value, .checkbox)

Input

Single-line text entry with optional validation.

Attribute	Type	Default	Notes
`value`	`str`	`""`	Current text
`placeholder`	`str`	`""`	Hint text when empty
`password`	`bool`	`False`	Mask characters
`restrict`	`str`	`None`	Regex limiting input
`type`	`str`	`"text"`	`"text"`, `"integer"`, `"number"`
`max_length`	`int\|None`	`None`	Character limit
`valid_empty`	`bool`	`False`	Allow empty as valid
`cursor_position`	`int`	`0`	Cursor index
`cursor_blink`	`bool`	`True`	→ see Shared

Read-only: is_valid, selected_text, selection (Selection), cursor_at_start, cursor_at_end

Messages: Input.Changed (.value), Input.Submitted (.value), Input.Blurred (.value, .validation_result)

MaskedInput

Text input with a formatting mask (e.g. dates, phone numbers).

Attribute	Type	Default	Notes
`value`	`str\|None`	`None`	Current text
`template`	`str`	required	Mask pattern
`placeholder`	`str`	`""`	Hint text when empty
`compact`	`bool`	`False`	→ see Shared

Messages: MaskedInput.Changed (.value), MaskedInput.Submitted (.value)

RadioButton

Standalone radio option; extends ToggleButton. Usually used inside RadioSet.

Attribute	Type	Default
`value`	`bool`	`False`

Messages: RadioButton.Changed (.radio_button, .value)

RadioSet

Group of RadioButton widgets enforcing single selection.

Attribute	Type	Default	Notes
`pressed_index`	`int`	`-1`	Index of selected button; `-1` = none selected
`compact`	`bool`	`False`	→ see Shared

Read-only: pressed_button — the active RadioButton or None

Messages: RadioSet.Changed (.index, .pressed, .radio_set)

Select

Dropdown with a single selected value.

Attribute	Type	Default	Notes
`value`	`SelectType\|NoSelection`	`Select.NULL`	`Select.NULL` when nothing selected
`prompt`	`str`	`"Select"`	Placeholder text
`expanded`	`bool`	`False`	Dropdown open/closed
`compact`	`bool`	`False`	→ see Shared

Read-only: selection — current value or None (never returns Select.NULL)

Methods: is_blank(), clear() (requires allow_blank=True), set_options(options)

Messages: Select.Changed (.value, .select)

Switch

Toggle switch (binary on/off, visually distinct from Checkbox). Extends ToggleButton.

Attribute	Type	Default
`value`	`bool`	`False`
`animate`	`bool`	`True`

Messages: Switch.Changed (.value)

Display

Label

Simple text display. Not focusable. No reactive attributes; inherits from Static — use update() to change content.

Link

Clickable hyperlink.

Attribute	Type	Default
`text`	`str`	`""`
`url`	`str`	`""`

Placeholder

Empty space — useful during layout development.

Attribute	Type	Default	Notes
`variant`	`str`	`"default"`	`"default"`, `"size"`, `"text"`

Method: cycle_variant() — advance to next variant

Rule

Horizontal or vertical separator line.

Attribute	Type	Default	Notes
`orientation`	`str`	`"horizontal"`	`"horizontal"` or `"vertical"`
`line_style`	`str`	`"solid"`	`"ascii"`, `"blank"`, `"dashed"`, `"double"`, `"heavy"`, `"hidden"`, `"none"`, `"solid"`, `"thick"`

Static

General-purpose container for Rich renderables.

Attribute	Type	Default
`content`	`VisualType`	`""`

Read-only: visual — what actually renders (may differ from content)

Constructor: content, expand (bool), shrink (bool), markup (bool, default True)

Method: update(content, *, layout=True) — update rendered content

Complex Containers

DataTable

Grid with rows/columns, keyboard navigation, and cursor selection.

Attribute	Type	Default	Notes
`show_header`	`bool`	`True`	Toggle header row
`show_row_labels`	`bool`	`True`	Toggle row labels
`fixed_rows`	`int`	`0`	Non-scrolling rows at top
`fixed_columns`	`int`	`0`	Non-scrolling columns at left
`zebra_stripes`	`bool`	`False`	Alternating row colors
`header_height`	`int`	`1`	Header row height
`show_cursor`	`bool`	`True`	Show cursor highlight
`cursor_type`	`str`	`"cell"`	`"cell"`, `"row"`, `"column"`, `"none"`
`cursor_coordinate`	`Coordinate`	`(0,0)`	Current cursor position
`hover_coordinate`	`Coordinate`	`(0,0)`	Hovered cell position
`cell_padding`	`int`	`1`	Horizontal padding per cell

Read-only: cursor_row, cursor_column, hover_row, hover_column, row_count, rows, columns, ordered_rows, ordered_columns

Key methods:

add_column(label, *, width=None, key=None) → ColumnKey
add_row(*cells, *, key=None, label=None) → RowKey
add_columns(*columns), add_rows(rows)
get_cell(row_key, col_key), get_cell_at(coordinate)
update_cell(row_key, col_key, value), update_cell_at(coordinate, value)
remove_row(row_key), remove_column(column_key)
clear(columns=False), sort(*columns, key=None, reverse=False)
move_cursor(row=None, column=None, animate=False)

Messages: DataTable.CellSelected, DataTable.RowSelected, DataTable.ColumnSelected, DataTable.CellHighlighted, DataTable.RowHighlighted, DataTable.ColumnHighlighted, DataTable.HeaderSelected, DataTable.RowLabelSelected

DirectoryTree

File system browser displaying a directory hierarchy.

Attribute	Type	Default
`path`	`str\|Path`	required
`show_root`	`bool`	`True`
`show_guides`	`bool`	`True`
`guide_depth`	`int`	`4`

Messages: DirectoryTree.FileSelected (.path), DirectoryTree.DirectorySelected (.path)

ListItem

Focusable container item for use inside ListView. Arrow-key navigation is handled by the parent.

Attribute	Type	Default	Notes
`highlighted`	`bool`	`False`	Set by parent `ListView`; do not set directly

No messages.

ListView

Vertical list of ListItem widgets with keyboard navigation.

Attribute	Type	Default	Notes
`index`	`int\|None`	`None`	Highlighted item index

Constructor: *children (ListItem), initial_index (int|None, default 0), disabled (bool)

Read-only: highlighted_child — the focused ListItem or None

Methods: append(item), extend(items), insert(index, items), pop(index=None), clear(), remove_items(indices)

Messages: ListView.Highlighted (.item, .list_view), ListView.Selected (.item, .list_view, .index)

OptionList

Scrollable list of options with single selection.

Attribute	Type	Default
`highlighted`	`int\|None`	`None`
`compact`	`bool`	`False`

Read-only: highlighted_option, option_count, options

Methods: add_option(item), add_options(items), clear_options(), get_option(id) (by option ID string), get_option_at_index(index), remove_option(id), set_options(options)

Messages: OptionList.OptionHighlighted (.option, .option_id, .option_index), OptionList.OptionSelected (.option, .option_id, .option_index)

SelectionList

Multi-select list with independent checked states per item.

Attribute	Type	Default
`highlighted`	`int\|None`	`None`

Read-only: selected — list of values for checked items

Messages: SelectionList.SelectionHighlighted (.selection, .selection_index, .selection_list), SelectionList.SelectionToggled (.selection, .selection_index, .selection_list), SelectionList.SelectedChanged

Tree

Generic hierarchical tree view with expandable nodes.

Attribute	Type	Default
`show_root`	`bool`	`True`
`show_guides`	`bool`	`True`
`guide_depth`	`int`	`4`
`auto_expand`	`bool`	`True`

Read-only: root — the root TreeNode; cursor_node — focused node

Node methods: node.add(label, data=None), node.add_leaf(label, data=None), node.expand(), node.collapse(), node.toggle(), node.remove()

Messages: Tree.NodeCollapsed, Tree.NodeExpanded, Tree.NodeHighlighted (.node), Tree.NodeSelected (.node; .node.data holds attached data)

Content

Log

Appends plain-text lines. Does not support Rich markup.

Attribute	Type	Default
`max_lines`	`int\|None`	`None`
`auto_scroll`	`bool`	`True`

Read-only: line_count, lines

Methods: write(data), write_line(line), write_lines(lines), clear()

Markdown

Renders a Markdown string as rich formatted text.

Constructor: markdown (str|None, default None), open_links (bool, default True), parser_factory (Callable|None, default None)

Read-only: source, table_of_contents

Methods: update(markdown), append(markdown), load(path) (async), goto_anchor(anchor) → bool

Messages: Markdown.LinkClicked (.href), Markdown.TableOfContentsSelected (.block_id), Markdown.TableOfContentsUpdated (.table_of_contents)

MarkdownViewer

Interactive Markdown with table of contents and navigation history.

Import: from textual.widgets import MarkdownViewer

Attribute	Type	Default
`show_table_of_contents`	`bool`	`True`

Constructor: markdown (str|None, default None), open_links (bool, default True)

Read-only: document (the underlying Markdown widget), table_of_contents

Methods: go(location) (async — navigates to a document path), back() (async), forward() (async)

Messages: MarkdownViewer.NavigatorUpdated

Pretty

Pretty-prints any Python object using Rich.

Constructor: object (any)

Method: update(object) — replace displayed object

RichLog

Appends Rich renderables (markup, tables, syntax blocks, etc.).

Attribute	Type	Default
`highlight`	`bool`	`False`
`markup`	`bool`	`False`
`max_lines`	`int\|None`	`None`
`min_width`	`int`	`78`
`wrap`	`bool`	`False`
`auto_scroll`	`bool`	`True`

Methods: write(content), clear()

Sparkline

Inline bar-graph of numeric values.

Attribute	Type	Default
`data`	`Sequence[float]\|None`	`None`
`summary_function`	`callable`	`max`

Layout

Collapsible

Expandable/collapsible container with a title bar.

Attribute	Type	Default
`collapsed`	`bool`	`True`
`title`	`str`	`"Toggle"`

Constructor extras: collapsed_symbol (str, default "▶"), expanded_symbol (str, default "▼")

Messages: Collapsible.Collapsed, Collapsible.Expanded, Collapsible.Toggled (base message for both)

ContentSwitcher

Shows one child widget at a time; switch by widget ID.

Import: from textual.widgets import ContentSwitcher (NOT textual.containers)

Attribute	Type	Default	Notes
`current`	`str\|None`	`None`	ID of visible child

Constructor: initial (str|None, default None) — which child to show at startup (distinct from current reactive)

Read-only: visible_content — the currently visible Widget or None

Method: add_content(widget, *, id=None, set_current=False)

TabbedContent

Combines Tabs + ContentSwitcher; each pane declared with TabPane.

Attribute	Type	Default	Notes
`active`	`str`	`""`	Active tab ID; Textual selects the first tab automatically

Read-only: active_pane (TabPane|None), tab_count (int)

Methods: add_pane(), remove_pane(), clear_panes(), get_pane(), enable_tab(), disable_tab(), show_tab(), hide_tab()

Messages: TabbedContent.TabActivated (.tab, .pane), TabbedContent.Cleared

Tabs

Tab navigation bar only (no content switching built-in).

Attribute	Type	Default
`active`	`str`	`""`

Read-only: active_tab (Tab|None), tab_count (int)

Methods: add_tab(tab), remove_tab(tab_or_id), clear(), disable(), enable(), hide(), show()

Messages: Tabs.TabActivated (.tab), Tabs.Cleared, Tabs.TabDisabled, Tabs.TabEnabled, Tabs.TabHidden, Tabs.TabShown

Feedback

Digits

Displays a numeric value in large seven-segment–style digits.

Attribute	Type	Default
`value`	`str`	`""`

Method: update(value) — update displayed value

LoadingIndicator

Animated spinner. No reactive attributes. Mount/unmount to show/hide.

ProgressBar

Linear progress indicator.

Attribute	Type	Default	Notes
`total`	`float\|None`	`None`	100% value; `None` = indeterminate
`progress`	`float`	`0`	Current value
`gradient`	`Gradient\|None`	`None`	Custom color gradient

Constructor extras: show_bar (bool, True), show_percentage (bool, True), show_eta (bool, True)

Read-only: percentage (float|None) — completion ratio (0.0–1.0)

Methods: advance(amount=1), update(*, total=None, progress=None, advance=None)

Toast

Temporary overlay notification (auto-dismisses).

Create via app.notify(message, severity="information", timeout=10) — do not mount directly.

Severity values: "information", "warning", "error"

Scaffolding

Header

Application title bar, typically docked at top.

Attribute	Type	Default
`tall`	`bool`	`False`
`icon`	`str`	`"⭘"`
`time_format`	`str`	`"%X"`

tall cannot be passed to the constructor — set it after mount or via CSS:

# In on_mount:
self.query_one(Header).tall = True
# Or in CSS:
Header { height: 2; }

show_clock does not exist — a common hallucination. The clock is always shown; control its format with time_format.

Footer

Keybinding legend bar, typically docked at bottom.

Attribute	Type	Default
`combine_groups`	`bool`	`True`
`compact`	`bool`	`False`
`show_command_palette`	`bool`	`True`

Multi-line Editor

TextArea

Full-featured multi-line code/text editor with syntax highlighting.

Attribute	Type	Default	Notes
`language`	`str\|None`	`None`	Syntax highlight language (e.g. `"python"`, `"json"`)
`theme`	`str`	`"css"`	Editor color theme
`selection`	`Selection`	`Selection()`	Current text selection range
`show_line_numbers`	`bool`	`False`	Show line number gutter
`line_number_start`	`int`	`1`	Starting line number
`indent_width`	`int`	`4`	Spaces per indent level
`match_cursor_bracket`	`bool`	`True`	Highlight matching bracket
`cursor_blink`	`bool`	`True`	→ see Shared
`soft_wrap`	`bool`	`True`	Soft line wrapping
`read_only`	`bool`	`False`	Prevent keyboard edits

Read-only: text (full content), selected_text, document, available_themes, available_languages, is_syntax_aware

Writable: cursor_location (row, col tuple) — assign to reposition cursor

Class method: TextArea.code_editor(text, language=None, ...) — convenience constructor for code editing

Messages: TextArea.Changed (.text_area), TextArea.SelectionChanged (.selection)

Documentation

https://textual.textualize.io/widgets/

Textual API Reference

File contents