Skip to content

Widget

Bases: DOMNode

A Widget is the base class for Textual widgets.

See also static for starting point for your own widgets.

Widget will highlight links automatically.

can_focus: bool = False class-attribute

Widget may receive focus.

can_focus_children: bool = True class-attribute

Widget's children may receive focus.

expand = Reactive(False) class-attribute

Rich renderable may expand.

shrink = Reactive(True) class-attribute

Rich renderable may shrink.

action(action) async

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

Parameters:

Name Type Description Default
action str

Action encoded as a string.

required

allow_horizontal_scroll() property

Check if horizontal scroll is permitted.

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

Returns:

Name Type Description
bool bool

True if the widget may scroll horizontally.

allow_vertical_scroll() property

Check if vertical scroll is permitted.

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

Returns:

Name Type Description
bool bool

True if the widget may scroll vertically.

animate(attribute, value, *, final_value=Ellipsis, duration=None, speed=None, delay=0.0, easing=DEFAULT_EASING, on_complete=None)

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.

Ellipsis
duration float | None

The duration of the animate. Defaults to None.

None
speed float | None

The speed of the animation. Defaults to None.

None
delay float

A delay (in seconds) before the animation starts. Defaults to 0.0.

0.0
easing EasingFunction | str

An easing method. Defaults to "in_out_cubic".

DEFAULT_EASING
on_complete CallbackType | None

A callable to invoke when the animation is finished. Defaults to None.

None

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. Defaults to True.

True

compose()

Called by Textual to create child widgets.

Extend this to build a UI.

Example
def compose(self) -> ComposeResult:
    yield Header()
    yield Container(
        TreeControl(), Viewer()
    )
    yield Footer()

container_size() property

The size of the container (parent widget).

Returns:

Name Type Description
Size Size

Container size.

container_viewport() property

The viewport region (parent window).

Returns:

Name Type Description
Region Region

The region that contains this widget.

content_offset() property

An offset from the Widget origin where the content begins.

Returns:

Name Type Description
Offset Offset

Offset from widget's origin.

content_region() property

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

Returns:

Name Type Description
Region Region

Screen region that contains a widget's content.

content_size() property

Get the size of the content area.

focus(scroll_visible=True)

Give focus to this widget.

Parameters:

Name Type Description Default
scroll_visible bool

Scroll parent to make this widget visible. Defaults to True.

True

focusable_children() property

Get the children which may be focused.

Returns:

Type Description
list[Widget]

list[Widget]: List of widgets that can receive focus.

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 | None

Require the object be of the supplied type, or None for any type. Defaults to None.

None

Returns:

Type Description
ExpectType | Widget

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_component_rich_style(name, *, partial=False)

Get a Rich style for a component.

Parameters:

Name Type Description Default
name str

Name of component.

required
partial bool

Return a partial style (not combined with parent).

False

Returns:

Name Type Description
Style Style

A Rich style object.

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:

Name Type Description
int int

The height of the content.

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:

Name Type Description
int int

The optimal width of the content.

get_pseudo_classes()

Pseudo classes for a widget.

Returns:

Type Description
Iterable[str]

Iterable[str]: Names of the pseudo classes.

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:

Name Type Description
Style Style

A rich Style object.

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 | None

Require the object be of the supplied type, or None for any type. Defaults to None.

None

Returns:

Type Description
ExpectType | Widget

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.

gutter() property

Spacing for padding / border / scrollbars.

Returns:

Name Type Description
Spacing Spacing

Additional spacing around content area.

horizontal_scrollbar() property

Get a vertical scrollbar (create if necessary).

Returns:

Name Type Description
ScrollBar ScrollBar

ScrollBar Widget.

is_container() property

Check if this widget is a container (contains other widgets).

Returns:

Name Type Description
bool bool

True if this widget is a container.

is_scrollable() property

Check if this Widget may be scrolled.

Returns:

Name Type Description
bool bool

True if this widget may be scrolled.

is_transparent() property

Check if the background styles is not set.

Returns:

Name Type Description
bool bool

True if there is background color, otherwise False.

layer() property

Get the name of this widgets layer.

Returns:

Name Type Description
str str

Name of layer.

layers() property

Layers of from parent.

Returns:

Type Description
tuple[str, ...]

tuple[str, ...]: Tuple of layer names.

Style of links with mouse hover.

Style of links.

max_scroll_x() property

The maximum value of scroll_x.

max_scroll_y() property

The maximum value of scroll_y.

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

Optional location to mount before.

None
after int | str | Widget

Optional location to mount after.

None

Returns:

Name Type Description
AwaitMount 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.

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

(int | Widget, optional): Optional location to move before.

None
after int | Widget | None

(int | Widget, optional): Optional location 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.

offset() property writable

Widget offset from origin.

Returns:

Name Type Description
Offset Offset

Relative offset.

outer_size() property

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

Returns:

Name Type Description
Size Size

Outer size.

post_message(message) async

Post a message to this widget.

Parameters:

Name Type Description Default
message Message

Message to post.

required

Returns:

Name Type Description
bool bool

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

post_render(renderable)

Applies style attributes to the default renderable.

Returns:

Name Type Description
RenderableType ConsoleRenderable

A new renderable.

refresh(*regions, repaint=True, layout=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). Defaults to True.

True
layout bool

Also layout widgets in the view. Defaults to False.

False

region() property

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

Raises:

Type Description
NoScreen

If there is no screen.

errors.NoWidget

If the widget is not on the screen.

Returns:

Name Type Description
Region Region

Region within screen occupied by widget.

release_mouse()

Release the mouse.

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

remove()

