Spinner

An indeterminate progress spinner for blocking work whose duration is unknown: a subprocess, a network call, a long query. Where click.progressbar needs a known length or an iterable to advance through, Spinner simply signals that something is happening.

It animates on a background thread, so the calling thread stays free to block on the work itself:

from time import sleep

from click_extra import Spinner

with Spinner("Brewing tea"):
    sleep(5)

The spinner draws to stderr and is a no-op whenever that stream is not a terminal (a pipe, a file, a CI log), so redirected output and machine-readable formats stay clean. Reassign its label while it runs to reflect the current step, and set a delay so it only appears once an operation is genuinely slow.

Use as a decorator

A Spinner doubles as a decorator, with or without parentheses. @Spinner wraps a function directly; @Spinner("…") configures the spinner first. Either way the function spins for the duration of every call and returns its result untouched.

@Spinner  # Bare form: a default spinner.
def roast(batch):
    sleep(5)
    return batch


@Spinner("Roasting coffee", timer=True)  # Configured form.
def roast_slowly(batch):
    sleep(5)
    return batch

The one instance is shared across calls, which is right for sequential use; give concurrent callers their own spinner.

Spin direction

Pass reverse=True to rotate the other way. It works with the default frames or any custom sequence:

with Spinner("Chilling lemonade", reverse=True):
    sleep(5)

A clock is the clearest thing to run backwards, since a reader already knows which way its hands are supposed to go:

This is why the catalog carries no timeTravel. cli-spinners ships one, because its renderers only play frames forwards and a backwards clock has to be a second preset to exist at all. Here it is SPINNERS["clock"] with reverse=True, and a duplicate entry would only be a second name for the same animation.

The animation source is just a sequence of strings. click_extra.spinner ships the default Braille SPINNER_FRAMES and a plain ASCII_SPINNER_FRAMES for terminals without Unicode glyphs; pass your own to frames for anything else.

Picturing a spinner

frame_lines() hands back one turn of the animation held still, one line per frame. The glyph, the label, the style and the timer land where the running spinner puts them, reverse included, so the picture cannot drift from what the terminal shows. No thread starts and no terminal is needed:

from click_extra import SPINNERS, Spinner, Style

spinner = Spinner("Brewing tea", spinner=SPINNERS["moon"], style=Style(fg="green"))
lines = spinner.frame_lines()

Colors are applied by default, whatever stream the spinner itself would have drawn on: a picture carries its own answer to whether ANSI survives. Pass color=False for the bare text. These lines are what an animated capture stacks into an SVG.

A documentation page asks for that picture with :screenshot-animate:, naming the spinner to draw. The option takes the frames and the interval straight off it, so the image below is built from the same object the paragraph above describes:

Because the frames come from a declared spinner rather than from a timed recording, the same expression composes the same lines on every build. The committed asset keeps the same bytes, and the working tree stays clean, until a new Click Extra version rewrites its @generated stamp.

Spinner catalog

SPINNERS is a catalog of around 90 ready-made animations, each a SpinnerPreset bundling the frames and the interval they were tuned for. They are ported from cli-spinners, the de-facto reference collection. Pick one with spinner=:

from click_extra import Spinner, SPINNERS

with Spinner("Brewing tea", spinner=SPINNERS["moon"]):
    sleep(5)

The preset sets both the frames and the interval; an explicit frames= or interval= still overrides it. Because the spinner redraws the whole line instead of backspacing, the multi-character animations (bouncing-bar, pong, shark, …) render correctly here, unlike in the upstream renderers that had to drop them.

Full inventory

Every style is browsable from the CLI. On an interactive terminal click-extra spinner animates a live tour of the selection (--all for the whole catalog, --random N for a sample, or --select name1,name2 for specific ones); --table prints the reference table below instead of animating. The Frames column previews each animation, and the Tour column is the dwell time the live tour spends on each: three full cycles, clamped to two-to-three seconds:

