Python Textual: Build Beautiful UIs in the Terminal

Checking the Textual Installation

The textual package is now installed in your Python virtual environment. You can check your installation by running the following command:

(venv) $ python -m textual

You should see the Textual demo app, a nicely formatted TUI application that displays useful information about Textual’s capabilities. You can interact with it using the mouse or keys:

Notice the colored text, emojis, structured layout, and the keyboard shortcuts listed in the window footer. There’s a lot to explore here, but for now, you’re going to dive right in and create your first app using Textual. You can close the demo by pressing Ctrl+C.

Getting to Know Textual

Textual is an application framework that provides classes and services for building fully-fledged applications. Its event-driven programming model lets you define callbacks for various events, such as key presses, mouse clicks, and timer ticks.

You can also define actions, which are functions that the user can call using a keystroke, or by clicking a text link. Events and actions let you build interactive TUIs.

Key features of Textual include:

• Rich widget library: Offers a comprehensive set of widgets such as buttons, inputs, checkboxes, switches, and more, allowing you to build interactive interfaces efficiently.

• Flexible layout management: Provides various layout options, including docking and grid systems, allowing you to design complex interfaces that adapt to different terminal sizes.

• Reactive attributes: Supports reactive programming, enabling the creation of dynamic interfaces that respond seamlessly to changes in application state.

• CSS styling: Uses a CSS-like syntax to customize widget appearance and behavior, which allows for customization of the appearance and behavior of widgets to match specific design requirements.

• Asynchronous event handling: Built on Python’s asyncio, it efficiently manages asynchronous events, ensuring responsive user interactions even in I/O-bound applications.

• Command palette: Includes a command palette with fuzzy search capabilities, enhancing user navigation and command execution within the application.

• Accessibility features: Designed with accessibility in mind, offering integration with screen readers, monochrome mode, high-contrast themes, and color-blind themes to accommodate diverse user needs.

• Cross-platform compatibility: Runs on various platforms, including Windows, macOS, and Linux, ensuring broad usability across different operating systems.

• Remote application support: Enables applications to run over SSH, making it easier to manage servers and develop remotely.

• Integration with Rich: Leverages the Rich library to provide advanced text formatting, syntax highlighting, and rendering capabilities, enhancing the visual appeal and functionality of terminal applications.

All in all, Textual provides everything you need to build beautiful, responsive text-based interface applications.

Static and Label Widgets

Static and Label are the most basic widgets in Textual. You’ve already used Static, which manages a rectangular area on the screen with some optional text. Label is quite similar to Static, though it’s specialized for displaying text.

Even these elementary widgets have some surprising powers—like all Textual widgets, they can display rich text renderables as defined by the Rich library’s renderable protocol. This means you can specify the text’s foreground and background colors, as well as text formats like bold, italic, and even flashing effects.

Besides text styling, you can also assign any widget its own background color and frame style. You can also use a wide range of emojis.

Here’s a bare-bones example using Static and Label widgets, along with some rich text and styling:

from textual.app import App
from textual.widgets import Label, Static

class StaticAndLabelApp(App):
    def compose(self):
        self.static = Static(
            "I am a [bold red]Static[/bold red] widget!",
        )
        yield self.static
        self.label = Label(
            "I am a [yellow italic]Label[/yellow italic] widget!",
        )
        yield self.label

    def on_mount(self):
        # Styling the static
        self.static.styles.background = "blue"
        self.static.styles.border = ("solid", "white")
        self.static.styles.text_align = "center"
        self.static.styles.padding = 1, 1
        self.static.styles.margin = 4, 4
        # Styling the label
        self.label.styles.background = "darkgreen"
        self.label.styles.border = ("double", "red")
        self.label.styles.padding = 1, 1
        self.label.styles.margin = 2, 4

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

This time, .compose() yields two widgets with some rich renderable content. You’ve saved a reference to each widget before calling yield, at which point Textual adds the widget to the app’s screen.

The .on_mount() method is an event handler, which decides what should happen if an event occurs. Textual automatically calls this method before the screen is rendered. Textual, like HTML, builds the UI into a document object model (DOM) that’s a hierarchy of containers and widgets. You can locate any Textual object in this hierarchy by a DOM query that references its Python class, or its unique ID if available.

At this point, the DOM of your Textual app is fully constructed. You can use your saved references self.static and self.label to apply styles to the widgets, which you do with their .styles attributes.

Go ahead and run static_and_label.py in your command line:

(venv) $ python static_and_label.py

Admire the result of your efforts to build and style a Textual UI:

The Static and Label instances are formatted to your specifications, but you’ll notice a small difference in their default formats. The Static widget expands horizontally to fill the screen, while the default behavior of the Label is to adjust its content’s width.

