Skip to content

Dom node

A DOMNode is a base class for any object within the Textual Document Object Model, which includes all Widgets, Screens, and Apps.

WalkMethod module-attribute

WalkMethod: TypeAlias = Literal['depth', 'breadth']

Valid walking methods for the DOMNode.walk_children method.

BadIdentifier class

Bases: Exception

Exception raised if you supply a id attribute or class name in the wrong format.

DOMError class

Bases: Exception

Base exception class for errors relating to the DOM.

DOMNode class

def __init__(self, *, name=None, id=None, classes=None):

Bases: MessagePump

The base class for object that can be in the Textual DOM (App and Widget)

SCOPED_CSS class-attribute

SCOPED_CSS: bool = True

Should default css be limited to the widget type?

ancestors property

ancestors: list[DOMNode]

A list of ancestor nodes found by tracing a path all the way back to App.

Returns
Type Description
list[DOMNode]

A list of nodes.

ancestors_with_self property

ancestors_with_self: list[DOMNode]

A list of ancestor nodes found by tracing a path all the way back to App.

Note

This is inclusive of self.

Returns
Type Description
list[DOMNode]

A list of nodes.

auto_refresh property writable

auto_refresh: float | None

Number of seconds between automatic refresh, or None for no automatic refresh.

background_colors property

background_colors: tuple[Color, Color]

The background color and the color of the parent's background.

Returns
Type Description
tuple[Color, Color]

(<background color>, <color>)

children property

children: Sequence['Widget']

A view on to the children.

Returns
Type Description
Sequence['Widget']

The node's children.

classes instance-attribute class-attribute

classes = _ClassesDescriptor()

CSS class names for this node.

colors property

colors: tuple[Color, Color, Color, Color]

The widget's background and foreground colors, and the parent's background and foreground colors.

Returns
Type Description
tuple[Color, Color, Color, Color]

(<parent background>, <parent color>, <background>, <color>)

css_identifier property

css_identifier: str

A CSS selector that identifies this DOM node.

css_identifier_styled property

css_identifier_styled: Text

A syntax highlighted CSS identifier.

Returns
Type Description
Text

A Rich Text object.

css_path_nodes property

css_path_nodes: list[DOMNode]

A list of nodes from the App to this node, forming a "path".

Returns
Type Description
list[DOMNode]

A list of nodes, where the first item is the App, and the last is this node.

css_tree property

css_tree: Tree

A Rich tree to display the DOM, annotated with the node's CSS.

Log this to visualize your app in the textual console.

Example
self.log(self.css_tree)
Returns
Type Description
Tree

A Tree renderable.

display property writable

display: bool

Should the DOM node be displayed?

May be set to a boolean to show or hide the node, or to any valid value for the display rule.

Example
my_widget.display = False  # Hide my_widget

displayed_children property

displayed_children: list[Widget]

The child nodes which will be displayed.

Returns
Type Description
list[Widget]

A list of nodes.

id property writable

id: str | None

The ID of this node, or None if the node has no ID.

is_modal property

is_modal: bool

Is the node a modal?

name property

name: str | None

The name of the node.

parent property

parent: DOMNode | None

The parent node.

All nodes have parent once added to the DOM, with the exception of the App which is the root node.

pseudo_classes property

pseudo_classes: frozenset[str]

A (frozen) set of all pseudo classes.

rich_style property

rich_style: Style

Get a Rich Style object for this DOMNode.

Returns
Type Description
Style

A Rich style.

screen property

screen: 'Screen[object]'

The screen containing this node.

Returns
Type Description
'Screen[object]'

A screen object.

Raises
Type Description
NoScreen

If this node isn't mounted (and has no screen).

text_style property

text_style: Style

Get the text style object.

A widget's style is influenced by its parent. for instance if a parent is bold, then the child will also be bold.

Returns
Type Description
Style

A Rich Style.

tree property

tree: Tree

A Rich tree to display the DOM.

Log this to visualize your app in the textual console.