$ click-extra --color spinner --all --table
╭───────────────────────┬──────────────────────────────────────────────────────────────────┬──────────┬───────╮
│ Name                  │ Frames                                                           │ Interval │  Tour │
├───────────────────────┼──────────────────────────────────────────────────────────────────┼──────────┼───────┤
│ dots                  │ ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏                                              │ 0.08s    │  2.4s │
│ dots2                 │ ⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷                                                  │ 0.08s    │  2.0s │
│ dots3                 │ ⠋ ⠙ ⠚ ⠞ ⠖ ⠦ ⠴ ⠲ ⠳ ⠓                                              │ 0.08s    │  2.4s │
│ dots4                 │ ⠄ ⠆ ⠇ ⠋ ⠙ ⠸ ⠰ ⠠ ⠰ ⠸ ⠙ ⠋ ⠇ ⠆                                      │ 0.08s    │  3.0s │
│ dots5                 │ ⠋ ⠙ ⠚ ⠒ ⠂ ⠂ ⠒ ⠲ ⠴ ⠦ ⠖ ⠒ ⠐ ⠐ ⠒ ⠓ ⠋                                │ 0.08s    │  3.0s │
│ dots6                 │ ⠁ ⠉ ⠙ ⠚ ⠒ ⠂ ⠂ ⠒ ⠲ ⠴ ⠤ ⠄ ⠄ ⠤ ⠴ ⠲ ⠒ ⠂ ⠂ ⠒ ⠚ ⠙ ⠉ ⠁                  │ 0.08s    │  3.0s │
│ dots7                 │ ⠈ ⠉ ⠋ ⠓ ⠒ ⠐ ⠐ ⠒ ⠖ ⠦ ⠤ ⠠ ⠠ ⠤ ⠦ ⠖ ⠒ ⠐ ⠐ ⠒ ⠓ ⠋ ⠉ ⠈                  │ 0.08s    │  3.0s │
│ dots8                 │ ⠁ ⠁ ⠉ ⠙ ⠚ ⠒ ⠂ ⠂ ⠒ ⠲ ⠴ ⠤ ⠄ ⠄ ⠤ ⠠ ⠠ ⠤ ⠦ ⠖ ⠒ ⠐ ⠐ ⠒ ⠓ ⠋ ⠉ ⠈ … (+1)   │ 0.08s    │  3.0s │
│ dots9                 │ ⢹ ⢺ ⢼ ⣸ ⣇ ⡧ ⡗ ⡏                                                  │ 0.08s    │  2.0s │
│ dots10                │ ⢄ ⢂ ⢁ ⡁ ⡈ ⡐ ⡠                                                    │ 0.08s    │  2.0s │
│ dots11                │ ⠁ ⠂ ⠄ ⡀ ⢀ ⠠ ⠐ ⠈                                                  │ 0.1s     │  2.4s │
│ dots12                │ ⢀⠀ ⡀⠀ ⠄⠀ ⢂⠀ ⡂⠀ ⠅⠀ ⢃⠀ ⡃⠀ ⠍⠀ ⢋⠀ ⡋⠀ ⠍⠁ ⢋⠁ ⡋⠁ ⠍⠉ ⠋⠉ ⠋⠉ ⠉⠙ ⠉⠙ … (+37) │ 0.08s    │  4.5s │
│ dots13                │ ⣼ ⣹ ⢻ ⠿ ⡟ ⣏ ⣧ ⣶                                                  │ 0.08s    │  2.0s │
│ dots14                │ ⠉⠉ ⠈⠙ ⠀⠹ ⠀⢸ ⠀⣰ ⢀⣠ ⣀⣀ ⣄⡀ ⣆⠀ ⡇⠀ ⠏⠀ ⠋⠁                              │ 0.08s    │  2.9s │
│ dots-8bit             │ ⠀ ⠁ ⠂ ⠃ ⠄ ⠅ ⠆ ⠇ ⡀ ⡁ ⡂ ⡃ ⡄ ⡅ ⡆ ⡇ ⠈ ⠉ ⠊ ⠋ ⠌ ⠍ ⠎ ⠏ ⡈ ⡉ ⡊ ⡋ … (+228) │ 0.08s    │ 20.5s │
│ dots-circle           │ ⢎  ⠎⠁ ⠊⠑ ⠈⠱  ⡱ ⢀⡰ ⢄⡠ ⢆⡀                                          │ 0.08s    │  2.0s │
│ sand                  │ ⠁ ⠂ ⠄ ⡀ ⡈ ⡐ ⡠ ⣀ ⣁ ⣂ ⣄ ⣌ ⣔ ⣤ ⣥ ⣦ ⣮ ⣶ ⣷ ⣿ ⡿ ⠿ ⢟ ⠟ ⡛ ⠛ ⠫ ⢋ … (+7)   │ 0.08s    │  3.0s │
│ line                  │ - \ | /                                                          │ 0.13s    │  2.0s │
│ line2                 │ ⠂ - – — – -                                                      │ 0.1s     │  2.0s │
│ rolling-line          │ /    -   \    |   |  \   -  /                                    │ 0.08s    │  2.0s │
│ pipe                  │ ┤ ┘ ┴ └ ├ ┌ ┬ ┐                                                  │ 0.1s     │  2.4s │
│ simple-dots           │ .   ..  ...                                                      │ 0.4s     │  3.0s │
│ simple-dots-scrolling │ .   ..  ...  ..   .                                              │ 0.2s     │  3.0s │
│ star                  │ ✶ ✸ ✹ ✺ ✹ ✷                                                      │ 0.07s    │  2.0s │
│ star2                 │ + x *                                                            │ 0.08s    │  2.0s │
│ flip                  │ _ _ _ - ` ` ' ´ - _ _ _                                          │ 0.07s    │  2.5s │
│ hamburger             │ ☱ ☲ ☴                                                         │ 0.1s     │  2.0s │
│ grow-vertical         │ ▁ ▃ ▄ ▅ ▆ ▇ ▆ ▅ ▄ ▃                                              │ 0.12s    │  3.0s │
│ grow-horizontal       │ ▏ ▎ ▍ ▌ ▋ ▊ ▉ ▊ ▋ ▌ ▍ ▎                                          │ 0.12s    │  3.0s │
│ balloon               │ . o O @ *                                                        │ 0.14s    │  2.9s │
│ balloon2              │ . o O ° O o .                                                    │ 0.12s    │  2.5s │
│ noise                 │ ▓ ▒ ░                                                            │ 0.1s     │  2.0s │
│ bounce                │ ⠁ ⠂ ⠄ ⠂                                                          │ 0.12s    │  2.0s │
│ box-bounce            │ ▖ ▘ ▝ ▗                                                          │ 0.12s    │  2.0s │
│ box-bounce2           │ ▌ ▀ ▐ ▄                                                          │ 0.1s     │  2.0s │
│ triangle              │ ◢ ◣ ◤ ◥                                                          │ 0.05s    │  2.0s │
│ binary                │ 010010 001100 100101 111010 111101 010111 101011 111000 … (+2)   │ 0.08s    │  2.4s │
│ arc                   │ ◜ ◠ ◝ ◞ ◡ ◟                                                      │ 0.1s     │  2.0s │
│ circle                │ ◡ ⊙ ◠                                                            │ 0.12s    │  2.0s │
│ square-corners        │ ◰ ◳ ◲ ◱                                                          │ 0.18s    │  2.2s │
│ circle-quarters       │ ◴ ◷ ◶ ◵                                                          │ 0.12s    │  2.0s │
│ circle-halves         │ ◐ ◓ ◑ ◒                                                          │ 0.05s    │  2.0s │
│ squish                │ ╫ ╪                                                              │ 0.1s     │  2.0s │
│ toggle                │ ⊶ ⊷                                                              │ 0.25s    │  2.0s │
│ toggle2               │ ▫ ▪                                                              │ 0.08s    │  2.0s │
│ toggle3               │ □ ■                                                              │ 0.12s    │  2.0s │
│ toggle4               │ ■ □ ▪ ▫                                                          │ 0.1s     │  2.0s │
│ toggle5               │ ▮ ▯                                                              │ 0.1s     │  2.0s │
│ toggle6               │ ဝ ၀                                                              │ 0.3s     │  2.0s │
│ toggle7               │ ⦾ ⦿                                                              │ 0.08s    │  2.0s │
│ toggle8               │ ◍ ◌                                                              │ 0.1s     │  2.0s │
│ toggle9               │ ◉ ◎                                                              │ 0.1s     │  2.0s │
│ toggle10              │ ㊂ ㊀ ㊁                                                         │ 0.1s     │  2.0s │
│ toggle11              │ ⧇ ⧆                                                              │ 0.05s    │  2.0s │
│ toggle12              │ ☗ ☖                                                              │ 0.12s    │  2.0s │
│ toggle13              │ = * -                                                            │ 0.08s    │  2.0s │
│ arrow                 │ ← ↖ ↑ ↗ → ↘ ↓ ↙                                                  │ 0.1s     │  2.4s │
│ arrow2                │ ⬆ ↗ ➡ ↘ ⬇ ↙ ⬅ ↖                                                  │ 0.08s    │  2.0s │
│ arrow3                │ ▹▹▹▹▹ ▸▹▹▹▹ ▹▸▹▹▹ ▹▹▸▹▹ ▹▹▹▸▹ ▹▹▹▹▸                              │ 0.12s    │  2.2s │
│ bouncing-bar          │ [    ] [=   ] [==  ] [=== ] [====] [ ===] [  ==] [   =] … (+8)   │ 0.08s    │  3.0s │
│ bouncing-ball         │ ( ●    ) (  ●   ) (   ●  ) (    ● ) (     ●) (    ● ) … (+4)     │ 0.08s    │  2.4s │
│ smiley                │ 😄 😝                                                            │ 0.2s     │  2.0s │
│ monkey                │ 🙈 🙈 🙉 🙊                                                      │ 0.3s     │  3.0s │
│ hearts                │ 💛 💙 💜 💚 💗                                                   │ 0.1s     │  2.0s │
│ clock                 │ 🕛 🕐 🕑 🕒 🕓 🕔 🕕 🕖 🕗 🕘 🕙 🕚                              │ 0.1s     │  3.0s │
│ earth                 │ 🌍 🌎 🌏                                                         │ 0.18s    │  2.0s │
│ material              │ █▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ … (+90)                │ 0.017s   │  3.0s │
│ moon                  │ 🌑 🌒 🌓 🌔 🌕 🌖 🌗 🌘                                          │ 0.08s    │  2.0s │
│ runner                │ 🚶 🏃                                                            │ 0.14s    │  2.0s │
│ pong                  │ ▐⠂       ▌ ▐⠈       ▌ ▐ ⠂      ▌ ▐ ⠠      ▌ ▐  ⡀     ▌ … (+25)   │ 0.08s    │  3.0s │
│ shark                 │ ▐|\____________▌ ▐_|\___________▌ ▐__|\__________▌ … (+23)       │ 0.12s    │  3.1s │
│ dqpb                  │ d q p b                                                          │ 0.1s     │  2.0s │
│ weather               │ ☀ ☀ ☀ 🌤  ⛅ 🌥  ☁ 🌧  🌨  🌧  🌨  🌧  🌨  ⛈  🌨  🌧  🌨  ☁ 🌥  ⛅ … (+3)    │ 0.1s     │  3.0s │
│ christmas             │ 🌲 🎄                                                            │ 0.4s     │  2.4s │
│ grenade               │ ،   ′    ´   ‾    ⸌   ⸊   |   ⁎   ⁕  ෴    ⁓                      │ 0.08s    │  3.0s │
│ point                 │ ∙∙∙ ●∙∙ ∙●∙ ∙∙● ∙∙∙                                              │ 0.125s   │  2.0s │
│ layer                 │ - = ≡                                                            │ 0.15s    │  2.0s │
│ beta-wave             │ ρββββββ βρβββββ ββρββββ βββρβββ ββββρββ βββββρβ ββββββρ          │ 0.08s    │  2.0s │
│ finger-dance          │ 🤘 🤟 🖖 ✋ 🤚 👆                                                │ 0.16s    │  2.9s │
│ fist-bump             │ 🤜　　　　🤛 🤜　　　　🤛 🤜　　　　🤛 　🤜　　🤛　 … (+3)       │ 0.08s    │  2.0s │
│ soccer-header         │ 🧑⚽       🧑 🧑  ⚽      🧑 🧑   ⚽     🧑 … (+9)               │ 0.08s    │  2.9s │
│ mindblown             │ 😐 😐 😮 😮 😦 😦 😧 😧 🤯 💥 ✨                                 │ 0.16s    │  3.0s │
│ speaker               │ 🔈 🔉 🔊 🔉                                                      │ 0.16s    │  2.0s │
│ orange-pulse          │ 🔸 🔶 🟠 🟠 🔶                                                   │ 0.1s     │  2.0s │
│ blue-pulse            │ 🔹 🔷 🔵 🔵 🔷                                                   │ 0.1s     │  2.0s │
│ orange-blue-pulse     │ 🔸 🔶 🟠 🟠 🔶 🔹 🔷 🔵 🔵 🔷                                    │ 0.1s     │  3.0s │
│ aesthetic             │ ▰▱▱▱▱▱▱ ▰▰▱▱▱▱▱ ▰▰▰▱▱▱▱ ▰▰▰▰▱▱▱ ▰▰▰▰▰▱▱ ▰▰▰▰▰▰▱ ▰▰▰▰▰▰▰ … (+1)   │ 0.08s    │  2.0s │
│ dwarf-fortress        │ ██████£££   ☺██████£££   ☺██████£££   ☺▓█████£££   … (+129)      │ 0.08s    │ 10.6s │
│ fish                  │ ~~~~~~~~~~~~~~~~~~~~ > ~~~~~~~~~~~~~~~~~~ … (+25)                │ 0.08s    │  3.0s │
╰───────────────────────┴──────────────────────────────────────────────────────────────────┴──────────┴───────╯

Every one of them, animating:

Name	Animation	Name	Animation	Name	Animation
dots		dots2		dots3
dots4		dots5		dots6
dots7		dots8		dots9
dots10		dots11		dots12
dots13		dots14		dots-8bit
dots-circle		sand		line
line2		rolling-line		pipe
simple-dots		simple-dots-scrolling		star
star2		flip		hamburger
grow-vertical		grow-horizontal		balloon
balloon2		noise		bounce
box-bounce		box-bounce2		triangle
binary		arc		circle
square-corners		circle-quarters		circle-halves
squish		toggle		toggle2
toggle3		toggle4		toggle5
toggle6		toggle7		toggle8
toggle9		toggle10		toggle11
toggle12		toggle13		arrow
arrow2		arrow3		bouncing-bar
bouncing-ball		smiley		monkey
hearts		clock		earth
material		moon		runner
pong		shark		dqpb
weather		christmas		grenade
point		layer		beta-wave
finger-dance		fist-bump		soccer-header
mindblown		speaker		orange-pulse
blue-pulse		orange-blue-pulse		aesthetic
dwarf-fortress		fish

Bell on completion

Set beep=True to ring the terminal bell once when the spinner stops, handy for a long task you walk away from. It rings only when the spinner was actually shown, so redirected or non-interactive runs stay quiet:

with Spinner("Baking bread", beep=True):
    sleep(5)

Printing while spinning

Because the spinner draws to stderr, results written to stdout never collide with the animation. To emit a line on the same stream as the spinner, use echo(): it erases the current frame, prints the message above the spinner, and lets the animation carry on underneath. A bare print would instead leave a frame glyph stranded mid-line.

from time import sleep

from click_extra import Spinner


def pick(stream=None):
    """Fill three baskets, tracing each one as it lands."""
    with Spinner("Picking apples", stream=stream) as spinner:
        for basket in range(3):
            sleep(1.5)
            spinner.echo(f"Filled basket {basket}")

The stream argument is threaded through only so this page can record the animation below. A real call leaves it out, and the spinner finds stderr on its own.

Each echoed line is kept where it landed and the animation carries on below it, which is the whole difference from a bare print.

Parallel work

