textual.widget

This module contains the Widget class, the base class for all widgets.

AwaitMount

AwaitMount(parent, widgets)

An optional awaitable returned by mount and mount_all.

Example

await self.mount(Static("foo"))

BadWidgetName

Bases: Exception

Raised when widget class names do not satisfy the required restrictions.

MountError

Bases: WidgetError

Error raised when there was a problem with the mount request.

PseudoClasses

Bases: NamedTuple

Used for render/render_line based widgets that use caching. This structure can be used as a cache-key.

enabled instance-attribute

enabled

Is 'enabled' applied?

focus instance-attribute

focus

Is 'focus' applied?

hover instance-attribute

hover

Is 'hover' applied?

Widget

Widget(
    *children,
    name=None,
    id=None,
    classes=None,
    disabled=False,
)

Bases: DOMNode

A Widget is the base class for Textual widgets.

See also static for starting point for your own widgets.

Parameters:

Name	Type	Description	Default
*children	Widget	Child widgets.	()
name	str | None	The name of the widget.	None
id	str | None	The ID of the widget in the DOM.	None
classes	str | None	The CSS classes for the widget.	None
disabled	bool	Whether the widget is disabled or not.	False

ALLOW_MAXIMIZE class-attribute

ALLOW_MAXIMIZE = None

Defines default logic to allow the widget to be maximized.

• None Use default behavior (Focusable widgets may be maximized)
• False Do not allow widget to be maximized
• True Allow widget to be maximized

BORDER_SUBTITLE class-attribute

BORDER_SUBTITLE = ''

Initial value for border_subtitle attribute.

BORDER_TITLE class-attribute

BORDER_TITLE = ''

Initial value for border_title attribute.

absolute_offset instance-attribute

absolute_offset = None

Force an absolute offset for the widget (used by tooltips).

allow_horizontal_scroll property

allow_horizontal_scroll

Check if horizontal scroll is permitted.

May be overridden if you want different logic regarding allowing scrolling.

allow_maximize property

allow_maximize

Check if the widget may be maximized.

Returns:

Type	Description
bool	True if the widget may be maximized, or False if it should not be maximized.

allow_vertical_scroll property

allow_vertical_scroll

Check if vertical scroll is permitted.

May be overridden if you want different logic regarding allowing scrolling.

auto_links class-attribute instance-attribute

auto_links = Reactive(True)

Widget will highlight links automatically.

border_subtitle class-attribute instance-attribute

border_subtitle = _BorderTitle()

A title to show in the bottom border (if there is one).

border_title class-attribute instance-attribute

border_title = _BorderTitle()

A title to show in the top border (if there is one).

can_focus class-attribute instance-attribute

can_focus = False

Widget may receive focus.

can_focus_children class-attribute instance-attribute

can_focus_children = True

Widget's children may receive focus.

container_size property

container_size

The size of the container (parent widget).

Returns:

Type	Description
Size	Container size.

container_viewport property

container_viewport

The viewport region (parent window).

Returns:

Type	Description
Region	The region that contains this widget.

content_offset property

content_offset

An offset from the Widget origin where the content begins.

Returns:

Type	Description
Offset	Offset from widget's origin.

content_region property

content_region

Gets an absolute region containing the content (minus padding and border).

Returns:

Type	Description
Region	Screen region that contains a widget's content.

content_size property

content_size

The size of the content area.

Returns:

Type	Description
Size	Content area size.

disabled class-attribute instance-attribute

disabled = Reactive(False)

Is the widget disabled? Disabled widgets can not be interacted with, and are typically styled to look dimmer.

dock_gutter property

dock_gutter

Space allocated to docks in the parent.

Returns:

Type	Description
Spacing	Space to be subtracted from scrollable area.

expand class-attribute instance-attribute

expand = Reactive(False)

Rich renderable may expand beyond optimal size.

first_of_type property

first_of_type

Is this the first widget of its type in its siblings?

focusable property

focusable

Can this widget currently be focused?

gutter property

gutter

Spacing for padding / border / scrollbars.

Returns:

Type	Description
Spacing	Additional spacing around content area.

