Schedule > Textual Pop-Up Screens (Step by Step)

Most of the remaining Project 1 tickets add a piece of the terminal interface with Textual. This activity is the warm-up for one of them: Export dialog, Issue #30. Its job: when the user presses a key, a small pop-up opens that asks “CSV, JSON, or Markdown?” and hands the answer back.

Today we build a tiny version of that pop-up step by step, starting from nothing.

What you will build

A tiny terminal app with a “blue screen” pop-up:

  1. The main screen says Hello World! and tells you to press b.
  2. Pressing b opens a blue pop-up with three buttons: CSV, JSON, Markdown.
  3. Clicking a button closes the pop-up, and the main screen says which one you chose.
  4. Pressing Escape closes the pop-up with no choice, and the main screen says Cancelled.

By the end you will be able to:

  • Build a pop-up (ModalScreen) out of widgets with compose()
  • Respond to a button click, and return an answer from a screen with dismiss()
  • Connect a key to an action with BINDINGS

You do not need to know Textual. We add one small idea at a time and run the app after every step. If something goes wrong, you only changed a few lines, so it is easy to find.

This is a practice run

The Export dialog is the instructor’s ticket, so do not open a pull request for it. You are working on a practice branch. The point is that the next ticket you pick up (a help screen, a theme switcher, a file-name dialog) uses exactly these moves.

Before You Begin

  1. If you have a PR that has been approved and that did not request changes, please merge it!
  2. If you have a PR where changes were requested, please revise and resubmit!

Get Situated

  1. In your terminal, commit any un-committed work, and then pull down the latest from main:

    git checkout main
    git pull
    poetry run pytest

    The tests should pass before you change anything.

  2. Create a new branch:

    # replace <yourname> with your name, no angle brackets
    git checkout -b popup-practice-<yourname>
  3. Open the issue #30 Export dialog in your browser and keep it open. You will not build the whole ticket today, but you will use its moves.

  4. In your project01-fall2026 folder, create a new file called bsod_demo.py. (You will not commit this file.)

Run your file at any time with:

poetry run python bsod_demo.py

Quit with Ctrl+Q (or q, once you add a key binding for it).

Try It Yourself First

Before you look at any steps, try to build it using only the online documentation. Reading docs and getting stuck a little is the skill the project tickets need, and it is where most of the learning happens.

The goal is the four-point app from “What you will build” above. A good order to attack it in:

A window that shows Hello World!
A second screen (a pop-up) that opens when you press b
Three buttons on that pop-up: CSV, JSON, Markdown
Clicking a button closes the pop-up and shows your choice on the main screen
Escape closes the pop-up and shows Cancelled

Where to look (open these in tabs):

You need to… Read
Get a first app running Textual: Getting started and App basics
Open and close a second screen Screens guide (look for push_screen, ModalScreen and dismiss)
Put buttons on a screen Button widget
Lay widgets out side by side Layout guide
Run code when a key is pressed Input guide and Actions
Run code when a button is clicked Events and messages

Stuck on a word in the docs? The one that trips most people up is yield:

What does yield mean? (click to expand)

compose() has one job: hand Textual the list of widgets to show. Here is the same method written two ways.

With a list (no yield): build the whole list, then give it back at the end.

def compose(self):
    widgets = []
    widgets.append(Header())
    widgets.append(Static("Hello World!"))
    widgets.append(Footer())
    return widgets

With yield: hand over one widget at a time, in the order they appear on screen.

def compose(self):
    yield Header()
    yield Static("Hello World!")
    yield Footer()

Textual ends up with the same three widgets in the same order either way. yield is shorthand: instead of collecting widgets in a list and returning it, each yield says “here is the next one.”

You can see the difference with a plain Python example that has nothing to do with Textual:

def with_a_list():
    items = []
    print("building the list...")
    items.append("a")
    items.append("b")
    return items          # everything is ready at once


def with_yield():
    print("starting...")
    yield "a"             # pauses here and hands over "a"
    print("...resuming")
    yield "b"             # pauses again, hands over "b"


for x in with_a_list():
    print("got", x)
# building the list...
# got a
# got b

for x in with_yield():
    print("got", x)
# starting...
# got a
# ...resuming
# got b

The function with yield runs a little, pauses at each yield, and picks up where it left off when asked for the next item. (Python calls this a generator.) For compose() you can ignore all that: read every yield as “add this widget to the screen.”

The actual Python meaning

A function containing yield is a generator. Calling it does not run it; it returns a “paused function” that gives back one value each time it is asked for the next one, then pauses where it left off.

def count_up(limit):
    n = 1
    while n <= limit:
        yield n          # hand back n, then pause here
        n += 1


gen = count_up(3)
print(next(gen))         # 1
print(next(gen))         # 2
print(list(count_up(3))) # [1, 2, 3]  (list() and for loops call next() for you)

