Skip to content

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 = 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 = 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_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_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

Style of links.

Returns:

Type Description
Style

Rich style.

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_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)

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.

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.