has_focus class-attribute instance-attribute

has_focus = Reactive(False, repaint=False)

Does this widget have focus? Read only.

has_focus_within property

has_focus_within

Are any descendants focused?

highlight_link_id class-attribute instance-attribute

highlight_link_id = Reactive('')

The currently highlighted link id. Read only.

horizontal_scrollbar property

horizontal_scrollbar

The horizontal scrollbar.

Note

This will create a scrollbar if one doesn't exist.

Returns:

Type	Description
ScrollBar	ScrollBar Widget.

hover_style class-attribute instance-attribute

hover_style = Reactive(Style, repaint=False)

The current hover style (style under the mouse cursor). Read only.

is_anchored property

is_anchored

Is this widget anchored?

is_container property

is_container

Is this widget a container (contains other widgets)?

is_disabled property

is_disabled

Is the widget disabled either because disabled=True or an ancestor has disabled=True.

is_even property

is_even

Is this widget at an evenly numbered position within its siblings?

is_horizontal_scroll_end property

is_horizontal_scroll_end

Is the horizontal scroll position at the maximum?

is_horizontal_scrollbar_grabbed property

is_horizontal_scrollbar_grabbed

Is the user dragging the vertical scrollbar?

is_in_maximized_view property

is_in_maximized_view

Is this widget, or a parent maximized?

is_maximized property

is_maximized

Is this widget maximized?

is_mounted property

is_mounted

Check if this widget is mounted.

is_mouse_over property

is_mouse_over

Is the mouse currently over this widget?

Note this will be True if the mouse pointer is within the widget's region, even if the mouse pointer is not directly over the widget (there could be another widget between the mouse pointer and self).

is_odd property

is_odd

Is this widget at an oddly numbered position within its siblings?

is_on_screen property

is_on_screen

Check if the node was displayed in the last screen update.

is_scrollable property

is_scrollable

Can this widget be scrolled?

is_scrolling property

is_scrolling

Is this widget currently scrolling?

is_vertical_scroll_end property

is_vertical_scroll_end

Is the vertical scroll position at the maximum?

is_vertical_scrollbar_grabbed property

is_vertical_scrollbar_grabbed

Is the user dragging the vertical scrollbar?

last_of_type property

last_of_type

Is this the last widget of its type in its siblings?

layer property

layer

Get the name of this widgets layer.

Returns:

Type	Description
str	Name of layer.

layers property

layers

Layers of from parent.

Returns:

Type	Description
tuple[str, ...]	Tuple of layer names.

layout property

layout

Get the layout object if set in styles, or a default layout.

Returns:

Type	Description
Layout	A layout object.

link_style property

link_style

Style of links.

Returns:

Type	Description
Style	Rich style.

link_style_hover property

link_style_hover

Style of links underneath the mouse cursor.

Returns:

Type	Description
Style	Rich Style.

loading class-attribute instance-attribute

loading = Reactive(False)

If set to True this widget will temporarily be replaced with a loading indicator.

lock instance-attribute

lock = RLock()

asyncio lock to be used to synchronize the state of the widget.

Two different tasks might call methods on a widget at the same time, which might result in a race condition. This can be fixed by adding async with widget.lock: around the method calls.

max_scroll_x property

max_scroll_x

The maximum value of scroll_x.

max_scroll_y property

max_scroll_y

The maximum value of scroll_y.

mouse_hover class-attribute instance-attribute

mouse_hover = Reactive(False, repaint=False)

Is the mouse over this widget? Read only.

offset property writable

offset

Widget offset from origin.

Returns:

Type	Description
Offset	Relative offset.

opacity property

opacity

Total opacity of widget.

outer_size property

outer_size

The size of the widget (including padding and border).

Returns:

Type	Description
Size	Outer size.

region property

region

The region occupied by this widget, relative to the Screen.

Raises:

Type	Description
NoScreen	If there is no screen.
NoWidget	If the widget is not on the screen.

Returns:

Type	Description
Region	Region within screen occupied by widget.

scroll_offset property

scroll_offset

Get the current scroll offset.

