Widgets

In this chapter we will explore widgets in more detail, and how you can create custom widgets of your own.

What is a widget?

A widget is a component of your UI responsible for managing a rectangular region of the screen. Widgets may respond to events in much the same way as an app. In many respects, widgets are like mini-apps.

Information

Every widget runs in its own asyncio task.

Custom widgets

There is a growing collection of builtin widgets in Textual, but you can build entirely custom widgets that work in the same way.

The first step in building a widget is to import and extend a widget class. This can either be Widget which is the base class of all widgets, or one of its subclasses.

Let's create a simple custom widget to display a greeting.

hello01.py

from textual.app import App, ComposeResult, RenderResult
from textual.widget import Widget


class Hello(Widget):
    """Display a greeting."""

    def render(self) -> RenderResult:
        return "Hello, [b]World[/b]!"


class CustomApp(App):
    def compose(self) -> ComposeResult:
        yield Hello()


if __name__ == "__main__":
    app = CustomApp()
    app.run()

The highlighted lines define a custom widget class with just a render() method. Textual will display whatever is returned from render in the content area of your widget.

Note that the text contains tags in square brackets, i.e. [b]. This is