Spinbox#

Spinbox is the native ttk text field with up/down arrows for stepping through numeric or listed values (ttk.Spinbox), themed by ttkbootstrap. This page is the complete reference for its options, methods, and styling.

Options#

Each option can be set in the constructor and changed later with configure().

Option	Type	Description
`bootstyle`	`str`	Constructor keyword. An accent color, optionally with a variant. See Styling options for the available styles.
`textvariable`	`Variable`	A `StringVar` bound to the field’s contents.
`from_`	`float`	The minimum value in the numeric range.
`to`	`float`	The maximum value in the numeric range.
`increment`	`float`	The amount each arrow press steps the value.
`values`	`list`	An explicit list of values to step through, instead of a numeric range.
`format`	`str`	A printf-style format for the displayed value (e.g. `"%.2f"`).
`wrap`	`bool`	Whether stepping past either end wraps around to the other.
`command`	`callable`	A callback run each time an arrow is pressed.
`show`	`str`	A character to display instead of the real text (e.g. `"*"` for a password field).
`justify`	`str`	Text alignment: `"left"`, `"center"`, or `"right"`.
`font`	`str \| Font`	The font for the text.
`foreground`	`str`	The text color.
`validate`	`str`	When validation runs: `"none"`, `"focus"`, `"focusin"`, `"focusout"`, `"key"`, or `"all"`.
`validatecommand`	`callable`	The callback that validates a proposed value; returns a boolean.
`invalidcommand`	`callable`	The callback run when `validatecommand` returns false.
`state`	`str`	`"normal"`, `"readonly"`, or `"disabled"`.
`exportselection`	`bool`	Whether the selection is exported to the clipboard/X selection.
`cursor`	`str`	The mouse cursor over the field (see Cursors).
`takefocus`	`bool`	Whether the field accepts keyboard focus during traversal.
`width`	`int`	The requested width in characters.
`xscrollcommand`	`callable`	A callback connecting the field to a horizontal scrollbar.

Methods#

set(value)

Set the field’s contents to value.

Returns:: None.

get()

Return the current text.

Return type:: str

insert(index, string)

Insert string before the character at index ("end" appends).

Returns:: None.

delete(first, last=None)

Delete the characters from first through last (or a single one).

Returns:: None.

index(index)

Resolve an index expression ("insert", "end", …) to an integer.

Return type:: int

icursor(index)

Move the insert cursor to index.

Returns:: None.

selection_range(start, end)

Select the characters from start to end. Aliased as select_range; the selection_* / select_* family also has clear, present, adjust, from, and to.

Returns:: None.

xview(*args): Query or set the horizontal view; usually wired to a scrollbar. Has xview_moveto(fraction) and xview_scroll(number, what) variants.

scan_mark(x)

Record a starting point for a fast drag-scroll (paired with scan_dragto(x), which scrolls the view relative to that point).

Returns:: None.

Styling options#

This section is for changing how the spinbox looks. Define a style with style.configure(...) (and style.map(...) for per-state colors), then apply it with Spinbox(style=...).

Bootstyle mapping#

Any of the accent colors – primary, secondary, success, info, warning, danger, light, dark – substitutes for primary below. neutral does not apply to this family.

`bootstyle`	ttk style name
`primary`	`primary.TSpinbox`

Layout (elements)#

The widget is drawn from these nested parts. Each is an element you can target by name in a custom layout:

primary.Spinbox.field
  primary.Spinbox.arrowgap
  null
    primary.Spinbox.uparrow
    primary.Spinbox.downarrow
  primary.Spinbox.padding
    primary.Spinbox.textarea

Configurable style options#

Options you can set with style.configure(...) / style.map(...):

background, bordercolor, darkcolor, fieldbackground, font, foreground, lightcolor, padding, relief, shiftrelief, width

Supported states#

The states you can target with style.map(...) to vary appearance by interaction:

!disabled, disabled, focus, invalid, readonly

Hand-styling example#

import ttkbootstrap as ttk

app = ttk.App()
style = app.style

style.configure("my.TSpinbox", background="#3498db", foreground="white")
ttk.Spinbox(app, style="my.TSpinbox").pack(padx=8, pady=8)

app.mainloop()

Shared capabilities#

Spinbox also has the methods every widget inherits — configuration, placement, event binding, lifecycle, focus, and introspection — plus the ttk state methods state / instate / identify. These are documented under Capabilities.