Returns:

Type	Description
Offset	Offset a container has been scrolled by.

scroll_target_x class-attribute instance-attribute

scroll_target_x = Reactive(0.0, repaint=False)

Scroll target destination, X coord.

scroll_target_y class-attribute instance-attribute

scroll_target_y = Reactive(0.0, repaint=False)

Scroll target destination, Y coord.

scroll_x class-attribute instance-attribute

scroll_x = Reactive(0.0, repaint=False, layout=False)

The scroll position on the X axis.

scroll_y class-attribute instance-attribute

scroll_y = Reactive(0.0, repaint=False, layout=False)

The scroll position on the Y axis.

scrollable_content_region property

scrollable_content_region

Gets an absolute region containing the scrollable content (minus padding, border, and scrollbars).

Returns:

Type	Description
Region	Screen region that contains a widget's content.

scrollable_size property

scrollable_size

The size of the scrollable content.

Returns:

Type	Description
Size	Scrollable content size.

scrollbar_corner property

scrollbar_corner

The scrollbar corner.

Note

This will create a scrollbar corner if one doesn't exist.

Returns:

Type	Description
ScrollBarCorner	ScrollBarCorner Widget.

scrollbar_gutter property

scrollbar_gutter

Spacing required to fit scrollbar(s).

Returns:

Type	Description
Spacing	Scrollbar gutter spacing.

scrollbar_size_horizontal property

scrollbar_size_horizontal

Get the height used by the horizontal scrollbar.

Returns:

Type	Description
int	Number of rows in the horizontal scrollbar.

scrollbar_size_vertical property

scrollbar_size_vertical

Get the width used by the vertical scrollbar.

Returns:

Type	Description
int	Number of columns in the vertical scrollbar.

scrollbars_enabled property

scrollbars_enabled

A tuple of booleans that indicate if scrollbars are enabled.

Returns:

Type	Description
tuple[bool, bool]	A tuple of (, )

scrollbars_space property

scrollbars_space

The number of cells occupied by scrollbars for width and height

show_horizontal_scrollbar class-attribute instance-attribute

show_horizontal_scrollbar = Reactive(False, layout=True)

Show a horizontal scrollbar?

show_vertical_scrollbar class-attribute instance-attribute

show_vertical_scrollbar = Reactive(False, layout=True)

Show a vertical scrollbar?

shrink class-attribute instance-attribute

shrink = Reactive(True)

Rich renderable may shrink below optimal size.

siblings property

siblings

Get the widget's siblings (self is removed from the return list).

Returns:

Type	Description
list[Widget]	A list of siblings.

size property

size

The size of the content area.

Returns:

Type	Description
Size	Content area size.

tooltip property writable

tooltip

Tooltip for the widget, or None for no tooltip.

vertical_scrollbar property

vertical_scrollbar

The vertical scrollbar (create if necessary).

Note

This will create a scrollbar if one doesn't exist.

Returns:

Type	Description
ScrollBar	ScrollBar Widget.

virtual_region property

virtual_region

The widget region relative to its container (which may not be visible, depending on scroll offset).

Returns:

Type	Description
Region	The virtual region.

virtual_region_with_margin property

virtual_region_with_margin

The widget region relative to its container (including margin), which may not be visible, depending on the scroll offset.

Returns:

Type	Description
Region	The virtual region of the Widget, inclusive of its margin.

virtual_size class-attribute instance-attribute

virtual_size = Reactive(Size(0, 0), layout=True)

The virtual (scrollable) size of the widget.

visible_siblings property

visible_siblings

A list of siblings which will be shown.

Returns:

Type	Description
list[Widget]	List of siblings.

window_region property

window_region

The region within the scrollable area that is currently visible.

Returns:

Type	Description
Region	New region.

allow_focus

allow_focus()

Check if the widget is permitted to focus.

The base class returns can_focus. This method may be overridden if additional logic is required.

Returns:

Type	Description
bool	True if the widget may be focused, or False if it may not be focused.

allow_focus_children

allow_focus_children()

Check if a widget's children may be focused.