You can always override these default behaviors if you wish. For example, if you specified style.width = 100% on the Label and style.width = auto on the Static, then their width behaviors would be reversed.

Button and Input Widgets

Textual provides text-based versions of nearly all the controls you’d expect in a modern UI. Buttons and text inputs are two building-block widgets that you’ll use in almost any UI app. This next example introduces Textual’s version of these widgets:

 1from textual.app import App
 2from textual.widgets import Button, Input
 3
 4class ButtonsAndInputsApp(App):
 5    def compose(self):
 6        # Buttons
 7        yield Button("Click me!")
 8        yield Button("Primary!", variant="primary")
 9        yield Button.success("Success!")
10        yield Button.warning("Warning!")
11        yield Button.error("Error!")
12        # Inputs
13        yield Input(placeholder="Type your text here")
14        yield Input(placeholder="Password", password=True)
15        yield Input(
16            placeholder="Type a number here",
17            type="number",
18            tooltip="Digits only please!",
19        )
20
21if __name__ == "__main__":
22    app = ButtonsAndInputsApp()
23    app.run()

This example shows just a few of the many possible ways of constructing Button and Input widgets. By default, the widgets are arranged vertically on the screen, in the order in which they appear in the code.

On line 7, you create a vanilla Button with the text "Click me!" It’s a rather drab black-and-white button.

The Button class has several variants, each using different colors and styles. For example, line 8 uses the parameter variant="primary", while lines 9 to 11 show off some convenience constructors for Button widgets with other variants.

Variants are mapped to colors via Textual’s system of themes, so the user can change all your app’s colors at once by selecting another theme through the built-in command palette. This palette can be accessed by pressing Ctrl+P while the app is running. You can also hard-code widget colors if you prefer. You’ll see examples of both approaches shortly.

Next, you have the Input widget, which has a range of parameters that let you customize its behavior. Each Input in this example has a placeholder text. This text appears only when the input field is empty and prompts the user to type what they’re expected to.

Line 14 creates an Input with password=True so that the text typed by the user is hidden. Lines 15 to 19 specify an Input that accepts only numbers. This Input also has a tooltip, which provides a pop-up label that appears when the mouse cursor hovers near the widget.

Go ahead and run your app now:

(venv) $ python buttons_and_inputs.py

Although your widgets aren’t yet hooked up to any events or actions, they still show some interesting built-in behavior. Notice how the themed Button widgets are animated as you move the mouse over them or click them. Try typing into the Input widgets and observe how their behavior differs:

The Input with password=True hides the input text, and the Input with type="number" ignores non-numeric inputs.

You’ve created an app with some prebuilt interactive components, but they don’t do much yet. You’ll explore ways to integrate them with your app’s logic in the section on events and actions.

Advanced Widgets

Textual has many prebuilt widgets. You’ll find classic UI widgets, such as labels, buttons, radio buttons, inputs, and text areas. You’ll also find advanced widgets, including the following:

• Tree provides a collapsible hierarchical display
• Sparkline is a compact histogram
• Switch provides an on and off switch
• Pretty is a pretty-printed display of a Python object

There are also widgets like TabbedContent that facilitate navigation between multiple screens, giving your application a multi-page look and feel. The Textual doc on widgets has all the details about using these widgets and provides usage examples for each one.

Now that you have a better understanding of widgets, it’s time to learn about the powerful styling options Textual provides for customizing the appearance of your application.

Vertical Containers

In your first two apps, you implicitly used a Vertical container. The default layout in Textual is Vertical, which is why your widgets are all lined up in a column.

Textual containers are implemented as context managers, so you can use them on a with statement. For example, a Vertical container stacks its elements vertically:

 1from textual.app import App
 2from textual.containers import Vertical
 3from textual.widgets import Static
 4
 5NUM_BOXES = 4
 6
 7class VerticalLayoutApp(App):
 8    def compose(self):
 9        with Vertical():
10            for i in range(NUM_BOXES):
11                static = Static(f"Static {i + 1}")
12                static.styles.border = ("solid", "green")
13                yield static
14
15        # for i in range(NUM_BOXES):
16        #     static = Static(f"Static {i + 1}")
17        #     static.styles.border = ("solid", "green")
18        #     yield static
19
20if __name__ == "__main__":
21    app = VerticalLayoutApp()
22    app.run()

The NUM_BOXES constant on line 5 determines how many widgets will be stacked. Line 9 introduces the context manager. Everything nested beneath it in lines 10 to 13 will be managed by a Vertical container, which stacks the widgets vertically on the screen.

Because the Vertical container is the default, you could achieve the same effect by replacing the with Vertical() stanza with the commented code below it.