A Spinner drives a single line, and one spinner can report on a whole pool of concurrent tasks. The simplest way is to let the main thread update it as the tasks finish, through concurrent.futures.as_completed.

Update the label for a running count:

from concurrent.futures import ThreadPoolExecutor, as_completed

cities = ["Cairo", "Lima", "Oslo", "Paris", "Tokyo"]

# How long each forecast takes to come back, standing in for a real fetch.
latency = {"Cairo": 1.7, "Lima": 0.5, "Oslo": 2.1, "Paris": 0.9, "Tokyo": 1.3}


def fetch(city):
    sleep(latency[city])  # The blocking call: a download, a query, a subprocess.
    return city


def count_forecasts(stream=None):
    """Fetch every forecast at once, counting them off as they land."""
    with Spinner(f"Fetching forecasts (0/{len(cities)})", stream=stream) as spinner:
        with ThreadPoolExecutor() as pool:
            futures = [pool.submit(fetch, city) for city in cities]
            for done, _ in enumerate(as_completed(futures), 1):
                spinner.label = f"Fetching forecasts ({done}/{len(cities)})"
        # A spinner erases itself on the way out, so the final tally only
        # reaches the screen if the animation gets one more beat to draw it.
        sleep(0.3)

Or echo() a line as each task lands, leaving a trail of finished work that scrolls up while the spinner keeps turning below it:

def trail_forecasts(stream=None):
    """Fetch every forecast at once, leaving a line behind for each."""
    with Spinner("Fetching forecasts", stream=stream) as spinner:
        with ThreadPoolExecutor() as pool:
            futures = {pool.submit(fetch, city): city for city in cities}
            for future in as_completed(futures):
                spinner.echo(f"✓ {futures[future]}")

The cities land in whatever order the pool finishes them, which is why the trail above is not alphabetical.

Both label and echo() are safe to touch while the animation runs, so a worker thread can stream its own progress mid-task rather than only reporting on completion. A genuine spinner per task, several rotating at once on their own lines, is a separate capability: it needs a coordinated multi-line region, which Spinner does not attempt.

The operation trail

The two idioms above (a running done/total label, plus one echoed line per finished task) are packaged together as OperationTrail, the batch-reporting companion of the concurrency primitives run_jobs and run_lanes. Each completed operation leaves a persistent ✓/✘ trail_line() on screen, and finish() closes the batch with a kept summary line:

from click_extra.execution import run_jobs
from click_extra.spinner import OperationTrail

jobs = 4

with OperationTrail(
    label="Fetching", unit="feeds", total=len(feeds), jobs=jobs
) as trail:

    def fetch(feed):
        trail.mark(*pull(feed))  # pull() returns (ok, message).

    list(run_jobs(fetch, feeds, jobs=jobs))
    trail.finish(
        trail.ok_count == len(feeds),
        f"Fetched {trail.ok_count}/{len(feeds)} feeds",
    )

Run concurrently, that is one aggregate spinner carrying the tally while the finished operations stack up above it:

The rendering adapts to the batch’s concurrency, and you pick neither mode by hand. Run concurrently (jobs > 1), one aggregate spinner carries the Fetching 3/5 feeds tally while the trail lines stream above it, its animation picked from the catalog with spinner=SPINNERS["moon"]. Run sequentially (jobs <= 1), each outcome echoes as a plain line and every operation stays free to keep its own per-call Spinner. Either way the finisher carries the elapsed time. OperationTrail details what each mode drives.

Only the aggregate spinner or bar needs an interactive terminal, since it redraws in place. The ✓/✘ lines and the finisher print on any stream, so a pipe or a CI log keeps the batch’s record, and mark() is safe to call from worker threads. A sequential batch whose real product is another output (a result table on stdout) can silence its trail with echo_sequential=False while keeping the ok_count tally.

Two arguments decide what a trail shows. live says where its spinner or bar may draw: "auto" (the default) on an interactive terminal, unless --no-progress or --accessible turned progress off; "always" on any stream; and "never" nowhere. A trail that does not draw keeps its lines. visible=False silences the whole trail.

This page captures its commands off a terminal, and the trail still prints there. That is how it shows a live sequential run:

from click_extra import command
from click_extra.spinner import OperationTrail


@command
def roast():
    """Roast a tray of vegetables, tracing each outcome as it lands."""
    vegetables = ["carrots", "fennel", "leeks", "peppers"]
    with OperationTrail(jobs=1) as trail:
        for vegetable in vegetables:
            roasted = vegetable != "leeks"  # The leeks caught the heat.
            trail.mark(
                roasted,
                f"{vegetable} roasted" if roasted else f"{vegetable} scorched",
            )
        trail.finish(
            trail.ok_count == len(vegetables),
            f"Roasted {trail.ok_count}/{len(vegetables)} vegetables",
        )

$ roast
✓ carrots roasted
✓ fennel roasted
✘ leeks scorched
✓ peppers roasted
✘ Roasted 3/4 vegetables

The lines echo in order as each outcome lands, and the run closes on the ✘ finisher because one vegetable scorched: the same trail a sequential batch leaves in a real terminal, without the live redraw.

The trail’s timer follows the --time / --no-time flag by default (timer=None), so this untimed run shows no clocks. Under --time the ✘ finisher gains the batch’s total, and each operation can report its own elapsed time: wrap the work in an operation() handle, whose mark() times itself, so the lines read ✓ carrots roasted (2.4s). Force it either way with timer=True or timer=False, or hand timer a lambda seconds: … callable to format the clock.

def roast(vegetable):
    op = trail.operation()  # Start this operation's clock.
    roasted = vegetable != "leeks"
    op.mark(
        roasted,
        f"{vegetable} roasted" if roasted else f"{vegetable} scorched",
    )

While the batch runs, the aggregate indicator counts the elapsed time up from zero by default; pass clock="eta" to count down an estimate of the time remaining instead. A determinate bar reads that estimate from Click natively, and the concurrent spinner borrows the same click.progressbar estimator since the trail knows its total. The per-operation and finisher times stay elapsed either way.

The bundled CLI wraps all three renderings in one command, to watch in a terminal what this page can only echo: click-extra trail roasts a batch behind a concurrent aggregate spinner, --jobs 1 drops to the sequential plain-line trail above, and --progress-bar swaps the spinner for a determinate bar.

$ click-extra trail --help
Usage: click-extra trail [OPTIONS]

  Trace a simulated batch of operations behind an operation trail.

  Roasts a handful of make-believe vegetables (each a short pause, the leeks
  scorching) and reports them as they land. The display follows the batch: with
  --jobs 1 each outcome echoes as a plain line; with two or more jobs a spinner
  carries the running tally while outcomes stream above it; --progress-bar swaps
  that spinner for a determinate progress bar. Add --time to append each
  vegetable's roast time and the batch total; --elapsed and --eta turn that on
  too, counting up from zero or down as an estimate. Under --no-progress, or off
  an interactive terminal, no spinner or bar draws, and each outcome and the
  summary print as plain lines.

Options:
  --progress-bar             Drive the batch with a determinate progress bar
                             instead of a spinner.
  --eta / --elapsed          For --progress-bar, show the time remaining (--eta)
                             or elapsed (--elapsed); either one turns timing on,
                             like --time. A spinner always shows elapsed time.
  --spinner NAME             Aggregate spinner animation for concurrent runs
                             (see the spinner command for names). Defaults to
                             the built-in spinner; ignored with --progress-bar.
  --jobs [auto|max|INTEGER]  Number of parallel jobs. Accepts an integer, auto
                             (the host's logical CPUs, minus one when there are
                             three or more) or max (all logical CPUs). --jobs 0
                             runs sequentially.  [default: auto]
  -h, --help                 Show this message and exit.

A Ctrl+C inside the trail still ends it on a finisher, like ✘ Interrupted after 2/5 roasts, so the record of the batch says where it stopped. A task already running when the Ctrl+C landed prints its own outcome below that line once it finishes, while the CLI waits for it.

A progress bar instead of a spinner

Because the trail knows its total, it can carry a determinate progress bar rather than an indeterminate spinner. Give the roast command above a bar by adding progress_bar=True (mutually exclusive with spinner=, and requiring a positive total), plus the label and unit its tally reads:

with OperationTrail(
    label="Roasting",
    unit="vegetables",
    total=len(vegetables),
    progress_bar=True,
) as trail:
    ...  # mark() each outcome, then finish(), exactly as above.

The aggregate indicator becomes a bar holding the done/total count, the same ✓/✘ outcomes streaming above it, and a kept summary replaces the bar on finish(). It serves sequential and concurrent batches alike.

Unlike the sequential trail above, the bar is driven by cursor-control codes, so it draws only on an interactive terminal, unless live="always" forces it. Recorded off one, the landed outcomes sit above a bar tracking the tally:

When the last vegetable lands, finish() replaces the bar with the kept ✘ Roasted 3/4 vegetables (0.0s) summary, the same trail a sequential run leaves behind. A log record emitted mid-batch still lands on its own line above the bar, through the same cooperation the spinner uses. To watch a bar drive a live batch, run click-extra trail --progress-bar in a terminal.

Styling and color

The spinner’s glyph, label and timer are painted with a Style instance: the very type Click Extra’s theme system is built on. The simplest customization is a foreground color:

from click_extra import Spinner, Style

with Spinner("Counting sheep", style=Style(fg="cyan")):
    sleep(5)

A Style carries far more than a foreground color. Add a background with bg, and text attributes like bold, dim, italic, underline, blink or reverse, and combine them freely:

with Spinner("Counting sheep", style=Style(fg="bright_white", bg="blue", bold=True)):
    sleep(5)

Colors accept any form click.style understands: ANSI names ("red", "bright_magenta"), 256-color indexes, #rrggbb hex strings, or (r, g, b) tuples. A Style carrying an unrenderable color or attribute is rejected with a ValueError at construction, so a typo fails fast instead of silently dying on the animation thread.

Color follows the terminal, not the spinner