return ends a function with one value. yield hands back a value and keeps the function alive so it can hand back more.

The with Vertical(...): blocks work the same way. Anything yielded inside the block becomes a child of that container.

Rules for this part:

  1. Give it about 15 minutes, working alone or with the person next to you.
  2. It is fine to get only partway. Note exactly where you got stuck (what you tried, and what happened).
  3. Do not open the steps below until we say so. When we do, compare your approach with the steps and see which parts you did differently.

If a guide’s example uses a separate .tcss file, you can put the same CSS in a CSS = """ ... """ string on your class instead, so you have one file to manage.

Step-by-Step Walkthrough

Open this after you have tried it on your own. Each step adds one idea and has you run the app.

Show the step-by-step walkthrough (try it yourself first!)

Step 1: A window that says hello

Type this into bsod_demo.py:

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


class ScreenApp(App):
    BINDINGS = [("q", "quit", "Quit")]

    def compose(self) -> ComposeResult:
        yield Header()
        yield Static("Hello World!")
        yield Footer()


if __name__ == "__main__":
    ScreenApp().run()

Run it. You should see a title bar, Hello World!, and a bottom bar that says q Quit. Press q to quit.

What is going on?

  • App is the program. ScreenApp is our version of it.
  • A widget is one thing on the screen: Header (top bar), Static (a piece of text), Footer (bottom bar).
  • compose() lists the widgets, top to bottom. Each yield means “add this widget next.”
  • BINDINGS connects a key to an action. ("q", "quit", "Quit") means: key q, do the action quit, show the label Quit in the footer.

Try it: change the text of the Static, run it again.


Step 2: Add a place to show an answer

We want the main screen to report what you chose. Add one more Static, with an id so we can find it later. Your compose() becomes:

    def compose(self) -> ComposeResult:
        yield Header()
        yield Static("Hello World!\nPress b to open the pop-up.")
        yield Static("", id="result")
        yield Footer()

Run it. The second Static is empty, so you will not see it yet, and that is fine.

  • \n means “start a new line.”
  • id="result" is a name tag. Later, self.query_one("#result") finds the widget with that name tag.

Step 3: Build the pop-up (but do not open it yet)

A pop-up is a screen of its own that sits on top of the main one. Add this class above ScreenApp in your file, and add Horizontal, Vertical, ModalScreen and Button to the imports:

from textual.containers import Horizontal, Vertical
from textual.screen import ModalScreen
from textual.widgets import Button, Footer, Header, Static


class BSOD(ModalScreen[str | None]):
    def compose(self) -> ComposeResult:
        with Vertical(id="box"):
            yield Static("Choose a format:")
            with Horizontal(id="buttons"):
                yield Button("CSV", id="csv")
                yield Button("JSON", id="json")
                yield Button("Markdown", id="markdown")
            yield Static("Press Escape to close this window.")

Nothing changes when you run it, because nothing opens the pop-up yet. That is the next step.

What is going on?

  • ModalScreen is a pop-up screen. [str | None] says “when it closes it hands back a piece of text, or nothing.”
  • Vertical stacks its children top to bottom. Horizontal puts them side by side. The indented lines under with are the children.
  • Each Button has a label (what you see) and an id (its name tag, which we use in step 5).

Step 4: Open the pop-up with a key

Add a new binding and a new method to ScreenApp:

class ScreenApp(App):
    BINDINGS = [
        ("b", "show_bsod", "Open pop-up"),
        ("q", "quit", "Quit"),
    ]

    # ... compose() stays the same ...

    def action_show_bsod(self) -> None:
        self.push_screen(BSOD())

Run it and press b. The pop-up appears on top. You can click the buttons, but nothing happens, and you cannot close the pop-up yet. (If you get stuck, press Ctrl+C in the terminal to stop the program. We fix this in the next two steps.)

What is going on?

  • The key b runs the action show_bsod. Textual finds it by name: action show_bsod → method action_show_bsod.
  • push_screen(...) puts a screen on top of the current one.

Step 5: Make the buttons give an answer

Add this method inside the BSOD class (indented, below compose):

    def on_button_pressed(self, event: Button.Pressed) -> None:
        self.dismiss(event.button.id)

Run it, press b, and click JSON. The pop-up closes. We have not shown the answer yet; that is the next step.

What is going on?

  • Clicking a button sends a message called Button.Pressed. A method named on_button_pressed is called automatically when that message arrives. (Textual finds it by its name: on_ + button + pressed.)
  • event.button.id is the name tag of the button that was clicked: "csv", "json", or "markdown".
  • self.dismiss(value) closes the pop-up and hands value back.

Step 6: Show the answer on the main screen

We need two small changes. First, tell push_screen what to do with the answer. Change action_show_bsod:

    def action_show_bsod(self) -> None:
        self.push_screen(BSOD(), self.show_result)

