Skip to content

Spinbox

Spinbox is a primitive input that wraps bs.Spinbox with bootstack styling and reactive text support.

It provides low-level spin behavior (range or list stepping) while still allowing direct typing. Use Spinbox when you want native ttk options like format and command. For a form-ready field with labels/messages/validation and standardized events, prefer SpinnerEntry.

Quick start

Numeric range

import bootstack as bs

app = bs.App()

spin = bs.Spinbox(app, from_=0, to=10, increment=1, width=8)
spin.pack(padx=20, pady=20)

app.mainloop()

Fixed list of values

import bootstack as bs

app = bs.App()

spin = bs.Spinbox(app, values=("XS", "S", "M", "L", "XL"), wrap=True, width=8)
spin.pack(padx=20, pady=20)

app.mainloop()

When to use

Use Spinbox when:

  • you want low-level ttk spinbox behavior and options

  • the range/list is small and predictable

  • you're building your own composite control

Consider a different control when...

  • you want a form-ready field (labels/messages/validation/events) - prefer SpinnerEntry

  • the choices are better expressed as a dropdown list - prefer SelectBox

Appearance

accent

Applies bootstack theme styling.

bs.Spinbox(app, from_=0, to=10, accent="primary")

Design System

See the Design System for available color tokens.

Examples and patterns

Value model

Spinbox stores and returns text (even in numeric mode).

value = spin.get()

Bind with:

  • textvariable= (Tk variable), or

  • textsignal= (reactive signal)

Common options

Range mode: from_, to, increment

bs.Spinbox(app, from_=1, to=31, increment=1)

Values mode: values

bs.Spinbox(app, values=("Low", "Medium", "High"))

If values is provided, it takes precedence over the numeric range.

wrap

bs.Spinbox(app, from_=0, to=5, wrap=True)
bs.Spinbox(app, values=("A", "B", "C"), wrap=True)

state="readonly"

Use readonly mode when you want pick-only interaction.

bs.Spinbox(app, values=("A", "B", "C"), state="readonly")

format (range mode)

bs.Spinbox(app, from_=0, to=1, increment=0.05, format="%.2f")

Events

command

def on_change():
    print(spin.get())

spin = bs.Spinbox(app, from_=0, to=10, command=on_change)

If you need to respond to typing, bind key events:

spin.bind("<KeyRelease>", lambda e: print(spin.get()))

Behavior

  • Users can type or use arrows to step.

  • In many Tk builds, command is primarily invoked by arrow interactions (not typing).

  • Wrapping cycles max->min (range) or last->first (values).

Validation and constraints

Spinbox does not provide control-level parsing/validation by default. It is a primitive widget.

For validated, commit-based workflows, prefer SpinnerEntry or NumericEntry.

Additional resources

Framework concepts

API reference