Color is decoupled from the animation: under --no-color or NO_COLOR the spinner keeps spinning, just in plain text (the --progress section below explains the rationale). Inside a Click Extra CLI the color follows the reconciled --color/--no-color flag; standalone it reads the same environment variables as --color, then falls back to whether the terminal is interactive.

The same Style type colors the ok() / fail() finishers: they default to the theme’s success/error style and take a style= override, covered in the Success and failure section below.

Success and failure

Stopping the spinner (or leaving its context) erases it and shows the cursor it hid, even when SIGTERM kills the process, which runs no clean-up of its own. To leave a result on screen instead, finish with ok() or fail(): each replaces the final frame with a kept line. The marker defaults to the theme’s success/error glyph (✓ / ✘), painted with the active theme’s success/error Style, so a finished spinner matches the rest of a themed CLI.

with Spinner("Baking bread") as spinner:
    sleep(5)
    spinner.ok()  # ✓ Baking bread

Pass your own marker (spinner.ok("done")) or override the paint with a Style (spinner.fail(style=Style(fg="bright_red"))). Color is stripped under --no-color/NO_COLOR; off a terminal the line is still written, so the outcome is recorded in logs and pipes.

Because the finisher is written even when the spinner never appeared (a call shorter than the delay, a pipe, a non-terminal), gate it on the shown property when you only want it after a spinner the reader actually saw:

with Spinner("Baking bread") as spinner:
    bake()
    if spinner.shown:
        spinner.ok()

Elapsed time

Set timer=True to append the running wall-clock time to the spinner, and to any ok()/fail() line:

with Spinner("Simmering stock", timer=True) as spinner:
    sleep(5)
    spinner.ok()  # ✓ Simmering stock (5.0s)

The default format is compact: 2.3s, then 1:05, then 1:02:03. For anything else, pass a callable instead of True: it receives the elapsed seconds and returns the string to show:

with Spinner("Simmering stock", timer=lambda s: f"{s / 60:.0f} min") as spinner:
    sleep(5)
    spinner.ok()  # ✓ Simmering stock (0 min)

Read the elapsed time any moment from the elapsed_time property, which freezes once the spinner stops.

The --progress option

click_extra.command and click_extra.group add a --progress/--no-progress flag to every CLI by default. It resolves to a single boolean at ctx.meta["click_extra.progress"]. A Spinner or an OperationTrail left at live="auto" reads it on its own, so --no-progress keeps it from drawing with no wiring in the command:

from click_extra import Spinner, command


@command
def harvest():
    """Pick apples behind a spinner, unless --no-progress is passed."""
    with Spinner("Picking apples"):
        sleep(5)

Pass live="always" or live="never" to decide regardless of the flag.

A command that is not a Click Extra one gets the same flag from the @progress_option decorator:

import click
from click_extra import Spinner, progress_option

@click.command
@progress_option
def press():
    """Press apples into cider."""
    with Spinner("Pressing apples"):
        click.echo("Cider is ready.")

$ press --help
Usage: press [OPTIONS]

  Press apples into cider.

Options:
  --progress / --no-progress  Show progress indicators during long operations.
                              Disabled for non-interactive output (pipes, dumb
                              terminals, CI) and by --accessible.
  --help                      Show this message and exit.

Spinner display is decoupled from color. A spinner is an interactivity concern, not a color one: it is driven by cursor-control codes, which the NO_COLOR standard explicitly does not govern. So --no-color and NO_COLOR strip the spinner’s color but keep it spinning, the same way cargo, npm, pip, Rich, indicatif and ora gate progress on the terminal rather than on color.

The resolved value is False only for non-interactive output (a pipe, a TERM=dumb terminal, or CI: handled by the widget’s own check when you pass live="auto") and for explicit intent (--no-progress or --accessible, the latter so a screen reader is never handed a spinning glyph).

Progress bars

The same --progress/--no-progress flag also gates Click’s determinate progress bar. click_extra.progressbar is a drop-in for click.progressbar: it reads the resolved flag and hides the bar when progress is off, so a single --no-progress (or --accessible) silences both the indeterminate spinner and the determinate bar.

from click_extra import command, progressbar


@command
def harvest():
    """Pick apples behind a determinate progress bar."""
    with progressbar((1, 2, 3), label="Picking apples") as bar:
        for _ in bar:
            pass

$ harvest
Picking apples

$ harvest --no-progress

The hidden argument stays authoritative: pass an explicit hidden=True or hidden=False to force the bar regardless of the flag, mirroring how an explicit color= overrides ctx.color on click.echo. Color is handled upstream too, since Click renders the bar through click.echo: --no-color and NO_COLOR strip its ANSI without any extra wiring.

The bar’s estimated-time display is gated the same way, but on --time rather than --progress: show_eta defaults to None, shown under --time and hidden otherwise, so a bare bar and an operation trail agree on when to surface timing. An explicit show_eta=True or show_eta=False overrides it (Click’s own default is True).

click_extra.spinner API

        classDiagram
  ExtraOption <|-- ProgressOption
  Protocol <|-- _AggregateIndicator
  Protocol <|-- _LiveLine
  tuple <|-- SpinnerPreset
    

Where a spinner or a progress bar may draw, see LIVE_MODES.

click_extra.spinner.TLive

Where a spinner or a progress bar may draw, see LIVE_MODES.

alias of Literal[‘auto’, ‘always’, ‘never’]

click_extra.spinner.active_spinner(stream=None)

Return the innermost Spinner currently animating, or None.

A spinner-typed view of _active_line(), skipping any progress-bar indicator that may own the line instead. With stream given, only a spinner drawing on that very stream matches.

Return type:

Spinner | None

click_extra.spinner.LIVE_MODES: tuple[str, ...] = ('auto', 'always', 'never')

The values of the live argument of Spinner and OperationTrail.

• "auto": draw only on an interactive terminal that can move the cursor, and only when the --progress flag of the active command allows it.

• "always": draw on any stream, a pipe or a captured buffer included.

• "never": never draw.

class click_extra.spinner.Spinner(label='', *, frames=None, spinner=None, reverse=False, interval=None, delay=0.0, style=None, label_style=None, timer=None, timer_style=None, stream=None, live='auto', hide_cursor=True, beep=False, enabled=Sentinel.UNSET)

Bases: object

A thread-animated, indeterminate progress spinner usable as a context manager.

The animation runs on a background daemon thread, leaving the calling thread free to block on the actual work. Entering the context (or calling start()) begins the animation; leaving it (or calling stop()) halts the thread and erases the spinner line so it never lingers above the next output.

Note

A single Spinner instance drives one animation at a time. mpm and similar tools run their subprocesses sequentially, so one shared instance whose label is reassigned between steps is enough; for concurrent work, use one instance per thread.

Configure (but do not start) the spinner.

Parameters:

• label (str | Callable[..., Any]) – text shown after the spinner glyph. As a special case, a bare @Spinner decorator passes the wrapped function here instead; it is detected and the label defaults to empty.

• frames (Sequence[str] | None) – the animation frames, cycled in order. Defaults to SPINNER_FRAMES, or the spinner preset’s frames when given.

• spinner (SpinnerPreset | None) – a SpinnerPreset from the SPINNERS catalog (spinner=SPINNERS["moon"]), supplying both frames and a tuned interval. An explicit frames or interval still overrides it.

• reverse (bool) – cycle the frames backwards, spinning the animation the other way. Set it when the rotation runs counter to what you expect; it composes with any custom frames.

• interval (float | None) – seconds between two frames. Defaults to 0.1, or the spinner preset’s interval when given.

• delay (float) – seconds to wait before drawing the first frame. A non-zero delay keeps the spinner silent for calls that finish quickly, so it only surfaces once an operation is genuinely slow.

• style (Style | None) – a Style applied to the spinner glyph, label and timer (Style(fg="cyan", bold=True)). Color is decoupled from animation: --no-color / NO_COLOR strip it while the spinner keeps spinning (see ProgressOption). The strip reaches escapes embedded in label itself too, so a label styled by hand is as safe as one styled through these arguments.

• label_style (Style | None) – a Style for the label alone, in place of style there. It also paints the label of the kept ok() / fail() line, which style leaves plain. It outlives a reassigned label, where styling embedded in the text has to be applied again at every step.

• timer (bool | Callable[[float], str] | None) – append the elapsed wall-clock time to the spinner, and to any final ok() / fail() line. None (the default) follows the CLI’s --time / --no-time flag, as an OperationTrail does. True forces it on with format_duration()’s compact format (2.3s, 1:05, then 1:02:03), False forces it off, and a callable (seconds: float) -> str formats the duration yourself, like timer=lambda s: f"{s / 60:.0f}m" for whole minutes.

• timer_style (Style | None) – a Style for the timer, parentheses included, in place of style there (Style(dim=True) to set the clock back from the label). A timer callable formats only the duration, so it cannot reach the parentheses: this can. Also paints the timer of the kept ok() / fail() line.

• stream (IO[str] | None) – where to draw; defaults to sys.stderr so the spinner never mixes into stdout data.

• live (Literal['auto', 'always', 'never']) – where the animation may draw: "auto" (the default) on an interactive terminal only, unless --no-progress turns it off, "always" on any stream, "never" nowhere. A spinner that does not draw still writes its ok() / fail() line.

• hide_cursor (bool) – hide the text cursor while spinning and restore it on stop.

• beep (bool) – ring the terminal bell once when the spinner stops. It fires only when the spinner was active, so a disabled or redirected spinner stays silent.

• enabled (bool | Literal[UNSET] | None) – deprecated, use live instead: None stands for "auto", True for "always" and False for "never".

Raises:

ValueError – if style, label_style or timer_style carries a color or attribute that cannot be rendered, or if live is not one of LIVE_MODES.

label: str

Text drawn after the spinner glyph.

Reassign it at any time while the spinner runs to reflect the current step; the animation thread reads it afresh on every frame.

property elapsed_time: float

Seconds elapsed since start(), frozen once stop() is called.

Returns 0.0 before the spinner has started.

property shown: bool

Whether the spinner has drawn at least one frame to its stream.

