Skip to main content

A visual coutndown widget for Textal applications

Project description


Textual Countdown demo


This library provides a simple visual countdown widget, designed to subtly let the user know that a period of time is passing; essentially a simple "wait some time" progress bar.

Uses could be as a non-intrusive countdown in some sort of quiz application, or a cool-down display in an application that's waiting to hit a busy API endpoint again.


The package can be installed with pip or related tools, for example:

$ pip install textual-countdown


Once installed, you can try a demo of the library with:

$ python -m textual_countdown

Using the widget

To import the widget, do:

from textual_countdown import Countdown

The Countdown widget can then be composed into your application like any other Textual widget.

Controlling the countdown

The widget provides the following methods:

  • start(countdown: float) -> None -- call this to start a countdown, giving the number of seconds to count down.
  • cancel() -> None -- to cancel a countdown.

There is also a is_running property to check if the countdown is running.


The following events will be sent from the widget:

  • Countdown.Started -- posted when a countdown starts.
  • Countdown.Finished -- posted when a countdown finishes.
  • Countdown.Cancelled -- posted if a countdown is cancelled.

All events have a countdown property that points to the widget that sent them; Started and Finished also have a counting property that gives the amount of time being counted.


The non-counting colour for the countdown display is controlled by the standard Textual colour CSS style. The active time-remaining portion of the display is controlled by a countdown--remaining component class.

As an example, if you wanted to colour the non-running/expired portion of a countdown as red, and the time remaining as green, you could do:

Countdown {
    color: red;

    &> .countdown--remaining {
        color: green;

Additionally, when a Countdown is running, it will have a countdown--running class applied; this allows styling of non-running and running countdown widgets.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

textual_countdown-0.1.0-py3-none-any.whl (5.6 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page