The base class returns can_focus_children. This method may be overridden if additional logic is required.

Returns:

Type	Description
bool	True if the widget's children may be focused, or False if the widget's children may not be focused.

anchor

anchor(*, animate=False)

Anchor the widget, which scrolls it into view (like scroll_visible), but also keeps it in view if the widget's size changes, or the size of its container changes.

Note

Anchored widgets will be un-anchored if the users scrolls the container.

Parameters:

Name	Type	Description	Default
animate	bool	True if the scroll should animate, or False if it shouldn't.	False

animate

animate(
    attribute,
    value,
    *,
    final_value=...,
    duration=None,
    speed=None,
    delay=0.0,
    easing=DEFAULT_EASING,
    on_complete=None,
    level="full"
)

Animate an attribute.

Parameters:

Name	Type	Description	Default
attribute	str	Name of the attribute to animate.	required
value	float | Animatable	The value to animate to.	required
final_value	object	The final value of the animation. Defaults to value if not set.	...
duration	float | None	The duration (in seconds) of the animation.	None
speed	float | None	The speed of the animation.	None
delay	float	A delay (in seconds) before the animation starts.	0.0
easing	EasingFunction | str	An easing method.	DEFAULT_EASING
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'full'

batch async

batch()

Async context manager that combines widget locking and update batching.

Use this async context manager whenever you want to acquire the widget lock and batch app updates at the same time.

Example

async with container.batch():
    await container.remove_children(Button)
    await container.mount(Label("All buttons are gone."))

begin_capture_print

begin_capture_print(stdout=True, stderr=True)

Capture text from print statements (or writes to stdout / stderr).

If printing is captured, the widget will be sent an events.Print message.

Call end_capture_print to disable print capture.

Parameters:

Name	Type	Description	Default
stdout	bool	Whether to capture stdout.	True
stderr	bool	Whether to capture stderr.	True

blur

blur()

Blur (un-focus) the widget.

Focus will be moved to the next available widget in the focus chain.

Returns:

Type	Description
Self	The Widget instance.

can_view_entire

can_view_entire(widget)

Check if a given widget is fully within the current view (scrollable area).

Note: This doesn't necessarily equate to a widget being visible. There are other reasons why a widget may not be visible.

Parameters:

Name	Type	Description	Default
widget	Widget	A widget that is a descendant of self.	required

Returns:

Type	Description
bool	True if the entire widget is in view, False if it is partially visible or not in view.

can_view_partial

can_view_partial(widget)

Check if a given widget at least partially visible within the current view (scrollable area).

Parameters:

Name	Type	Description	Default
widget	Widget	A widget that is a descendant of self.	required

Returns:

Type	Description
bool	True if any part of the widget is visible, False if it is outside of the viewable area.

capture_mouse

capture_mouse(capture=True)

Capture (or release) the mouse.

When captured, mouse events will go to this widget even when the pointer is not directly over the widget.

Parameters:

Name	Type	Description	Default
capture	bool	True to capture or False to release.	True

check_message_enabled

check_message_enabled(message)

Check if a given message is enabled (allowed to be sent).

Parameters:

Name	Type	Description	Default
message	Message	A message object	required

Returns:

Type	Description
bool	True if the message will be sent, or False if it is disabled.

clear_anchor

clear_anchor()

Stop anchoring this widget (a no-op if this widget is not anchored).

clear_cached_dimensions

clear_cached_dimensions()

Clear cached results of get_content_width and get_content_height.

Call if the widget's renderable changes size after the widget has been created.

Note

This is not required if you are extending Static.

compose

compose()

Called by Textual to create child widgets.

This method is called when a widget is mounted or by setting recompose=True when calling refresh().

Note that you don't typically need to explicitly call this method.

Example

def compose(self) -> ComposeResult:
    yield Header()
    yield Label("Press the button below:")
    yield Button()
    yield Footer()

compose_add_child

compose_add_child(widget)

Add a node to children.

This is used by the compose process when it adds children. There is no need to use it directly, but you may want to override it in a subclass if you want children to be attached to a different node.

Parameters:

Name	Type	Description	Default
widget	Widget	A Widget to add.	required

end_capture_print

end_capture_print()

End print capture (set with begin_capture_print).

focus

focus(scroll_visible=True)

Give focus to this widget.

Parameters:

Name	Type	Description	Default
scroll_visible	bool	Scroll parent to make this widget visible.	True

Returns:

Type	Description
Self	The Widget instance.

get_child_by_id

get_child_by_id(id: str) -> Widget

get_child_by_id(
    id: str, expect_type: type[ExpectType]
) -> ExpectType

get_child_by_id(id, expect_type=None)

Return the first child (immediate descendent) of this node with the given ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the child.	required
expect_type	type[ExpectType] | None	Require the object be of the supplied type, or None for any type.	None

Returns:

Type	Description
ExpectType | Widget	The first child of this node with the ID.

Raises:

Type	Description
NoMatches	if no children could be found for this ID
WrongType	if the wrong type was found.

get_child_by_type

get_child_by_type(expect_type)

Get the first immediate child of a given type.

Only returns exact matches, and so will not match subclasses of the given type.

Parameters:

Name	Type	Description	Default
expect_type	type[ExpectType]	The type of the child to search for.	required

Raises:

Type	Description
NoMatches	If no matching child is found.

Returns:

Type	Description
ExpectType	The first immediate child widget with the expected type.

get_component_rich_style

get_component_rich_style(*names, partial=False)

Get a Rich style for a component.

Parameters:

Name	Type	Description	Default
names	str	Names of components.	()
partial	bool	Return a partial style (not combined with parent).	False

Returns:

Type	Description
Style	A Rich style object.

get_content_height

get_content_height(container, viewport, width)

Called by Textual to get the height of the content area. May be overridden in a subclass.

Parameters:

Name	Type	Description	Default
container	Size	Size of the container (immediate parent) widget.	required
viewport	Size	Size of the viewport.	required
width	int	Width of renderable.	required

Returns:

Type	Description
int	The height of the content.

get_content_width

get_content_width(container, viewport)

Called by textual to get the width of the content area. May be overridden in a subclass.

Parameters:

Name	Type	Description	Default
container	Size	Size of the container (immediate parent) widget.	required
viewport	Size	Size of the viewport.	required

Returns:

Type	Description
int	The optimal width of the content.

get_loading_widget

get_loading_widget()

Get a widget to display a loading indicator.

The default implementation will defer to App.get_loading_widget.

Returns:

Type	Description
Widget	A widget in place of this widget to indicate a loading.

get_pseudo_class_state

get_pseudo_class_state()

Get an object describing whether each pseudo class is present on this object or not.

Returns:

Type	Description
PseudoClasses	A PseudoClasses object describing the pseudo classes that are present.

get_style_at

get_style_at(x, y)

Get the Rich style in a widget at a given relative offset.

Parameters:

Name	Type	Description	Default
x	int	X coordinate relative to the widget.	required
y	int	Y coordinate relative to the widget.	required

Returns:

Type	Description
Style	A rich Style object.

get_visual_style

get_visual_style(component_classes)

Get the visual style for the widget, including any component styles.

Parameters:

Name	Type	Description	Default
component_classes	Iterable[str]	Optional component styles.	required

Returns:

Type	Description
Style	A Visual style instance.

get_widget_by_id

get_widget_by_id(id: str) -> Widget

get_widget_by_id(
    id: str, expect_type: type[ExpectType]
) -> ExpectType

get_widget_by_id(id, expect_type=None)

Return the first descendant widget with the given ID.

Performs a depth-first search rooted at this widget.

Parameters:

Name	Type	Description	Default
id	str	The ID to search for in the subtree.	required
expect_type	type[ExpectType] | None	Require the object be of the supplied type, or None for any type.	None

Returns:

Type	Description
ExpectType | Widget	The first descendant encountered with this ID.

Raises:

Type	Description
NoMatches	if no children could be found for this ID.
WrongType	if the wrong type was found.

mount

mount(*widgets, before=None, after=None)

Mount widgets below this widget (making this widget a container).

Parameters:

Name	Type	Description	Default
*widgets	Widget	The widget(s) to mount.	()
before	int | str | Widget | None	Optional location to mount before. An int is the index of the child to mount before, a str is a query_one query to find the widget to mount before.	None
after	int | str | Widget | None	Optional location to mount after. An int is the index of the child to mount after, a str is a query_one query to find the widget to mount after.	None

Returns:

Type	Description
AwaitMount	An awaitable object that waits for widgets to be mounted.

Raises:

Type	Description
MountError	If there is a problem with the mount request.

Note

Only one of before or after can be provided. If both are provided a MountError will be raised.

mount_all

mount_all(widgets, *, before=None, after=None)

Mount widgets from an iterable.

Parameters:

Name	Type	Description	Default
widgets	Iterable[Widget]	An iterable of widgets.	required
before	int | str | Widget | None	Optional location to mount before. An int is the index of the child to mount before, a str is a query_one query to find the widget to mount before.	None
after	int | str | Widget | None	Optional location to mount after. An int is the index of the child to mount after, a str is a query_one query to find the widget to mount after.	None

Returns:

Type	Description
AwaitMount	An awaitable object that waits for widgets to be mounted.

Raises:

Type	Description
MountError	If there is a problem with the mount request.

Note

Only one of before or after can be provided. If both are provided a MountError will be raised.

mount_composed_widgets async

mount_composed_widgets(widgets)

Called by Textual to mount widgets after compose.

There is generally no need to implement this method in your application. See Lazy for a class which uses this method to implement lazy mounting.

Parameters:

Name	Type	Description	Default
widgets	list[Widget]	A list of child widgets.	required

move_child

move_child(
    child: int | Widget,
    *,
    before: int | Widget,
    after: None = None
) -> None

move_child(
    child: int | Widget,
    *,
    after: int | Widget,
    before: None = None
) -> None

move_child(child, *, before=None, after=None)

Move a child widget within its parent's list of children.

Parameters:

Name	Type	Description	Default
child	int | Widget	The child widget to move.	required
before	int | Widget | None	Child widget or location index to move before.	None
after	int | Widget | None	Child widget or location index to move after.	None

Raises:

Type	Description
WidgetError	If there is a problem with the child or target.

Note

Only one of before or after can be provided. If neither or both are provided a WidgetError will be raised.

notify

notify(
    message,
    *,
    title="",
    severity="information",
    timeout=None
)

Create a notification.

Tip

This method is thread-safe.

Parameters:

Name	Type	Description	Default
message	str	The message for the notification.	required
title	str	The title for the notification.	''
severity	SeverityLevel	The severity of the notification.	'information'
timeout	float | None	The timeout (in seconds) for the notification, or None for default.	None

See App.notify for the full documentation for this method.

on_prune async

on_prune(event)

Close message loop when asked to prune.

post_message

post_message(message)

Post a message to this widget.

Parameters:

Name	Type	Description	Default
message	Message	Message to post.	required

Returns:

Type	Description
bool	True if the message was posted, False if this widget was closed / closing.

post_render

post_render(renderable, base_style)

Applies style attributes to the default renderable.

This method is called by Textual itself. It is unlikely you will need to call or implement this method.

Returns:

Type	Description
ConsoleRenderable	A new renderable.

pre_layout

pre_layout(layout)

This method id called prior to a layout operation.

Implement this method if you want to make updates that should impact the layout.

Parameters:

Name	Type	Description	Default
layout	Layout	The Layout instance that will be used to arrange this widget's children.	required

recompose async

recompose()

Recompose the widget.

Recomposing will remove children and call self.compose again to remount.

refresh

refresh(
    *regions, repaint=True, layout=False, recompose=False
)

Initiate a refresh of the widget.

This method sets an internal flag to perform a refresh, which will be done on the next idle event. Only one refresh will be done even if this method is called multiple times.

By default this method will cause the content of the widget to refresh, but not change its size. You can also set layout=True to perform a layout.

Warning

It is rarely necessary to call this method explicitly. Updating styles or reactive attributes will do this automatically.

Parameters:

Name	Type	Description	Default
*regions	Region	Additional screen regions to mark as dirty.	()
repaint	bool	Repaint the widget (will call render() again).	True
layout	bool	Also layout widgets in the view.	False
recompose	bool	Re-compose the widget (will remove and re-mount children).	False

Returns:

Type	Description
Self	The Widget instance.

release_mouse

release_mouse()

Release the mouse.

Mouse events will only be sent when the mouse is over the widget.

remove

remove()

Remove the Widget from the DOM (effectively deleting it).

Returns:

Type	Description
AwaitRemove	An awaitable object that waits for the widget to be removed.

remove_children

remove_children(selector='*')

Remove the immediate children of this Widget from the DOM.

Parameters:

Name	Type	Description	Default
selector	str | type[QueryType] | Iterable[Widget]	A CSS selector or iterable of widgets to remove.	'*'

Returns:

Type	Description
AwaitRemove	An awaitable object that waits for the direct children to be removed.

render

render()

Get text or Rich renderable for this widget.

Implement this for custom widgets.

Example

from textual.app import RenderableType
from textual.widget import Widget

class CustomWidget(Widget):
    def render(self) -> RenderableType:
        return "Welcome to [bold red]Textual[/]!"

Returns:

Type	Description
RenderResult	Any renderable.

render_line

render_line(y)

Render a line of content.

Parameters:

Name	Type	Description	Default
y	int	Y Coordinate of line.	required

Returns:

Type	Description
Strip	A rendered line.

render_lines

render_lines(crop)

Render the widget in to lines.

Parameters:

Name	Type	Description	Default
crop	Region	Region within visible area to render.	required

Returns:

Type	Description
list[Strip]	A list of list of segments.

render_str

render_str(text_content)

Convert str in to a Text object.

If you pass in an existing Text object it will be returned unaltered.

Parameters:

Name	Type	Description	Default
text_content	str | Text	Text or str.	required

Returns:

Type	Description
Text	A text object.

run_action async

run_action(action)

Perform a given action, with this widget as the default namespace.

Parameters:

Name	Type	Description	Default
action	str	Action encoded as a string.	required

scroll_down