True only once an animation frame was actually rendered. It stays False for a disabled spinner (off a TTY, on a TERM=dumb terminal, or with live="never") and for a call that finishes within delay, before the first frame. Reset by start().

Use it to gate output that should mirror the spinner’s visibility. ok() and fail() write their line unconditionally, so an outcome is still recorded in a pipe or log; guard them with shown when you only want the finisher on screen after a spinner the user actually saw:

with Spinner("Baking bread") as spinner:
    bake()
    if spinner.shown:
        spinner.ok()

frame_lines(*, color=True)

Every line this spinner’s animation draws, one per frame.

One turn of the animation, held still. reverse, the label, the style and the timer all land the way start() would draw them, which is what an animated capture stacks into a picture of this spinner.

Note

The timer is read once, here, so every line carries the same elapsed time rather than a counting one: a still cannot show a clock running. A spinner that never started reads zero.

Parameters:

color (bool) – style each line. On by default, because a capture renders ANSI whatever the terminal the spinner would have drawn on accepts.

Return type:

tuple[str, ...]

Returns:

the lines, in the order the animation cycles them.

start()

Begin animating on a background thread, unless the spinner is disabled.

A disabled spinner (non-TTY stream, or live="never") returns at once without spawning a thread or emitting anything (but still records the start time, so a later ok() / fail() can report a duration).

Return type:

None

stop()

Halt the animation and erase the spinner line.

Idempotent and safe to call when the spinner never started. Restores the cursor and clears the line only if the animation actually drew to the terminal.

Return type:

None

echo(message='')

Print message on its own line above the running spinner.

Click’s click.progressbar() and a bare print both fight the animation: a frame drawn between the cursor returns and the text mangles the line. echo() takes the same draw lock as the animation thread, erases the in-progress frame, writes message followed by a newline, and lets the next tick redraw the spinner underneath. It is safe to call from another thread while the spinner runs.

Output goes to the spinner’s own stream (stderr by default), so results written to stdout never need it. When the spinner is not animating (disabled, or a non-TTY stream), it degrades to a plain write of message with no control codes.

Return type:

None

ok(symbol=None, *, style=None)

Stop the spinner and leave a persistent success line on screen.

Where stop() erases the spinner, ok() replaces the final frame with symbol followed by the current label (and the elapsed time when timer is set), then keeps that line. symbol defaults to the themed success glyph OK_GLYPH (✓), painted with the active theme’s success slot unless style overrides it. Color is stripped under --no-color / NO_COLOR; the glyph stays.

Return type:

None

fail(symbol=None, *, style=None)

Stop the spinner and leave a persistent failure line on screen.

The failure counterpart of ok(), defaulting to KO_GLYPH (✘) painted with the active theme’s error slot.

Return type:

None

click_extra.spinner.trail_glyph(ok)

Return the themed ✓ or ✘ glyph for a trail line or finisher.

The success glyph OK_GLYPH painted with the active theme’s success slot, or the failure glyph KO_GLYPH painted with its error slot.

Return type:

str

click_extra.spinner.trail_line(ok, message)

Format one ✓/✘ trail line: a status glyph followed by message.

Return type:

str

class click_extra.spinner.OperationTrail(*, label='', unit='', total=0, jobs=1, spinner=None, progress_bar=False, timer=None, clock='elapsed', visible=True, live='auto', echo_sequential=True, delay=0.0, stream=None, enabled=Sentinel.UNSET)

Bases: object

A ✓/✘ progress trail and finisher for a batch of operations.

Where Spinner narrates one long-running call, OperationTrail reports a batch of them: each completed operation leaves a persistent trail_line() on screen, a running done/total tally keeps the batch’s pulse visible, and finish() closes with a persistent summary line. The natural reporting companion of the concurrency primitives run_jobs() and run_lanes(), rendered one of three ways:

• sequential (jobs <= 1): echo each outcome as it lands, with no aggregate indicator (each operation is free to keep its own per-call Spinner). finish() appends the elapsed time.

• concurrent (jobs > 1): drive one aggregate Spinner (per-call spinners would collide on the shared stream), buffering outcomes until it first draws, then streaming the rest live above it. Pick the animation from the SPINNERS catalog with spinner=.

• progress bar (progress_bar=True): drive one aggregate determinate bar carrying the {done}/:total:` tally, with outcomes streaming above it. Serves sequential and concurrent batches alike, and needs a known `total.

The aggregate indicators redraw in place, which a pipe or a CI log cannot do, so by default they draw only on an interactive terminal, and live changes where they draw. The ✓/✘ lines and the finisher only append, so they print on any stream, in plain text where color is off. Where no indicator draws, every rendering echoes each outcome as it lands, as the sequential one does. visible=False silences all of it. The running ✓ tally is kept as outcomes land (ok_count), so a caller computes no counts of its own.

Thread-safe: mark() may be called from worker threads. Use it as a context manager whenever it may run concurrently, to bound the aggregate spinner’s life; a purely sequential caller may construct it bare.

from click_extra.execution import run_jobs
from click_extra.spinner import OperationTrail

with OperationTrail(label="Fetching", unit="feeds", total=len(feeds),
                    jobs=jobs) as trail:
    def fetch(feed):
        trail.mark(*pull(feed))  # pull() returns (ok, message).

    list(run_jobs(fetch, feeds, jobs=jobs))
    trail.finish(
        trail.ok_count == len(feeds),
        f"Fetched {trail.ok_count}/{len(feeds)} feeds",
    )

Configure (but do not start) the trail.

Parameters:

• label (str) – present-tense verb for the running aggregate indicator ("Fetching"), composed into its {label} {done}/{total} {unit} tally.

• unit (str) – the noun counted in the tally ("files", "feeds").

• total (int) – how many outcomes are expected, for the done/total count.

• jobs (int) – the batch’s worker count; > 1 selects the concurrent rendering (one aggregate spinner), <= 1 the sequential one (plain echoed lines).

• spinner (SpinnerPreset | None) – a SpinnerPreset from the SPINNERS catalog (spinner=SPINNERS["moon"]) for the concurrent aggregate spinner. Ignored by the sequential and progress-bar renderings, and mutually exclusive with progress_bar.

• progress_bar (bool) – render the aggregate indicator as a determinate click.progressbar() instead of a spinner, for a sequential or concurrent batch alike. Requires a positive total (a bar needs a length) and is mutually exclusive with spinner.

• timer (bool | Callable[[float], str] | None) – append each operation’s and the batch’s elapsed time to the trail lines and the finisher. None (the default) follows the CLI’s --time / --no-time flag; True forces timing on with format_duration()’s compact clock, a callable (seconds: float) -> str forces it on with a custom format, and False forces it off. Per-operation times come from a seconds argument to mark(), filled in automatically by an operation() handle.

• clock (Literal['elapsed', 'eta']) – whether a running aggregate indicator shows elapsed time ("elapsed", the default: a stopwatch counting up, visible from the start) or remaining time ("eta": an estimate from the batch’s rate, appearing only once an outcome lets it be computed). Both the progress bar and the concurrent spinner honor "eta" (the spinner reuses Click’s progress-bar estimate, since the trail knows its total). Per-operation and finisher times are always elapsed.

• visible (bool) – whether the trail shows anything. False silences the lines, the finisher and the aggregate indicator, while ok_count keeps counting.

• live (Literal['auto', 'always', 'never']) – where the aggregate indicator may draw: "auto" (the default) on an interactive terminal only, unless --no-progress turns it off, "always" on any stream, "never" nowhere. Where it does not draw, each outcome line prints as it lands.

• echo_sequential (bool) – whether the batch echoes its outcome lines and finisher as plain lines at all: in a sequential batch, in a batch whose aggregate indicator cannot draw on the stream, and in one that finishes before its indicator first draws. Turn it off when the batch has another output that is the real product (a result table) and the trail would be noise. An indicator that did draw is unaffected.

• delay (float) – seconds before the aggregate indicator first draws: a fast batch then completes without ever flashing one, its lines echoed plainly at finish() instead (see echo_sequential).

• stream (IO[str] | None) – where to render; defaults to sys.stderr so the trail never mixes into stdout data.

• enabled (bool | Literal[UNSET] | None) – deprecated, use visible and live instead: False stands for visible=False, and True for live="always".

Raises:

ValueError – if progress_bar is set without a positive total, or together with spinner, if clock is neither "elapsed" nor "eta", or if live is not one of LIVE_MODES.

property ok_count: int

How many marked outcomes have succeeded so far.

mark(ok, message, seconds=None)

Record one ✓/✘ outcome: tally it and render its trail line.

Parameters:

seconds (float | None) – the operation’s own elapsed time. When timer is on it is formatted and appended to message as (2.3s). An operation() handle fills this in from when it was created; pass it yourself when you already hold a duration.

Return type:

None

finish(ok, summary)

Render the persistent ✓/✘ {summary} finisher.

With an aggregate indicator that drew, it becomes the indicator’s kept line (a spinner’s Spinner.ok() / Spinner.fail() line, or the bar’s replacement line); otherwise, a plain echoed line. The batch’s elapsed time since construction is appended when timer is on.

A batch finishing inside delay never draws its indicator, so none of its buffered lines reached the stream. When the trail is the batch’s output (echo_sequential and visible), they are echoed plainly along with the finisher, the way a sequential batch prints them: how fast a batch ran must not decide whether its record exists.

Return type:

None

operation()

Start a timed operation, returning a handle to record its outcome.

The handle captures the current time; call _Operation.mark() when the work finishes to record its ✓/✘ outcome with the elapsed time appended (when timer is on). This is how a batch reports per-operation timings under concurrency, where the trail itself never sees when an operation began:

def fetch(feed):
    op = trail.operation()
    ok, message = pull(feed)
    op.mark(ok, message)

Return type:

_Operation

class click_extra.spinner.ProgressOption(param_decls=None, *, is_flag=True, default=True, is_eager=True, expose_value=False, help='Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible.', **kwargs)

Bases: ExtraOption

A pre-configured --progress/--no-progress flag gating spinner display.