Second, add the show_result method to ScreenApp:

    def show_result(self, result: str | None) -> None:
        text = "Cancelled" if result is None else f"You chose: {result}"
        self.query_one("#result", Static).update(text)

Run it, press b, click Markdown. The main screen now says You chose: markdown.

What is going on?

  • self.show_result (no parentheses) is handed over as a callback: “when the pop-up closes, call this with its answer.”
  • query_one("#result", Static) finds the widget with that name tag, and .update(...) changes its text.
  • None means “no answer,” and we will see where it comes from in the next step.

Step 7: Close with Escape

Add a binding and a method inside BSOD:

class BSOD(ModalScreen[str | None]):
    BINDINGS = [("escape", "cancel", "Close")]

    # ... compose() and on_button_pressed() stay the same ...

    def action_cancel(self) -> None:
        self.dismiss(None)

Run it, press b, then Escape. The main screen says Cancelled.

This is the same pattern as step 4: key → action name → action_<name> method.


Step 8: Make it blue

Add this to the BSOD class, right under BINDINGS:

    DEFAULT_CSS = """
    BSOD { align: center middle; background: #0000aa; }
    #box { width: 60; height: auto; padding: 1 2; border: round white; }
    #buttons { height: auto; margin: 1 0; }
    #buttons Button { margin-right: 1; }
    """

Run it and press b.

  • The CSS looks like web CSS. #box styles the widget with id="box".
  • BSOD { ... } styles the whole pop-up screen: center things, make the background blue.

Try it: change width: 60 to 40, or the colors.


Step 9 (optional): Say what is being exported

Right now the pop-up always says Choose a format:. Let the main screen decide the text.

In BSOD, add an __init__ and use the value:

    def __init__(self, what: str) -> None:
        super().__init__()   # let Textual set the screen up first
        self.what = what

    def compose(self) -> ComposeResult:
        with Vertical(id="box"):
            yield Static(f"Choose a format for {self.what}:", markup=False)
            # ... the rest stays the same ...

In ScreenApp, pass the value in:

        self.push_screen(BSOD("your file"), self.show_result)

Run it. The pop-up now says Choose a format for your file:.


The finished file

If anything is not working, compare yours with this one:

from textual.app import App, ComposeResult
from textual.containers import Horizontal, Vertical
from textual.screen import ModalScreen
from textual.widgets import Button, Footer, Header, Static


class BSOD(ModalScreen[str | None]):
    """A pop-up screen. It answers with "csv", "json", "markdown" or None."""

    BINDINGS = [("escape", "cancel", "Close")]

    DEFAULT_CSS = """
    BSOD { align: center middle; background: #0000aa; }
    #box { width: 60; height: auto; padding: 1 2; border: round white; }
    #buttons { height: auto; margin: 1 0; }
    #buttons Button { margin-right: 1; }
    """

    def __init__(self, what: str) -> None:
        super().__init__()
        self.what = what

    def compose(self) -> ComposeResult:
        with Vertical(id="box"):
            yield Static(f"Choose a format for {self.what}:", markup=False)
            with Horizontal(id="buttons"):
                yield Button("CSV", id="csv")
                yield Button("JSON", id="json")
                yield Button("Markdown", id="markdown")
            yield Static("Press Escape to close this window.")

    def on_button_pressed(self, event: Button.Pressed) -> None:
        self.dismiss(event.button.id)

    def action_cancel(self) -> None:
        self.dismiss(None)


class ScreenApp(App):
    BINDINGS = [
        ("b", "show_bsod", "Open pop-up"),
        ("q", "quit", "Quit"),
    ]

    def compose(self) -> ComposeResult:
        yield Header()
        yield Static("Hello World!\nPress b to open the pop-up.")
        yield Static("", id="result")
        yield Footer()

    def action_show_bsod(self) -> None:
        self.push_screen(BSOD("your file"), self.show_result)

    def show_result(self, result: str | None) -> None:
        text = "Cancelled" if result is None else f"You chose: {result}"
        self.query_one("#result", Static).update(text)


if __name__ == "__main__":
    ScreenApp().run()

Check your understanding

  1. Which line makes the pop-up appear? Which line makes it disappear?
  2. How does the main screen find out which button you clicked?
  3. What would happen if you gave two buttons the same id? (Try it. Which of the two buttons could you still tell apart?)
  4. Add a fourth button, Excel, so that choosing it shows You chose: excel. How many places did you have to change?

What you just used: a screen (ModalScreen), widgets and containers (compose, yield, with), key bindings (BINDINGS + action_<name>), messages (on_button_pressed), and a callback (push_screen(screen, callback)). Every screen ticket in the project is built from these same pieces.

UNC Asheville Department of Computer Science