scroll_down(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll one line down.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

scroll_end

scroll_end(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False,
    x_axis=True,
    y_axis=True
)

Scroll to the end of the container.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False
x_axis	bool	Allow scrolling on X axis?	True
y_axis	bool	Allow scrolling on Y axis?	True

scroll_home

scroll_home(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False,
    x_axis=True,
    y_axis=True
)

Scroll to home position.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False
x_axis	bool	Allow scrolling on X axis?	True
y_axis	bool	Allow scrolling on Y axis?	True

scroll_left

scroll_left(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll one cell left.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

scroll_page_down

scroll_page_down(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic"
)

Scroll one page down.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'

scroll_page_left

scroll_page_left(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic"
)

Scroll one page left.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'

scroll_page_right

scroll_page_right(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic"
)

Scroll one page right.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'

scroll_page_up

scroll_page_up(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic"
)

Scroll one page up.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'

scroll_relative

scroll_relative(
    x=None,
    y=None,
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll relative to current position.

Parameters:

Name	Type	Description	Default
x	float | None	X distance (columns) to scroll, or None for no change.	None
y	float | None	Y distance (rows) to scroll, or None for no change.	None
animate	bool	Animate to new scroll position.	True
speed	float | None	Speed of scroll if animate is True. Or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

scroll_right

scroll_right(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll one cell right.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

scroll_to

scroll_to(
    x=None,
    y=None,
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll to a given (absolute) coordinate, optionally animating.

Parameters:

Name	Type	Description	Default
x	float | None	X coordinate (column) to scroll to, or None for no change.	None
y	float | None	Y coordinate (row) to scroll to, or None for no change.	None
animate	bool	Animate to new scroll position.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

Note

The call to scroll is made after the next refresh.

scroll_to_center

scroll_to_center(
    widget,
    animate=True,
    *,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    origin_visible=True,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll this widget to the center of self.

The center of the widget will be scrolled to the center of the container.

Parameters:

Name	Type	Description	Default
widget	Widget	The widget to scroll to the center of self.	required
animate	bool	Whether to animate the scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
origin_visible	bool	Ensure that the top left corner of the widget remains visible after the scroll.	True
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

scroll_to_region

scroll_to_region(
    region,
    *,
    spacing=None,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    center=False,
    top=False,
    origin_visible=True,
    force=False,
    on_complete=None,
    level="basic",
    x_axis=True,
    y_axis=True,
    immediate=False
)

Scrolls a given region in to view, if required.

This method will scroll the least distance required to move region fully within the scrollable area.

Parameters:

Name	Type	Description	Default
region	Region	A region that should be visible.	required
spacing	Spacing | None	Optional spacing around the region.	None
animate	bool	True to animate, or False to jump.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
top	bool	Scroll region to top of container.	False
origin_visible	bool	Ensure that the top left of the widget is within the window.	True
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
x_axis	bool	Allow scrolling on X axis?	True
y_axis	bool	Allow scrolling on Y axis?	True
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

Returns:

Type	Description
Offset	The distance that was scrolled.

scroll_to_widget

scroll_to_widget(
    widget,
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    center=False,
    top=False,
    origin_visible=True,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll scrolling to bring a widget in to view.

Parameters:

Name	Type	Description	Default
widget	Widget	A descendant widget.	required
animate	bool	True to animate, or False to jump.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
top	bool	Scroll widget to top of container.	False
origin_visible	bool	Ensure that the top left of the widget is within the window.	True
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

Returns:

Type	Description
bool	True if any scrolling has occurred in any descendant, otherwise False.

scroll_up

scroll_up(
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll one line up.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

scroll_visible

scroll_visible(
    animate=True,
    *,
    speed=None,
    duration=None,
    top=False,
    easing=None,
    force=False,
    on_complete=None,
    level="basic",
    immediate=False
)

Scroll the container to make this widget visible.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
top	bool	Scroll to top of container.	False
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False
on_complete	CallbackType | None	A callable to invoke when the animation is finished.	None
level	AnimationLevel	Minimum level required for the animation to take place (inclusive).	'basic'
immediate	bool	If False the scroll will be deferred until after a screen refresh, set to True to scroll immediately.	False

set_loading

set_loading(loading)

Set or reset the loading state of this widget.

A widget in a loading state will display a LoadingIndicator that obscures the widget.

Parameters:

Name	Type	Description	Default
loading	bool	True to put the widget into a loading state, or False to reset the loading state.	required

Returns:

Type	Description
None	An optional awaitable.

set_scroll

set_scroll(x, y)

Set the scroll position without any validation.

This is a low-level method for when you want to see the scroll position in the next frame. For a more fully featured method, see scroll_to.

Parameters:

Name	Type	Description	Default
x	float | None	Desired X coordinate.	required
y	float | None	Desired Y coordinate.	required

stop_animation async

stop_animation(attribute, complete=True)

Stop an animation on an attribute.

Parameters:

Name	Type	Description	Default
attribute	str	Name of the attribute whose animation should be stopped.	required
complete	bool	Should the animation be set to its final value?	True

Note

If there is no animation scheduled or running, this is a no-op.

suppress_click

suppress_click()

Suppress a click event.

This will prevent a Click event being sent, if called after a mouse down event and before the click itself.

watch_disabled

watch_disabled(disabled)

Update the styles of the widget and its children when disabled is toggled.

watch_has_focus

watch_has_focus(value)

Update from CSS if has focus state changes.

watch_mouse_hover

watch_mouse_hover(value)

Update from CSS if mouse over state changes.

with_tooltip

with_tooltip(tooltip)

Chainable method to set a tooltip.

Example

def compose(self) -> ComposeResult:
    yield Label("Hello").with_tooltip("A greeting")

Parameters:

Name	Type	Description	Default
tooltip	RenderableType | None	New tooltip, or None to clear the tooltip.	required

Returns:

Type	Description
Self	Self.

WidgetError

Bases: Exception

Base widget error.