Resolves to a single boolean published at ctx.meta[click_extra.context.PROGRESS], which Spinner, OperationTrail and progressbar() read on their own when left at their automatic default. The default is True; --accessible lowers it to False (via default_map) so a screen reader is never handed a spinning glyph.

Note

Spinner display is intentionally decoupled from color, even though both emit ANSI. A spinner is an interactivity concern, not a color one: it is built from cursor-control codes (hide-cursor, carriage return, clear-line), which the NO_COLOR standard explicitly does not govern – it “only signals the user’s intention regarding adding ANSI color to text output”. So --no-color / NO_COLOR strip the spinner’s colors but never hide it.

This matches how the wider ecosystem treats the two axes as orthogonal: cargo, npm, pip, Rich, indicatif and ora all gate progress on the terminal (and a dedicated --progress/--quiet knob), while NO_COLOR only affects color. Rich uses TERM=dumb – not NO_COLOR – as the signal to drop cursor-moving features like progress bars.

The spinner is therefore silenced by two things only, neither of them color:

• non-interactive output – a pipe, file, CI log, or TERM=dumb terminal that cannot move the cursor (see Spinner._resolve_live);

• explicit intent – --no-progress or --accessible.

This option is eager. It no longer reads ctx.color, so its position relative to ColorOption is not load-bearing.

set_progress(ctx, param, value)

Publish whether progress spinners may be shown.

Stores the resolved --progress flag at PROGRESS. Deliberately independent of color: see the ProgressOption note for why a spinner is gated on interactivity (TTY / TERM=dumb) and --accessible, never on --no-color / NO_COLOR.

Return type:

None

click_extra.spinner.progressbar(iterable=None, length=None, label=None, hidden=None, show_eta=None, **kwargs)

Drop-in for click.progressbar() honoring --progress and --time.

Click’s own progress bar is determinate, the counterpart to the indeterminate Spinner. This thin wrapper gates its visibility on the same PROGRESS flag the spinner uses, so a single --no-progress (or --accessible, which lowers the progress default) silences both, and gates its estimated-time display on --time.

Parameters:

• hidden (bool | None) – tri-state. Left at its default None, the bar follows the resolved --progress flag: hidden when the user (or --accessible) turned progress off, shown otherwise. An explicit True or False forces the bar regardless, mirroring how an explicit color= argument overrides ctx.color on click.echo(). With no active context (the bar used outside a Click command) it defaults to shown.

• show_eta (bool | None) – tri-state, like hidden. Left at its default None, the estimated-time-remaining display follows the --time / --no-time flag: shown under --time, hidden otherwise (its default, or outside a command). An explicit True or False forces it, keeping a bare bar’s timing in step with an OperationTrail’s timer. Click’s own default is True.

Return type:

ProgressBar[TypeVar(V)]

Note

The --progress flag gates visibility and --time the ETA. Color is already handled upstream: Click renders the bar through click.echo(), whose color=None resolves against ctx.color, so --no-color / NO_COLOR strip the bar’s ANSI without any work from this wrapper.

        classDiagram
  tuple <|-- SpinnerPreset
    

The bundled catalog of terminal spinner presets.

Ported from cli-spinners, with frame intervals converted from milliseconds to seconds.

Note

One upstream entry is deliberately absent. timeTravel is clock running backwards, which upstream has to ship as a second preset because its renderers only play frames forwards. Spinner takes a reverse argument, so the same animation is SPINNERS["clock"] with reverse=True and a duplicate would only be a second name for it.

Note

The emoji frames are one cell narrower than upstream writes them. Upstream pads each with a trailing space, so a terminal drawing the emoji one cell wide still leaves a gap before whatever follows. Here that space is one cell too many: Spinner already writes one before its label, and the pair reads as a double gap. A capture laid out on the frames alone also reserves a column nothing is ever drawn in, which leaves the glyph off center.

Every frame of a preset is the same width, so a label never moves as the animation turns. weather is the one upstream entry that was ragged, mixing two- and three-cell frames.

click_extra.spinner_presets.ASCII_SPINNER_FRAMES: Final = ('-', '\\', '|', '/')

Plain ASCII animation frames, for terminals or fonts lacking Unicode glyphs.

click_extra.spinner_presets.SPINNER_FRAMES: Final = ('⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏')

Default animation frames: the ubiquitous Braille-dots spinner.

Ten frames give a smooth rotation in any UTF-8 terminal. Fall back to ASCII_SPINNER_FRAMES where Braille glyphs are unavailable.

class click_extra.spinner_presets.SpinnerPreset(frames: tuple[str, ...], interval: float)

Bases: NamedTuple

A named spinner animation: its frames and the interval they look best at.

The SPINNERS catalog is ported from cli-spinners, with intervals converted from milliseconds to seconds. Pass one to Spinner via its spinner argument.

Create new instance of SpinnerPreset(frames, interval)

frames: tuple[str, ...]

The animation frames, cycled in order.

interval: float

Seconds between two frames, tuned per spinner upstream.

