Gauge

A circular arc gauge for displaying a value within a range. Supports full-circle and semicircle layouts, solid and segmented arc styles, optional center text with prefix/suffix formatting, and an interactive drag mode.

Usage

Variants

'full' (default) draws a complete 360° ring. 'semi' draws a half-circle arc along the bottom, useful for dashboards.

bs.Gauge(value=68, variant="full", subtitle="Full")
bs.Gauge(value=68, variant="semi", subtitle="Semi")

Value range

Set min_value and max_value to match your data’s natural scale:

bs.Gauge(value=750, min_value=0, max_value=1000, subtitle="Requests/s")

Update the value at runtime via the value property. min_value and max_value are live properties too — assign to them to rescale the gauge as your data’s range changes:

gauge = bs.Gauge(value=0, max_value=100)
gauge.value = 65
gauge.max_value = 2000     # rescale the arc

Labels and formatting

subtitle appears below the value. value_prefix and value_suffix flank the number. value_template is a Python format string applied to the raw value.

bs.Gauge(value=4200, max_value=10000,
         value_prefix="$", value_template="{:.0f}",
         subtitle="Revenue", accent="success")

bs.Gauge(value=72, value_suffix="%", subtitle="Disk Used", accent="warning")

bs.Gauge(value=3.7, max_value=5.0, value_template="{:.1f}",
         subtitle="Rating", accent="primary")

Update the subtitle at runtime via the subtitle property:

gauge = bs.Gauge(value=50, subtitle="Loading…")
gauge.subtitle = "Ready"

Accent colors

bs.Gauge(value=65, accent="primary")
bs.Gauge(value=65, accent="success")
bs.Gauge(value=65, accent="warning")
bs.Gauge(value=65, accent="danger")

Segmented arc

Set segment_width to a positive integer to draw a dashed arc. Smaller values produce finer dashes:

bs.Gauge(value=55, segment_width=8,  accent="primary")   # coarse segments
bs.Gauge(value=55, segment_width=4,  accent="secondary") # fine segments

Arc thickness

thickness controls the stroke width in pixels:

bs.Gauge(value=70, thickness=6,  subtitle="Thin")
bs.Gauge(value=70, thickness=14, subtitle="Default")
bs.Gauge(value=70, thickness=24, subtitle="Thick")

Size

size sets the diameter in pixels (default 200):

bs.Gauge(value=60, size=120)   # compact
bs.Gauge(value=60, size=200)   # default
bs.Gauge(value=60, size=300)   # large

Interactive mode

interactive=True lets the user click or drag the arc to change the value. step controls how much each drag step changes the value:

bs.Gauge(value=50, interactive=True, step=5, accent="primary")

Listen for changes via on_change:

gauge = bs.Gauge(value=50, interactive=True)
gauge.on_change(lambda e: print("value:", gauge.value))

Widget sizing

All widgets accept self-placement kwargs via **kwargs. The parent container determines which options apply — stack-based parents use stack kwargs, grid-based parents use grid kwargs. Unrecognised keys are silently ignored.

Stack

Used inside VStack, HStack, App, and other stack containers.

fill	Fill direction: 'x', 'y', 'both', or 'none'.
expand	Grow to consume extra space in the parent. True or False.
anchor	Alignment when the widget does not fill the available slot: 'n', 's', 'e', 'w', 'center', 'nw', etc.
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.
sticky	Alignment and fill within the grid cell. Any combination of 'n', 's', 'e', 'w' — e.g. 'ew' stretches horizontally, 'nsew' fills the entire cell.
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 Gauge lives on the Widgets API page. At a glance:

Gauge

A circular gauge for displaying a value within a range.

Full Example

with bs.App(title="Gauge Demo", padding=20, gap=16) as app:

    # Full vs semi meter types
    bs.Label("Variants", font="heading-sm")
    with bs.HStack(gap=20):
        bs.Gauge(value=68, variant="full", subtitle="Full")
        bs.Gauge(value=68, variant="semi", subtitle="Semi")

    # Accent colors
    bs.Label("Accent Colors", font="heading-sm")
    with bs.HStack(gap=12):
        for accent in ("primary", "secondary", "info", "success", "warning", "danger"):
            bs.Gauge(value=65, accent=accent, size=140, thickness=14, subtitle=accent.title())

    # Prefix / suffix / subtitle
    bs.Label("Labels and Formatting", font="heading-sm")
    with bs.HStack(gap=20):
        bs.Gauge(value=4200, max_value=10000, value_prefix="$", value_template="{:.0f}",
                 subtitle="Revenue", accent="success")
        bs.Gauge(value=72, value_suffix="%", subtitle="Disk Used", accent="warning")
        bs.Gauge(value=3.7, max_value=5.0, value_template="{:.1f}", subtitle="Rating",
                 accent="primary")

    # Segmented / dashed arc
    bs.Label("Segmented Arc", font="heading-sm")
    with bs.HStack(gap=20):
        bs.Gauge(value=55, segment_width=8, subtitle="Segmented", accent="primary")
        bs.Gauge(value=55, segment_width=4, thickness=12, subtitle="Fine segments",
                 accent="secondary")

    # Thickness variants
    bs.Label("Thickness", font="heading-sm")
    with bs.HStack(gap=20):
        bs.Gauge(value=70, thickness=6,  subtitle="Thin",   accent="info")
        bs.Gauge(value=70, thickness=14, subtitle="Default", accent="info")
        bs.Gauge(value=70, thickness=24, subtitle="Thick",  accent="info")

app.run()