Run the example to see the effect:

(venv) $ python vertical_layout.py

The Static widgets line up in a vertical column:

The vertical_layout.py app uses Python code to apply styles to the Static widgets. You can achieve the same result using an external .tcss file:

from textual.app import App
from textual.containers import Vertical
from textual.widgets import Static

NUM_BOXES = 4

class VerticalLayoutAppWithTCSS(App):
    CSS_PATH="vertical_layout.tcss"

    def compose(self):
        with Vertical():
            for i in range(NUM_BOXES):
                yield Static(f"Static {i + 1}")

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

The vertical_layout_tcss.py example references a .tcss file that may look like the following:

Static {
    border: solid green;
}

You can run this version as usual:

(venv) $ python vertical_layout_tcss.py

The output will be identical to that from vertical_layout.py.

Recall that NUM_BOXES determines the number of widgets to be stacked. In either version of the vertical layout app, try changing NUM_BOXES to a larger number, say 20. If you do this, you’ll have too many widgets to fit vertically on the screen. Some of them will disappear and become inaccessible.

Fortunately, Textual provides a quick solution to this type of issue. You can use the VerticalScroll container:

from textual.app import App
from textual.containers import VerticalScroll
from textual.widgets import Static

NUM_BOXES = 20

class VerticalScrollApp(App):
    CSS_PATH="vertical_layout.tcss"

    def compose(self):
        with VerticalScroll():
            for i in range(NUM_BOXES):
                yield Static(f"Static {i + 1}")

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

You can use the same external TCSS file as for vertical_layout.py. Run the vertical scrolling example:

(venv) $ python vertical_scroll.py

The new container class, VerticalScroll, is a drop-in replacement for Vertical that can accommodate an unlimited number of widgets:

The scrollbar on the right of the display allows you to scroll through all the boxes, using mouse gestures, the mouse scroll wheel, or the up and down arrow keys.

Horizontal Containers

A Horizontal container works in a similar way to the Vertical container but places the widgets horizontally:

 1from textual.app import App
 2from textual.containers import Horizontal
 3from textual.widgets import Static
 4
 5NUM_BOXES = 4
 6
 7class HorizontalLayoutApp(App):
 8    def compose(self):
 9        with Horizontal():
10            for i in range(NUM_BOXES):
11                static = Static(f"Static {i + 1}")
12                static.styles.border = ("solid", "green")
13                static.styles.width = "10%"
14                yield static
15
16if __name__ == "__main__":
17    app = HorizontalLayoutApp()
18    app.run()

Again, the with Horizontal() stanza on lines 9 to 14 determines the layout of the app. Here, you need to specify the width of each widget, which you do on line 13. Otherwise, the first widget will expand and claim all the horizontal space.

You can run the example in the usual way:

(venv) $ python horizontal_layout.py

Here’s how it looks with NUM_BOXES set to 4:

The widgets are laid out neatly in a horizontal row sharing the available space.

Again, the Horizontal container works well for a small number of widgets. Setting NUM_BOXES to a larger number will cause the display to overflow horizontally, and some boxes will become inaccessible. The solution is once again to use the scrolling variant of the container:

from textual.app import App
from textual.containers import HorizontalScroll
from textual.widgets import Static

NUM_BOXES = 20

class HorizontalScrollApp(App):
    def compose(self):
        with HorizontalScroll():
            for i in range(NUM_BOXES):
                static = Static(f"Static {i + 1}")
                static.styles.border = ("solid", "green")
                static.styles.width = "10%"
                yield static

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

The only change from the previous app is that now you’re using the HorizontalScroll container class. You’ve set NUM_BOXES to 20 to ensure the scrolling effect is visible.

Run your horizontal scrolling demo:

(venv) $ python horizontal_scroll.py

Now you can scroll through all the widgets:

This time, the scroll bar appears automatically at the bottom of the screen. You can manipulate it using the mouse or the Left and Right arrow keys.

You’re not limited to a single container class per app. In principle, Horizontal and Vertical containers can be nested indefinitely to make complex layouts.

Docked Widgets

An entirely different layout option is dock. It’s not a container-based option since a docked widget completely ignores the layout rules defined by its parent container.

Docks stick to their assigned position: top, left, bottom, or right within the container. The container’s other widgets get laid out according to the container’s rules, even if this results in overlaps with the docked widget.

Nested Containers and Docked Widgets

You can nest containers and combine them to create complex UI layouts. This next example will combine horizontal and vertical containers with a docked widget:

from textual.app import App
from textual.containers import (
    Horizontal,
    HorizontalScroll,
    VerticalScroll,
)
from textual.widgets import Label, Static

