ProgressBar

The ProgressBar widget displays a horizontal progress indicator that can be updated dynamically from Python.
It supports both determinate (percentage-based) and indeterminate (animated) modes and integrates with Mercury layout placement.

This widget is ideal for:

long-running computations
data processing pipelines
model training or evaluation
file uploads / downloads
multi-step workflows

Basic Usage

Determinate Progress

import mercury as mr

progress = mr.ProgressBar(
    label="Processing data",
    value=0
)

progress.set(25)
progress.set(50)
progress.set(75)
progress.set(100)

The progress bar updates immediately when set() is called.

Indeterminate Mode

Use indeterminate mode when progress cannot be measured.

import mercury as mr
import time

progress = mr.ProgressBar(
    label="Loading",
    indeterminate=True
)

time.sleep(2)

progress.set_indeterminate(False)
progress.set(100)

Updating the Label

You can update the label text dynamically:

import mercury as mr

progress = mr.ProgressBar(label="Step 1/3")
progress.set_label("Step 2/3")
progress.set_label("Step 3/3")

Layout

Control where the progress bar is rendered using position:

import mercury as mr

mr.ProgressBar(
    label="Sidebar task",
    position="sidebar"
)

Available values:

"inline" — main view (default)
"sidebar" — left sidebar
"bottom" — bottom area

ProgressBar Params

label

type: string

Optional text displayed above the progress bar.

Default: ""

value

type: float

Initial progress value for determinate mode.

Default: 0

min / max

type: float

Value range used to compute percentage.

Defaults:

min = 0
max = 100

show_percent

type: bool

Show or hide the percentage text.

Default: True

indeterminate

type: bool

Start the progress bar in animated indeterminate mode.

Default: False

position

type: "sidebar" | "inline" | "bottom"

Controls widget placement in the Mercury layout.

Default: "inline"

key

type: string

Stable identifier used to reuse the same widget instance.

ProgressHandle API

The ProgressBar() function returns a ProgressHandle object.

Common Methods

set(value) — update progress value
set_label(text) — update label text
set_indeterminate(on=True) — toggle indeterminate mode
show() — display the progress bar
hide() — hide the progress bar

Notes

Progress is clamped to the [min, max] range.
Setting a value disables indeterminate mode automatically.
The widget is rendered immediately when created.