Remove the Widget from the DOM (effectively deleting it)

Returns:

Name Type Description
AwaitRemove AwaitRemove

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

render()

Get renderable for widget.

Returns:

Name Type Description
RenderableType RenderableType

Any renderable

render_line(y)

Render a line of content.

Parameters:

Name Type Description Default
y int

Y Coordinate of line.

required

Returns:

Type Description
list[Segment]

list[Segment]: A rendered line.

render_lines(crop)

Render the widget in to lines.

Parameters:

Name Type Description Default
crop Region

Region within visible area to render.

required

Returns:

Name Type Description
Lines Lines

A list of list of segments.

reset_focus()

Reset the focus (move it to the next available widget).

scroll_down(*, animate=True, speed=None, duration=None, easing=None)

Scroll one line down.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_end(*, animate=True, speed=None, duration=None, easing=None)

Scroll to the end of the container.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_home(*, animate=True, speed=None, duration=None, easing=None)

Scroll to home position.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_left(*, animate=True, speed=None, duration=None, easing=None)

Scroll one cell left.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_offset() property

Get the current scroll offset.

Returns:

Name Type Description
Offset Offset

Offset a container has been scrolled by.

scroll_page_down(*, animate=True, speed=None, duration=None, easing=None)

Scroll one page down.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_page_left(*, animate=True, speed=None, duration=None, easing=None)

Scroll one page left.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_page_right(*, animate=True, speed=None, duration=None, easing=None)

Scroll one page right.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_page_up(*, animate=True, speed=None, duration=None, easing=None)

Scroll one page up.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_relative(x=None, y=None, *, animate=True, speed=None, duration=None, easing=None)

Scroll relative to current position.

Parameters:

Name Type Description Default
x int | None

X distance (columns) to scroll, or None for no change. Defaults to None.

None
y int | None

Y distance (rows) to scroll, or None for no change. Defaults to None.

None
animate bool

Animate to new scroll position. Defaults to False.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if the scroll position changed, otherwise False.

scroll_right(*, animate=True, speed=None, duration=None, easing=None)

Scroll on cell right.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_to(x=None, y=None, *, animate=True, speed=None, duration=None, easing=None)

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

Parameters:

Name Type Description Default
x int | None

X coordinate (column) to scroll to, or None for no change. Defaults to None.

None
y int | None

Y coordinate (row) to scroll to, or None for no change. Defaults to None.

None
animate bool

Animate to new scroll position. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if the scroll position changed, otherwise False.

scroll_to_region(region, *, spacing=None, animate=True, speed=None, duration=None, easing=None, top=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. Defaults to None.

None
animate bool

True to animate, or False to jump. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None
top bool

Scroll region to top of container. Defaults to False.

False

Returns:

Name Type Description
Offset Offset

The distance that was scrolled.

scroll_to_widget(widget, *, animate=True, speed=None, duration=None, easing=None, top=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. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None
top bool

Scroll widget to top of container. Defaults to False.

False

Returns:

Name Type Description
bool bool

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

scroll_up(*, animate=True, speed=None, duration=None, easing=None)

Scroll one line up.

Parameters:

Name Type Description Default
animate bool

Animate scroll. Defaults to True.

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. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

Returns:

Name Type Description
bool bool

True if any scrolling was done.

scroll_visible(animate=True, *, speed=None, duration=None, top=False, easing=None)

Scroll the container to make this widget visible.

Parameters:

Name Type Description Default
animate bool

description. Defaults to True.

True
speed float | None

description. Defaults to None.

None
duration float | None

description. Defaults to None.

None
top bool

Scroll to top of container. Defaults to False.

False
easing EasingFunction | str | None

An easing method for the scrolling animation. Defaults to "None", which will result in Textual choosing the configured default scrolling easing function.

None

scrollable_content_region() property

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

Returns:

Name Type Description
Region Region

Screen region that contains a widget's content.

scrollbar_corner() property

Return the ScrollBarCorner - the cells that appear between the horizontal and vertical scrollbars (only when both are visible).

scrollbar_gutter() property

Spacing required to fit scrollbar(s).

Returns:

Name Type Description
Spacing Spacing

Scrollbar gutter spacing.

scrollbar_size_horizontal() property

Get the height used by the horizontal scrollbar.

Returns:

Name Type Description
int int

Number of rows in the horizontal scrollbar.

scrollbar_size_vertical() property

Get the width used by the vertical scrollbar.

Returns:

Name Type Description
int int

Number of columns in the vertical scrollbar.

scrollbars_enabled() property

A tuple of booleans that indicate if scrollbars are enabled.

Returns:

Type Description
tuple[bool, bool]

tuple[bool, bool]: A tuple of (, )

siblings() property

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

Returns:

Type Description
list[Widget]

list[Widget]: A list of siblings.

size() property

The size of the content area.

Returns:

Name Type Description
Size Size

Content area size.

vertical_scrollbar() property

Get a vertical scrollbar (create if necessary).

Returns:

Name Type Description
ScrollBar ScrollBar

ScrollBar Widget.

virtual_region() property

The widget region relative to it's container. Which may not be visible, depending on scroll offset.

virtual_region_with_margin() property

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

Returns:

Name Type Description
Region Region

The virtual region of the Widget, inclusive of its margin.

visible_siblings() property

A list of siblings which will be shown.

Returns:

Type Description
list[Widget]

list[Widget]: List of siblings.

watch_has_focus(value)

Update from CSS if has focus state changes.

watch_mouse_over(value)

Update from CSS if mouse over state changes.

window_region() property

The region within the scrollable area that is currently visible.

Returns:

Name Type Description
Region Region

New region.