click_extra.spinner_presets.SPINNERS: Final = {'aesthetic': (('▰▱▱▱▱▱▱', '▰▰▱▱▱▱▱', '▰▰▰▱▱▱▱', '▰▰▰▰▱▱▱', '▰▰▰▰▰▱▱', '▰▰▰▰▰▰▱', '▰▰▰▰▰▰▰', '▰▱▱▱▱▱▱'), 0.08), 'arc': (('◜', '◠', '◝', '◞', '◡', '◟'), 0.1), 'arrow': (('←', '↖', '↑', '↗', '→', '↘', '↓', '↙'), 0.1), 'arrow2': (('⬆️', '↗️', '➡️', '↘️', '⬇️', '↙️', '⬅️', '↖️'), 0.08), 'arrow3': (('▹▹▹▹▹', '▸▹▹▹▹', '▹▸▹▹▹', '▹▹▸▹▹', '▹▹▹▸▹', '▹▹▹▹▸'), 0.12), 'balloon': ((' ', '.', 'o', 'O', '@', '*', ' '), 0.14), 'balloon2': (('.', 'o', 'O', '°', 'O', 'o', '.'), 0.12), 'beta-wave': (('ρββββββ', 'βρβββββ', 'ββρββββ', 'βββρβββ', 'ββββρββ', 'βββββρβ', 'ββββββρ'), 0.08), 'binary': (('010010', '001100', '100101', '111010', '111101', '010111', '101011', '111000', '110011', '110101'), 0.08), 'blue-pulse': (('🔹', '🔷', '🔵', '🔵', '🔷'), 0.1), 'bounce': (('⠁', '⠂', '⠄', '⠂'), 0.12), 'bouncing-ball': (('( ●    )', '(  ●   )', '(   ●  )', '(    ● )', '(     ●)', '(    ● )', '(   ●  )', '(  ●   )', '( ●    )', '(●     )'), 0.08), 'bouncing-bar': (('[    ]', '[=   ]', '[==  ]', '[=== ]', '[====]', '[ ===]', '[  ==]', '[   =]', '[    ]', '[   =]', '[  ==]', '[ ===]', '[====]', '[=== ]', '[==  ]', '[=   ]'), 0.08), 'box-bounce': (('▖', '▘', '▝', '▗'), 0.12), 'box-bounce2': (('▌', '▀', '▐', '▄'), 0.1), 'christmas': (('🌲', '🎄'), 0.4), 'circle': (('◡', '⊙', '◠'), 0.12), 'circle-halves': (('◐', '◓', '◑', '◒'), 0.05), 'circle-quarters': (('◴', '◷', '◶', '◵'), 0.12), 'clock': (('🕛', '🕐', '🕑', '🕒', '🕓', '🕔', '🕕', '🕖', '🕗', '🕘', '🕙', '🕚'), 0.1), 'dots': (('⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'), 0.08), 'dots-8bit': (('⠀', '⠁', '⠂', '⠃', '⠄', '⠅', '⠆', '⠇', '⡀', '⡁', '⡂', '⡃', '⡄', '⡅', '⡆', '⡇', '⠈', '⠉', '⠊', '⠋', '⠌', '⠍', '⠎', '⠏', '⡈', '⡉', '⡊', '⡋', '⡌', '⡍', '⡎', '⡏', '⠐', '⠑', '⠒', '⠓', '⠔', '⠕', '⠖', '⠗', '⡐', '⡑', '⡒', '⡓', '⡔', '⡕', '⡖', '⡗', '⠘', '⠙', '⠚', '⠛', '⠜', '⠝', '⠞', '⠟', '⡘', '⡙', '⡚', '⡛', '⡜', '⡝', '⡞', '⡟', '⠠', '⠡', '⠢', '⠣', '⠤', '⠥', '⠦', '⠧', '⡠', '⡡', '⡢', '⡣', '⡤', '⡥', '⡦', '⡧', '⠨', '⠩', '⠪', '⠫', '⠬', '⠭', '⠮', '⠯', '⡨', '⡩', '⡪', '⡫', '⡬', '⡭', '⡮', '⡯', '⠰', '⠱', '⠲', '⠳', '⠴', '⠵', '⠶', '⠷', '⡰', '⡱', '⡲', '⡳', '⡴', '⡵', '⡶', '⡷', '⠸', '⠹', '⠺', '⠻', '⠼', '⠽', '⠾', '⠿', '⡸', '⡹', '⡺', '⡻', '⡼', '⡽', '⡾', '⡿', '⢀', '⢁', '⢂', '⢃', '⢄', '⢅', '⢆', '⢇', '⣀', '⣁', '⣂', '⣃', '⣄', '⣅', '⣆', '⣇', '⢈', '⢉', '⢊', '⢋', '⢌', '⢍', '⢎', '⢏', '⣈', '⣉', '⣊', '⣋', '⣌', '⣍', '⣎', '⣏', '⢐', '⢑', '⢒', '⢓', '⢔', '⢕', '⢖', '⢗', '⣐', '⣑', '⣒', '⣓', '⣔', '⣕', '⣖', '⣗', '⢘', '⢙', '⢚', '⢛', '⢜', '⢝', '⢞', '⢟', '⣘', '⣙', '⣚', '⣛', '⣜', '⣝', '⣞', '⣟', '⢠', '⢡', '⢢', '⢣', '⢤', '⢥', '⢦', '⢧', '⣠', '⣡', '⣢', '⣣', '⣤', '⣥', '⣦', '⣧', '⢨', '⢩', '⢪', '⢫', '⢬', '⢭', '⢮', '⢯', '⣨', '⣩', '⣪', '⣫', '⣬', '⣭', '⣮', '⣯', '⢰', '⢱', '⢲', '⢳', '⢴', '⢵', '⢶', '⢷', '⣰', '⣱', '⣲', '⣳', '⣴', '⣵', '⣶', '⣷', '⢸', '⢹', '⢺', '⢻', '⢼', '⢽', '⢾', '⢿', '⣸', '⣹', '⣺', '⣻', '⣼', '⣽', '⣾', '⣿'), 0.08), 'dots-circle': (('⢎ ', '⠎⠁', '⠊⠑', '⠈⠱', ' ⡱', '⢀⡰', '⢄⡠', '⢆⡀'), 0.08), 'dots10': (('⢄', '⢂', '⢁', '⡁', '⡈', '⡐', '⡠'), 0.08), 'dots11': (('⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'), 0.1), 'dots12': (('⢀⠀', '⡀⠀', '⠄⠀', '⢂⠀', '⡂⠀', '⠅⠀', '⢃⠀', '⡃⠀', '⠍⠀', '⢋⠀', '⡋⠀', '⠍⠁', '⢋⠁', '⡋⠁', '⠍⠉', '⠋⠉', '⠋⠉', '⠉⠙', '⠉⠙', '⠉⠩', '⠈⢙', '⠈⡙', '⢈⠩', '⡀⢙', '⠄⡙', '⢂⠩', '⡂⢘', '⠅⡘', '⢃⠨', '⡃⢐', '⠍⡐', '⢋⠠', '⡋⢀', '⠍⡁', '⢋⠁', '⡋⠁', '⠍⠉', '⠋⠉', '⠋⠉', '⠉⠙', '⠉⠙', '⠉⠩', '⠈⢙', '⠈⡙', '⠈⠩', '⠀⢙', '⠀⡙', '⠀⠩', '⠀⢘', '⠀⡘', '⠀⠨', '⠀⢐', '⠀⡐', '⠀⠠', '⠀⢀', '⠀⡀'), 0.08), 'dots13': (('⣼', '⣹', '⢻', '⠿', '⡟', '⣏', '⣧', '⣶'), 0.08), 'dots14': (('⠉⠉', '⠈⠙', '⠀⠹', '⠀⢸', '⠀⣰', '⢀⣠', '⣀⣀', '⣄⡀', '⣆⠀', '⡇⠀', '⠏⠀', '⠋⠁'), 0.08), 'dots2': (('⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'), 0.08), 'dots3': (('⠋', '⠙', '⠚', '⠞', '⠖', '⠦', '⠴', '⠲', '⠳', '⠓'), 0.08), 'dots4': (('⠄', '⠆', '⠇', '⠋', '⠙', '⠸', '⠰', '⠠', '⠰', '⠸', '⠙', '⠋', '⠇', '⠆'), 0.08), 'dots5': (('⠋', '⠙', '⠚', '⠒', '⠂', '⠂', '⠒', '⠲', '⠴', '⠦', '⠖', '⠒', '⠐', '⠐', '⠒', '⠓', '⠋'), 0.08), 'dots6': (('⠁', '⠉', '⠙', '⠚', '⠒', '⠂', '⠂', '⠒', '⠲', '⠴', '⠤', '⠄', '⠄', '⠤', '⠴', '⠲', '⠒', '⠂', '⠂', '⠒', '⠚', '⠙', '⠉', '⠁'), 0.08), 'dots7': (('⠈', '⠉', '⠋', '⠓', '⠒', '⠐', '⠐', '⠒', '⠖', '⠦', '⠤', '⠠', '⠠', '⠤', '⠦', '⠖', '⠒', '⠐', '⠐', '⠒', '⠓', '⠋', '⠉', '⠈'), 0.08), 'dots8': (('⠁', '⠁', '⠉', '⠙', '⠚', '⠒', '⠂', '⠂', '⠒', '⠲', '⠴', '⠤', '⠄', '⠄', '⠤', '⠠', '⠠', '⠤', '⠦', '⠖', '⠒', '⠐', '⠐', '⠒', '⠓', '⠋', '⠉', '⠈', '⠈'), 0.08), 'dots9': (('⢹', '⢺', '⢼', '⣸', '⣇', '⡧', '⡗', '⡏'), 0.08), 'dqpb': (('d', 'q', 'p', 'b'), 0.1), 'dwarf-fortress': ((' ██████£££  ', '☺██████£££  ', '☺██████£££  ', '☺▓█████£££  ', '☺▓█████£££  ', '☺▒█████£££  ', '☺▒█████£££  ', '☺░█████£££  ', '☺░█████£££  ', '☺ █████£££  ', ' ☺█████£££  ', ' ☺█████£££  ', ' ☺▓████£££  ', ' ☺▓████£££  ', ' ☺▒████£££  ', ' ☺▒████£££  ', ' ☺░████£££  ', ' ☺░████£££  ', ' ☺ ████£££  ', '  ☺████£££  ', '  ☺████£££  ', '  ☺▓███£££  ', '  ☺▓███£££  ', '  ☺▒███£££  ', '  ☺▒███£££  ', '  ☺░███£££  ', '  ☺░███£££  ', '  ☺ ███£££  ', '   ☺███£££  ', '   ☺███£££  ', '   ☺▓██£££  ', '   ☺▓██£££  ', '   ☺▒██£££  ', '   ☺▒██£££  ', '   ☺░██£££  ', '   ☺░██£££  ', '   ☺ ██£££  ', '    ☺██£££  ', '    ☺██£££  ', '    ☺▓█£££  ', '    ☺▓█£££  ', '    ☺▒█£££  ', '    ☺▒█£££  ', '    ☺░█£££  ', '    ☺░█£££  ', '    ☺ █£££  ', '     ☺█£££  ', '     ☺█£££  ', '     ☺▓£££  ', '     ☺▓£££  ', '     ☺▒£££  ', '     ☺▒£££  ', '     ☺░£££  ', '     ☺░£££  ', '     ☺ £££  ', '      ☺£££  ', '      ☺£££  ', '      ☺▓££  ', '      ☺▓££  ', '      ☺▒££  ', '      ☺▒££  ', '      ☺░££  ', '      ☺░££  ', '      ☺ ££  ', '       ☺££  ', '       ☺££  ', '       ☺▓£  ', '       ☺▓£  ', '       ☺▒£  ', '       ☺▒£  ', '       ☺░£  ', '       ☺░£  ', '       ☺ £  ', '        ☺£  ', '        ☺£  ', '        ☺▓  ', '        ☺▓  ', '        ☺▒  ', '        ☺▒  ', '        ☺░  ', '        ☺░  ', '        ☺   ', '        ☺  &', '        ☺ ☼&', '       ☺ ☼ &', '       ☺☼  &', '      ☺☼  & ', '      ‼   & ', '     ☺   &  ', '    ‼    &  ', '   ☺    &   ', '  ‼     &   ', ' ☺     &    ', '‼      &    ', '      &     ', '      &     ', '     &   ░  ', '     &   ▒  ', '    &    ▓  ', '    &    £  ', '   &    ░£  ', '   &    ▒£  ', '  &     ▓£  ', '  &     ££  ', ' &     ░££  ', ' &     ▒££  ', '&      ▓££  ', '&      £££  ', '      ░£££  ', '      ▒£££  ', '      ▓£££  ', '      █£££  ', '     ░█£££  ', '     ▒█£££  ', '     ▓█£££  ', '     ██£££  ', '    ░██£££  ', '    ▒██£££  ', '    ▓██£££  ', '    ███£££  ', '   ░███£££  ', '   ▒███£££  ', '   ▓███£££  ', '   ████£££  ', '  ░████£££  ', '  ▒████£££  ', '  ▓████£££  ', '  █████£££  ', ' ░█████£££  ', ' ▒█████£££  ', ' ▓█████£££  ', ' ██████£££  ', ' ██████£££  '), 0.08), 'earth': (('🌍', '🌎', '🌏'), 0.18), 'finger-dance': (('🤘', '🤟', '🖖', '✋', '🤚', '👆'), 0.16), 'fish': (('~~~~~~~~~~~~~~~~~~~~', '> ~~~~~~~~~~~~~~~~~~', 'º> ~~~~~~~~~~~~~~~~~', '(º> ~~~~~~~~~~~~~~~~', '((º> ~~~~~~~~~~~~~~~', '<((º> ~~~~~~~~~~~~~~', '><((º> ~~~~~~~~~~~~~', ' ><((º> ~~~~~~~~~~~~', '~ ><((º> ~~~~~~~~~~~', '~~ <>((º> ~~~~~~~~~~', '~~~ ><((º> ~~~~~~~~~', '~~~~ <>((º> ~~~~~~~~', '~~~~~ ><((º> ~~~~~~~', '~~~~~~ <>((º> ~~~~~~', '~~~~~~~ ><((º> ~~~~~', '~~~~~~~~ <>((º> ~~~~', '~~~~~~~~~ ><((º> ~~~', '~~~~~~~~~~ <>((º> ~~', '~~~~~~~~~~~ ><((º> ~', '~~~~~~~~~~~~ <>((º> ', '~~~~~~~~~~~~~ ><((º>', '~~~~~~~~~~~~~~ <>((º', '~~~~~~~~~~~~~~~ ><((', '~~~~~~~~~~~~~~~~ <>(', '~~~~~~~~~~~~~~~~~ ><', '~~~~~~~~~~~~~~~~~~ <', '~~~~~~~~~~~~~~~~~~~~'), 0.08), 'fist-bump': (('🤜\u3000\u3000\u3000\u3000🤛', '🤜\u3000\u3000\u3000\u3000🤛', '🤜\u3000\u3000\u3000\u3000🤛', '\u3000🤜\u3000\u3000🤛\u3000', '\u3000\u3000🤜🤛\u3000\u3000', '\u3000🤜✨🤛\u3000\u3000', '🤜\u3000✨\u3000🤛\u3000'), 0.08), 'flip': (('_', '_', '_', '-', '`', '`', "'", '´', '-', '_', '_', '_'), 0.07), 'grenade': (('،  ', '′  ', ' ´ ', ' ‾ ', '  ⸌', '  ⸊', '  |', '  ⁎', '  ⁕', ' ෴ ', '  ⁓', '   ', '   ', '   '), 0.08), 'grow-horizontal': (('▏', '▎', '▍', '▌', '▋', '▊', '▉', '▊', '▋', '▌', '▍', '▎'), 0.12), 'grow-vertical': (('▁', '▃', '▄', '▅', '▆', '▇', '▆', '▅', '▄', '▃'), 0.12), 'hamburger': (('☱', '☲', '☴'), 0.1), 'hearts': (('💛', '💙', '💜', '💚', '💗'), 0.1), 'layer': (('-', '=', '≡'), 0.15), 'line': (('-', '\\', '|', '/'), 0.13), 'line2': (('⠂', '-', '–', '—', '–', '-'), 0.1), 'material': (('█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '███▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '████▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '██████▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '██████▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '███████▁▁▁▁▁▁▁▁▁▁▁▁▁', '████████▁▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '██████████▁▁▁▁▁▁▁▁▁▁', '███████████▁▁▁▁▁▁▁▁▁', '█████████████▁▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁▁██████████████▁▁▁▁', '▁▁▁██████████████▁▁▁', '▁▁▁▁█████████████▁▁▁', '▁▁▁▁██████████████▁▁', '▁▁▁▁██████████████▁▁', '▁▁▁▁▁██████████████▁', '▁▁▁▁▁██████████████▁', '▁▁▁▁▁██████████████▁', '▁▁▁▁▁▁██████████████', '▁▁▁▁▁▁██████████████', '▁▁▁▁▁▁▁█████████████', '▁▁▁▁▁▁▁█████████████', '▁▁▁▁▁▁▁▁████████████', '▁▁▁▁▁▁▁▁████████████', '▁▁▁▁▁▁▁▁▁███████████', '▁▁▁▁▁▁▁▁▁███████████', '▁▁▁▁▁▁▁▁▁▁██████████', '▁▁▁▁▁▁▁▁▁▁██████████', '▁▁▁▁▁▁▁▁▁▁▁▁████████', '▁▁▁▁▁▁▁▁▁▁▁▁▁███████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁██████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█████', '█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '███▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '████▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '█████▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '█████▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '██████▁▁▁▁▁▁▁▁▁▁▁▁▁█', '████████▁▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '███████████▁▁▁▁▁▁▁▁▁', '████████████▁▁▁▁▁▁▁▁', '████████████▁▁▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁▁▁█████████████▁▁▁▁', '▁▁▁▁▁████████████▁▁▁', '▁▁▁▁▁████████████▁▁▁', '▁▁▁▁▁▁███████████▁▁▁', '▁▁▁▁▁▁▁▁█████████▁▁▁', '▁▁▁▁▁▁▁▁█████████▁▁▁', '▁▁▁▁▁▁▁▁▁█████████▁▁', '▁▁▁▁▁▁▁▁▁█████████▁▁', '▁▁▁▁▁▁▁▁▁▁█████████▁', '▁▁▁▁▁▁▁▁▁▁▁████████▁', '▁▁▁▁▁▁▁▁▁▁▁████████▁', '▁▁▁▁▁▁▁▁▁▁▁▁███████▁', '▁▁▁▁▁▁▁▁▁▁▁▁███████▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁███████', '▁▁▁▁▁▁▁▁▁▁▁▁▁███████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁'), 0.017), 'mindblown': (('😐', '😐', '😮', '😮', '😦', '😦', '😧', '😧', '🤯', '💥', '✨', '\u3000', '\u3000', '\u3000'), 0.16), 'monkey': (('🙈', '🙈', '🙉', '🙊'), 0.3), 'moon': (('🌑', '🌒', '🌓', '🌔', '🌕', '🌖', '🌗', '🌘'), 0.08), 'noise': (('▓', '▒', '░'), 0.1), 'orange-blue-pulse': (('🔸', '🔶', '🟠', '🟠', '🔶', '🔹', '🔷', '🔵', '🔵', '🔷'), 0.1), 'orange-pulse': (('🔸', '🔶', '🟠', '🟠', '🔶'), 0.1), 'pipe': (('┤', '┘', '┴', '└', '├', '┌', '┬', '┐'), 0.1), 'point': (('∙∙∙', '●∙∙', '∙●∙', '∙∙●', '∙∙∙'), 0.125), 'pong': (('▐⠂       ▌', '▐⠈       ▌', '▐ ⠂      ▌', '▐ ⠠      ▌', '▐  ⡀     ▌', '▐  ⠠     ▌', '▐   ⠂    ▌', '▐   ⠈    ▌', '▐    ⠂   ▌', '▐    ⠠   ▌', '▐     ⡀  ▌', '▐     ⠠  ▌', '▐      ⠂ ▌', '▐      ⠈ ▌', '▐       ⠂▌', '▐       ⠠▌', '▐       ⡀▌', '▐      ⠠ ▌', '▐      ⠂ ▌', '▐     ⠈  ▌', '▐     ⠂  ▌', '▐    ⠠   ▌', '▐    ⡀   ▌', '▐   ⠠    ▌', '▐   ⠂    ▌', '▐  ⠈     ▌', '▐  ⠂     ▌', '▐ ⠠      ▌', '▐ ⡀      ▌', '▐⠠       ▌'), 0.08), 'rolling-line': (('/  ', ' - ', ' \\ ', '  |', '  |', ' \\ ', ' - ', '/  '), 0.08), 'runner': (('🚶', '🏃'), 0.14), 'sand': (('⠁', '⠂', '⠄', '⡀', '⡈', '⡐', '⡠', '⣀', '⣁', '⣂', '⣄', '⣌', '⣔', '⣤', '⣥', '⣦', '⣮', '⣶', '⣷', '⣿', '⡿', '⠿', '⢟', '⠟', '⡛', '⠛', '⠫', '⢋', '⠋', '⠍', '⡉', '⠉', '⠑', '⠡', '⢁'), 0.08), 'shark': (('▐|\\____________▌', '▐_|\\___________▌', '▐__|\\__________▌', '▐___|\\_________▌', '▐____|\\________▌', '▐_____|\\_______▌', '▐______|\\______▌', '▐_______|\\_____▌', '▐________|\\____▌', '▐_________|\\___▌', '▐__________|\\__▌', '▐___________|\\_▌', '▐____________|\\▌', '▐____________/|▌', '▐___________/|_▌', '▐__________/|__▌', '▐_________/|___▌', '▐________/|____▌', '▐_______/|_____▌', '▐______/|______▌', '▐_____/|_______▌', '▐____/|________▌', '▐___/|_________▌', '▐__/|__________▌', '▐_/|___________▌', '▐/|____________▌'), 0.12), 'simple-dots': (('.  ', '.. ', '...', '   '), 0.4), 'simple-dots-scrolling': (('.  ', '.. ', '...', ' ..', '  .', '   '), 0.2), 'smiley': (('😄', '😝'), 0.2), 'soccer-header': ((' 🧑⚽️       🧑', '🧑  ⚽️      🧑', '🧑   ⚽️     🧑', '🧑    ⚽️    🧑', '🧑     ⚽️   🧑', '🧑      ⚽️  🧑', '🧑       ⚽️🧑 ', '🧑      ⚽️  🧑', '🧑     ⚽️   🧑', '🧑    ⚽️    🧑', '🧑   ⚽️     🧑', '🧑  ⚽️      🧑'), 0.08), 'speaker': (('🔈', '🔉', '🔊', '🔉'), 0.16), 'square-corners': (('◰', '◳', '◲', '◱'), 0.18), 'squish': (('╫', '╪'), 0.1), 'star': (('✶', '✸', '✹', '✺', '✹', '✷'), 0.07), 'star2': (('+', 'x', '*'), 0.08), 'toggle': (('⊶', '⊷'), 0.25), 'toggle10': (('㊂', '㊀', '㊁'), 0.1), 'toggle11': (('⧇', '⧆'), 0.05), 'toggle12': (('☗', '☖'), 0.12), 'toggle13': (('=', '*', '-'), 0.08), 'toggle2': (('▫', '▪'), 0.08), 'toggle3': (('□', '■'), 0.12), 'toggle4': (('■', '□', '▪', '▫'), 0.1), 'toggle5': (('▮', '▯'), 0.1), 'toggle6': (('ဝ', '၀'), 0.3), 'toggle7': (('⦾', '⦿'), 0.08), 'toggle8': (('◍', '◌'), 0.1), 'toggle9': (('◉', '◎'), 0.1), 'triangle': (('◢', '◣', '◤', '◥'), 0.05), 'weather': (('☀️', '☀️', '☀️', '🌤 ', '⛅️', '🌥 ', '☁️', '🌧 ', '🌨 ', '🌧 ', '🌨 ', '🌧 ', '🌨 ', '⛈ ', '🌨 ', '🌧 ', '🌨 ', '☁️', '🌥 ', '⛅️', '🌤 ', '☀️', '☀️'), 0.1)}

Named spinner animations ported from cli-spinners, keyed by name.

Each value is a SpinnerPreset bundling frames and a tuned interval. Select one with Spinner’s spinner argument:

from click_extra import Spinner, SPINNERS

with Spinner("Brewing tea", spinner=SPINNERS["moon"]):
    ...

Unlike the upstream \b-based renderers, Spinner redraws the whole line, so the multi-character animations (bouncingBar, pong, shark, …) render correctly here.