ProgressBar

A horizontal or vertical progress indicator. Use the determinate mode to show a fixed fill proportional to a known value, or the indeterminate mode for operations whose duration is unknown.

Usage

The main decision is mode: determinate fill tracks a known value (0 to max_value), while indeterminate animates continuously for work of unknown length. Bind value to a Signal with signal= to drive the fill live.

Determinate progress

Set value between 0 and max_value (default 100) to control the fill level. The bar fills proportionally.

bs.ProgressBar(value=0)    # empty
bs.ProgressBar(value=50)   # half full
bs.ProgressBar(value=100)  # complete

Read or update the value at any time via the value property:

bar = bs.ProgressBar(value=0)
bar.value = 42
print(bar.value)   # 42.0

Indeterminate mode

Use mode='indeterminate' for operations of unknown duration. Call start() to begin the animation and stop() to end it.

bar = bs.ProgressBar(mode="indeterminate")
bar.start()      # begins looping animation
# ... do work ...
bar.stop()

step(amount) advances the fill by amount (default 1.0) when you want manual control instead of an animation:

bar = bs.ProgressBar(value=0)
bar.step(10)   # value → 10
bar.step(10)   # value → 20

Signal binding

Pass a Signal to keep the bar in sync with a reactive value:

progress = bs.Signal(0.0)
bs.ProgressBar(signal=progress)
progress.value = 75   # bar updates automatically

Accent colors

bs.ProgressBar(value=65, accent="primary")
bs.ProgressBar(value=65, accent="secondary")
bs.ProgressBar(value=65, accent="info")
bs.ProgressBar(value=65, accent="success")
bs.ProgressBar(value=65, accent="warning")
bs.ProgressBar(value=65, accent="danger")

Thin variant

variant='thin' reduces the bar height for compact layouts or subtle progress indicators:

bs.ProgressBar(value=40, variant="thin")
bs.ProgressBar(value=70, accent="primary", variant="thin")
bs.ProgressBar(value=90, accent="success", variant="thin")

Vertical orientation

bs.ProgressBar(value=25, orient="vertical")
bs.ProgressBar(value=50, orient="vertical")
bs.ProgressBar(value=75, orient="vertical")
bs.ProgressBar(value=100, orient="vertical")

Custom max value

Set max_value to match your data’s natural scale:

bs.ProgressBar(value=750, max_value=1000, accent="info")

Widget sizing

All widgets accept self-placement kwargs via **kwargs. The parent container determines which options apply — Column / Row parents use the layout kwargs below, grid-based parents use grid kwargs.

Column (vertical layout)

Used inside a Column, App, or any other container with a column layout. Children are arranged top-to-bottom, so horizontal aligns each child across the width and grow shares the vertical space. (vertical does not apply — the order of the children sets their top-to-bottom position.)

horizontal	Cross-axis placement of the widget: 'left', 'center', 'right', or 'stretch' to fill the available width.
grow	Claim and fill a share of the leftover vertical space (the layout direction). True or False.
margin	External spacing in pixels. Accepts an integer (equal on all sides), a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing (left and right). Accepts an integer or a 2-tuple (left, right) for asymmetric spacing. Overrides the horizontal component of margin=.
margin_y	Vertical external spacing (top and bottom). Accepts an integer or a 2-tuple (top, bottom) for asymmetric spacing. Overrides the vertical component of margin=.

Row (horizontal layout)

Used inside a Row or any other container with a row layout. Children are arranged left-to-right, so vertical aligns each child across the height and grow shares the horizontal space. (horizontal does not apply — the order of the children sets their left-to-right position.)

vertical	Cross-axis placement of the widget: 'top', 'center', 'bottom', or 'stretch' to fill the available height.
grow	Claim and fill a share of the leftover horizontal space (the layout direction). True or False.
margin	External spacing in pixels. Accepts an integer (equal on all sides), a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing (left and right). Accepts an integer or a 2-tuple (left, right) for asymmetric spacing. Overrides the horizontal component of margin=.
margin_y	Vertical external spacing (top and bottom). Accepts an integer or a 2-tuple (top, bottom) for asymmetric spacing. Overrides the vertical component of margin=.

Grid

Used inside a Grid container.

row / column	Zero-based row and column indices.
rowspan / columnspan	Number of rows or columns to span.
horizontal	Horizontal placement within the grid cell: 'left', 'center', 'right', or 'stretch' to fill the cell width.
vertical	Vertical placement within the grid cell: 'top', 'center', 'bottom', or 'stretch' to fill the cell height.
margin	External spacing in pixels. Accepts an integer, a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing. Accepts an integer or (left, right).
margin_y	Vertical external spacing. Accepts an integer or (top, bottom).

API

The complete reference for ProgressBar lives on the Widgets API page. At a glance:

ProgressBar

A progress indicator bar.

Full Example

with bs.App(title="ProgressBar Demo", padding=20, gap=0) as app:
    with bs.Grid(columns=[1, 1], gap=(32, 20), vertical_items="top", horizontal="stretch", grow=True):

        # Quadrant 1 — Determinate progress
        with bs.Column(gap=8, horizontal_items="stretch"):
            bs.Label("Determinate Progress", font="heading-sm")
            for pct in (0, 25, 50, 75, 100):
                bs.ProgressBar(value=pct)

        # Quadrant 2 — Accent colors
        with bs.Column(gap=8, horizontal_items="stretch"):
            bs.Label("Accent Colors", font="heading-sm")
            for accent in ("primary", "secondary", "info", "success", "warning", "danger"):
                bs.ProgressBar(value=65, accent=accent)

        # Quadrant 3 — Thin variant
        with bs.Column(gap=8, horizontal_items="stretch"):
            bs.Label("Thin Variant", font="heading-sm")
            bs.ProgressBar(value=40, variant="thin")
            bs.ProgressBar(value=70, accent="primary", variant="thin")
            bs.ProgressBar(value=90, accent="success", variant="thin")

        # Quadrant 4 — Vertical orientation
        with bs.Column(gap=8, horizontal_items="stretch"):
            bs.Label("Vertical Orientation", font="heading-sm")
            with bs.Row(gap=12):
                for pct in (25, 50, 75, 100):
                    bs.ProgressBar(value=pct, orient="vertical")

app.run()