Example
self.log(self.tree)
Returns
Type Description
Tree

A Tree renderable.

visible property writable

visible: bool

Is this widget visible in the DOM?

If a widget hasn't had its visibility set explicitly, then it inherits it from its DOM ancestors.

This may be set explicitly to override inherited values. The valid values include the valid values for the visibility rule and the booleans True or False, to set the widget to be visible or invisible, respectively.

When a node is invisible, Textual will reserve space for it, but won't display anything.

workers property

workers: WorkerManager

The app's worker manager. Shortcut for self.app.workers.

action_toggle async

def action_toggle(self, attribute_name):

Toggle an attribute on the node.

Assumes the attribute is a bool.

Parameters
Parameter Default Description
attribute_name
str
required

Name of the attribute.

add_class method

def add_class(self, *class_names, update=True):

Add class names to this Node.

Parameters
Parameter Default Description
*class_names
str
()

CSS class names to add.

update
bool
True

Also update styles.

Returns
Type Description
Self

Self.

data_bind method

def data_bind(self, *reactives, **bind_vars):

Bind reactive data so that changes to a reactive automatically change the reactive on another widget.

Reactives may be given as positional arguments or keyword arguments. See the guide on data binding.

Example
def compose(self) -> ComposeResult:
    yield WorldClock("Europe/London").data_bind(WorldClockApp.time)
    yield WorldClock("Europe/Paris").data_bind(WorldClockApp.time)
    yield WorldClock("Asia/Tokyo").data_bind(WorldClockApp.time)
Raises
Type Description
ReactiveError

If the data wasn't bound.

Returns
Type Description
Self

Self.

get_component_styles method

def get_component_styles(self, name):

Get a "component" styles object (must be defined in COMPONENT_CLASSES classvar).

Parameters
Parameter Default Description
name
str
required

Name of the component.

Raises
Type Description
KeyError

If the component class doesn't exist.

Returns
Type Description
RenderStyles

A Styles object.

get_pseudo_classes method

def get_pseudo_classes(self):

Get any pseudo classes applicable to this Node, e.g. hover, focus.

Returns
Type Description
Iterable[str]

Iterable of strings, such as a generator.

has_class method

def has_class(self, *class_names):

Check if the Node has all the given class names.

Parameters
Parameter Default Description
*class_names
str
()

CSS class names to check.

Returns
Type Description
bool

True if the node has all the given class names, otherwise False.

has_pseudo_class method

def has_pseudo_class(self, class_name):

Check the node has the given pseudo class.

Parameters
Parameter Default Description
class_name
str
required

The pseudo class to check for.

Returns
Type Description
bool

True if the DOM node has the pseudo class, False if not.

has_pseudo_classes method

def has_pseudo_classes(self, class_names):

Check the node has all the given pseudo classes.

Parameters
Parameter Default Description
class_names
set[str]
required

Set of class names to check for.

Returns
Type Description
bool

True if all pseudo class names are present.

notify_style_update method

def notify_style_update(self):

Called after styles are updated.

Implement this in a subclass if you want to clear any cached data when the CSS is reloaded.

query method

def query(self, selector=None):

Query the DOM for children that match a selector or widget type.

Parameters
Parameter Default Description
selector
str | type[QueryType] | None
None

A CSS selector, widget type, or None for all nodes.

Returns
Type Description
DOMQuery[Widget] | DOMQuery[QueryType]

A query object.

query_one method

def query_one(self, selector, expect_type=None):

Get a widget from this widget's children that matches a selector or widget type.

Parameters
Parameter Default Description
selector
str | type[QueryType]
required

A selector or widget type.

expect_type
type[QueryType] | None
None

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

Raises
Type Description
WrongType

If the wrong type was found.

NoMatches

If no node matches the query.

TooManyMatches

If there is more than one matching node in the query.

Returns
Type Description
QueryType | Widget

A widget matching the selector.

remove_class method

def remove_class(self, *class_names, update=True):

Remove class names from this Node.

Parameters
Parameter Default Description
*class_names
str
()

