Textual CSS

Textual uses CSS to apply style to widgets. If you have any exposure to web development you will have encountered CSS, but don't worry if you haven't: this chapter will get you up to speed.

VSCode User?

The official Textual CSS extension adds syntax highlighting for both external files and inline CSS.

Stylesheets

CSS stands for Cascading Stylesheet. A stylesheet is a list of styles and rules about how those styles should be applied to a web page. In the case of Textual, the stylesheet applies styles to widgets, but otherwise it is the same idea.

Let's look at some Textual CSS.

Header {
  dock: top;
  height: 3;
  content-align: center middle;
  background: blue;
  color: white;
}

This is an example of a CSS rule set. There may be many such sections in any given CSS file.

Let's break this CSS code down a bit.

Header {
  dock: top;
  height: 3;
  content-align: center middle;
  background: blue;
  color: white;
}

The first line is a selector which tells Textual which widget(s) to modify. In the above example, the styles will be applied to a widget defined by the Python class Header.

Header {
  dock: top;
  height: 3;
  content-align: center middle;
  background: blue;
  color: white;
}

The lines inside the curly braces contains CSS rules, which consist of a rule name and rule value separated by a colon and ending in a semicolon. Such rules are typically written one per line, but you could add additional rules as long as they are separated by semicolons.

The first rule in the above example reads "dock: top;". The rule name is dock which tells Textual to place the widget on an edge of the screen. The text after the colon is top which tells Textual to dock to the top of the screen. Other valid values for dock are "right", "bottom", or "left"; but "top" is most appropriate for a header.

The DOM

The DOM, or Document Object Model, is a term borrowed from the web world. Textual doesn't use documents but the term has stuck. In Textual CSS, the DOM is an arrangement of widgets you can visualize as a tree-like structure.

Some widgets contain other widgets: for instance, a list control widget will likely also have item widgets, or a dialog widget may contain button widgets. These child widgets form the branches of the tree.

Let's look at a trivial Textual app.

dom1.pyOutput

from textual.app import App


class ExampleApp(App):
    pass


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

This example creates an instance of ExampleApp, which will implicitly create a Screen object. In DOM terms, the Screen is a child of ExampleApp.

With the above example, the DOM will look like the following:

This doesn't look much like a tree yet. Let's add a header and a footer to this application, which will create more branches of the tree:

dom2.pyOutput

from textual.app import App, ComposeResult
from textual.widgets import Header, Footer


class ExampleApp(App):
    def compose(self) -> ComposeResult:
        yield Header()
        yield Footer()


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

With a header and a footer widget the DOM looks like this:

What we didn't show

We've simplified the above example somewhat. Both the Header and Footer widgets contain children of their own. When building an app with pre-built widgets you rarely need to know how they are constructed unless you plan on changing the styles of individual components.

Both Header and Footer are children of the Screen object.

To further explore the DOM, we're going to build a simple dialog with a question and two buttons. To do this we're going to import and use a few more builtin widgets:

• textual.containers.Container For our top-level dialog.
• textual.containers.Horizontal To arrange widgets left to right.
• textual.widgets.Static For simple content.
• textual.widgets.Button For a clickable button.

dom3.py

from textual.app import App, ComposeResult
from textual.containers import Container, Horizontal
from textual.widgets import Button, Footer, Header, Static

QUESTION = "Do you want to learn about Textual CSS?"


class ExampleApp(App):
    def compose(self) -> ComposeResult:
        yield Header()
        yield Footer()
        yield Container(
            Static(QUESTION, classes="question"),
            Horizontal(
                Button("Yes", variant="success"),
                Button("No", variant="error"),
                classes="buttons",
            ),
            id="dialog",
        )


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

We've added a Container to our DOM which (as the name suggests) contains other widgets. The container has a number of other widgets passed as positional arguments which will be added as the children of the container. Not all widgets accept child widgets in this way. A Button widget doesn't require any children, for example.

Here's the DOM created by the above code:

Here's the output from this example:

You may recognize some elements in the above screenshot, but it doesn't quite look like a dialog. This is because we haven't added a stylesheet.

CSS files

To add a stylesheet set the CSS_PATH classvar to a relative path:

What are TCSS files?

Textual CSS files are typically given the extension .tcss to differentiate them from browser CSS (.css).

dom4.py

from textual.app import App, ComposeResult
from textual.containers import Container, Horizontal
from textual.widgets import Button, Footer, Header, Static

QUESTION = "Do you want to learn about Textual CSS?"


class ExampleApp(App):
    CSS_PATH = "dom4.tcss"

    def compose(self) -> ComposeResult:
        yield Header()
        yield Footer()
        yield Container(