NumberField

Numeric input with optional stepper buttons, bounds enforcement, and keyboard/ mouse-wheel stepping.

Usage

Basic

bs.NumberField()
bs.NumberField(42)
bs.NumberField(3.14, step=0.01)

Label and message

Use label= for a field title and message= for helper text below.

bs.NumberField(
    label="Quantity",
    message="Enter a value between 0 and 100.",
)

Required

Set required=True to mark the field visually and prevent empty submission.

bs.NumberField(label="Quantity", required=True)

Bounds and step

Use min_value=, max_value=, and step= to constrain input. Arrow keys and the mouse wheel step by step. Stepper buttons disable automatically at the bounds. Set wrap=True to wrap from the maximum back to the minimum (and vice versa) when stepping past a bound.

bs.NumberField(min_value=0,   max_value=100, step=5,   label="0–100, step 5")
bs.NumberField(min_value=0.0, max_value=1.0, step=0.1, label="0.0–1.0, step 0.1")
bs.NumberField(min_value=1, max_value=12, value=12, wrap=True, label="Month (wraps)")

Stepper buttons

The +/− buttons are shown by default. Hide them with show_steppers=False.

bs.NumberField(label="With steppers", value=25)
bs.NumberField(label="No steppers",   value=25, show_steppers=False)

Programmatic stepping

Call increment() and decrement() to step the value in code.

field = bs.NumberField(value=10, step=5)
field.increment()    # → 15
field.decrement(2)   # → 5
field.clear()        # empties the field — value becomes None, not 0

Value formatting

Use value_format= to display the number with a locale-aware ICU pattern. The raw numeric value is preserved internally; only the display changes. Requires localization to be enabled.

bs.NumberField(1234567, value_format="#,##0",    label="Thousands",  show_steppers=False)
bs.NumberField(3.14159, value_format="#,##0.00", label="2 decimals", show_steppers=False)
bs.NumberField(0.75,    value_format="percent",  label="Percent",    show_steppers=False)
bs.NumberField(9.99,    value_format="currency", label="Currency",   show_steppers=False)

States

bs.NumberField(value=42, label="Normal")
bs.NumberField(value=42, label="Read only", read_only=True)
bs.NumberField(value=42, label="Disabled",  disabled=True)

Reactive binding

Bind a Signal with textsignal=. The field and signal stay in sync automatically. Initialize the signal with a string value, not a number.

qty = bs.Signal("1")
bs.NumberField(label="Quantity", textsignal=qty, min_value=1)
bs.Label(textsignal=qty, accent="secondary")

Validation

Attach rules with add_validation_rule(). Rules run on the configured trigger ('blur', 'key', or 'manual').

field = bs.NumberField(label="Age")
field.add_validation_rule(
    "custom",
    func=lambda v: v != "" and 0 <= float(v) <= 120,
    message="Age must be between 0 and 120.",
    trigger="blur",
)

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).

See also

• TextField — plain text input

• PasswordField — masked password input

• Slider — drag-to-set numeric value

API

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

NumberField

A numeric input field with optional stepper buttons.

Full Example

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

    # Basic
    bs.Label("Basic", font="heading-sm")
    with bs.HStack(gap=8, anchor_items="s"):
        bs.NumberField()
        bs.NumberField(3.14, step=0.01, label="Float step")

    # Label, message, required
    bs.Label("Label, Message, Required", font="heading-sm")
    bs.NumberField(
        label="Quantity",
        message="Enter a value between 0 and 100.",
        required=True,
        fill="x",
    )

    # Bounds and step
    bs.Label("Bounds and Step", font="heading-sm")
    with bs.HStack(gap=8, fill="x", fill_items="x", expand_items=True):
        bs.NumberField(min_value=0, max_value=100, step=5, label="0–100, step 5")
        bs.NumberField(min_value=0.0, max_value=1.0, step=0.1, label="0.0–1.0, step 0.1")

    # Stepper buttons
    bs.Label("Stepper Buttons", font="heading-sm")
    with bs.HStack(gap=8, fill="x", fill_items="x", expand_items=True):
        bs.NumberField(label="With steppers", value=25)
        bs.NumberField(label="No steppers",   value=25, show_steppers=False)

    # Value formatting
    bs.Label("Value Formatting", font="heading-sm")
    with bs.Grid(columns=[1, 1], gap=8, fill="x", sticky_items="ew"):
        bs.NumberField(1234567, value_format="#,##0",    label="Thousands",  show_steppers=False)
        bs.NumberField(3.14159, value_format="#,##0.00", label="2 decimals", show_steppers=False)
        bs.NumberField(0.75,    value_format="percent",  label="Percent",    show_steppers=False)
        bs.NumberField(9.99,    value_format="currency", label="Currency",   show_steppers=False)

    # States
    bs.Label("States", font="heading-sm")
    with bs.HStack(gap=8, fill="x", fill_items="x", expand_items=True):
        bs.NumberField(value=42, label="Normal")
        bs.NumberField(value=42, label="Read only", read_only=True)
        bs.NumberField(value=42, label="Disabled",  disabled=True)

app.run()