CSS class names to remove.

update
bool
True

Also update styles.

Returns
Type Description
Self

Self.

reset_styles method

def reset_styles(self):

Reset styles back to their initial state.

run_worker method

def run_worker(
    self,
    work,
    name="",
    group="default",
    description="",
    exit_on_error=True,
    start=True,
    exclusive=False,
    thread=False,
):

Run work in a worker.

A worker runs a function, coroutine, or awaitable, in the background as an async task or as a thread.

Parameters
Parameter Default Description
work
WorkType[ResultType]
required

A function, async function, or an awaitable object to run in a worker.

name
str | None
''

A short string to identify the worker (in logs and debugging).

group
str
'default'

A short string to identify a group of workers.

description
str
''

A longer string to store longer information on the worker.

exit_on_error
bool
True

Exit the app if the worker raises an error. Set to False to suppress exceptions.

start
bool
True

Start the worker immediately.

exclusive
bool
False

Cancel all workers in the same group.

thread
bool
False

Mark the worker as a thread worker.

Returns
Type Description
Worker[ResultType]

New Worker instance.

set_class method

def set_class(self, add, *class_names, update=True):

Add or remove class(es) based on a condition.

Parameters
Parameter Default Description
add
bool
required

Add the classes if True, otherwise remove them.

update
bool
True

Also update styles.

Returns
Type Description
Self

Self.

set_classes method

def set_classes(self, classes):

Replace all classes.

Parameters
Parameter Default Description
classes
str | Iterable[str]
required

A string containing space separated classes, or an iterable of class names.

Returns
Type Description
Self

Self.

set_reactive method

def set_reactive(self, reactive, value):

Sets a reactive value without invoking validators or watchers.

Example
self.set_reactive(App.dark_mode, True)
Parameters
Parameter Default Description
name
required

Name of reactive attribute.

value
ReactiveType
required

New value of reactive.

Raises
Type Description
AttributeError

If the first argument is not a reactive.

set_styles method

def set_styles(self, css=None, **update_styles):

Set custom styles on this object.

Parameters
Parameter Default Description
css
str | None
None

Styles in CSS format.

update_styles
Any
{}

Keyword arguments map style names onto style values.

Returns
Type Description
Self

Self.

toggle_class method

def toggle_class(self, *class_names):

Toggle class names on this Node.

Parameters
Parameter Default Description
*class_names
str
()

CSS class names to toggle.

Returns
Type Description
Self

Self.

walk_children method

def walk_children(
    self,
    filter_type=None,
    *,
    with_self=False,
    method="depth",
    reverse=False
):

Walk the subtree rooted at this node, and return every descendant encountered in a list.

Parameters
Parameter Default Description
filter_type
type[WalkType] | None
None

Filter only this type, or None for no filter.

with_self
bool
False

Also yield self in addition to descendants.

method
WalkMethod
'depth'

One of "depth" or "breadth".

reverse
bool
False

Reverse the order (bottom up).

Returns
Type Description
list[DOMNode] | list[WalkType]

A list of nodes.

watch method

def watch(self, obj, attribute_name, callback, init=True):

Watches for modifications to reactive attributes on another object.

Example

Here's how you could detect when the app changes from dark to light mode (and vice versa).

def on_dark_change(old_value:bool, new_value:bool):
    # Called when app.dark changes.
    print("App.dark when from {old_value} to {new_value}")

self.watch(self.app, "dark", self.on_dark_change, init=False)
Parameters
Parameter Default Description
obj
DOMNode
required

Object containing attribute to watch.

attribute_name
str
required

Attribute to watch.

callback
WatchCallbackType
required

A callback to run when attribute changes.

init
bool
True

Check watchers on first call.

NoScreen class

Bases: DOMError

Raised when the node has no associated screen.

check_identifiers function

def check_identifiers(description, *names):

Validate identifier and raise an error if it fails.

Parameters
Parameter Default Description
description
str
required

Description of where identifier is used for error message.

*names
str
()

Identifiers to check.