NUM_BOXES = 12

class NestedContainersApp(App):
    CSS_PATH = "layouts.tcss"

    def compose(self):
        with Horizontal(id="horizontal"):
            yield Static("Left", classes="box")
            with HorizontalScroll(id="horizontalscroll"):
                for i in range(NUM_BOXES):
                    yield Static(
                        f"Center.{i + 1}",
                        classes="box yellowbox",
                    )
            with VerticalScroll(id="verticalscroll"):
                for i in range(NUM_BOXES):
                    yield Static(
                        f"Right.{i + 1}",
                        classes="box redbox",
                    )
                yield Label(
                    "I am a docked label.\nI don't move!",
                    id="docked-label",
                )

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

As always, the .compose() method defines the UI structure. First, you declare the overall layout manager as a Horizontal container. Within this container, you have a Static widget, a HorizontalScroll container, and a VerticalScroll container.

Each of the scrolling containers holds twelve Static objects, too many to display all at once. In addition, the VerticalScroll contains a Label that will be docked inside it.

Textual widget constructors have an optional classes argument that accepts a series of TCSS class names in a space-separated string. These correspond to TCSS classes defined in a .tcss file that you’ll see in a moment.

The linked layouts.tcss file below declares the relevant TCSS:

.box {
    height: 1fr;
    width: 1fr;
    background: $panel;
    border: solid white;
}

.redbox {
    border: heavy red;
    height: 5;
}

.yellowbox {
    border: heavy yellow;
    width: 10;
}

#docked-label {
    dock: bottom;
    border: solid dodgerblue;
}

The .box class defines the general style that will make widgets look like boxes with a colored border. Note that you’ve specified the height and width in fr values. This unit represents a fraction of the available space. If all the widgets get 1fr, then each will occupy the same space.

Next, you have two more specific classes: .redbox and .yellowbox. They add or override some style attributes.

The #docked-label ID is applied to the label defined within the VerticalScroll container. This ID selector positions the label at the container bottom using the dock attribute. This positioning is completely independent of the container’s layout.

You can run your app to see the various layout effects:

(venv) $ python layouts.py

The resulting app will look something like this:

The leftmost widget is a plain Static. The HorizontalScroll in the center panel scrolls horizontally, and the VerticalScroll in the rightmost part scrolls vertically. The docked label remains fixed in its place within the VerticalScroll container while the other widgets scroll past it.

When you resize the screen, the layout will adapt smoothly!

Grid Container

The Grid container allows you to specify a number of rows and columns for your UI. As you yield each widget or container in your .compose() method, it’s automatically allocated to a grid position. The columns in the first row are filled, then the columns in the second row, and so on.

You have many styling options to customize this container. You can assign a height to each row and a width to each column. You can make individual cells span multiple rows or columns. You can specify gutters to reserve space between the rows and columns. And of course, you can color, frame, and add content to each individual cell or container within the grid.

Here’s an example to illustrate the flexibility of the Grid container:

from textual.app import App
from textual.containers import Grid
from textual.widgets import Static

class GridLayoutApp(App):
    def compose(self):
        grid = Grid()
        grid.styles.grid_size_rows = rows = 6
        grid.styles.grid_size_columns = cols = 4
        with grid:
            for row in range(rows):
                for col in range(cols):
                    static = Static(f"Static ({row=}, {col=})")
                    static.styles.border = ("solid", "green")
                    static.styles.width = "1fr"
                    static.styles.height = "1fr"
                    yield static

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

You’ve defined a Grid container with six rows and four columns. The Static widgets will automatically populate this grid from left to right and from top to bottom.

Now you can run your app:

(venv) $ python grid.py

The widgets are arranged as specified, and display their row and column numbers:

Note that by nesting grids together with other containers, you can craft almost any reasonable screen design.

You can also use an external TCSS file to build the above app. Here’s how:

from textual.app import App
from textual.containers import Grid
from textual.widgets import Static

class GridLayoutWithTCSS(App):
    CSS_PATH = "grid.tcss"

    def compose(self):
        with Grid():
            for row in range(6):
                for col in range(4):
                    yield Static(f"Static ({row=}, {col=})")

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

The highlighted line references the external TCSS file, which has the following styling rules for the app:

Grid {
    grid_size: 4 6;
}

Static {
    height: 1fr;
    width: 1fr;
    border: solid green;
}

First, you have the Grid class that defines a grid of four columns and six rows. Then you have the Static class that defines some styling for the Static widget.

You can run this version:

(venv) $ python grid_tcss.py

The result is the same as for the non-TCSS version. In general, TCSS is pretty useful for defining an app’s layout. It can simplify your Python code and facilitate how you style and configure your widgets and containers.