Skip to content

NumericEntry

Bases: Field

A numeric entry field widget with increment/decrement spin buttons.

Extends Field to provide numeric input with spin buttons, bounds validation, keyboard stepping (Up/Down arrows), mouse wheel support, and optional wrapping.

Events

  • <<Increment>>: Fired when increment is requested (before step occurs).
  • <<Decrement>>: Fired when decrement is requested (before step occurs).
  • <<Change>>: Fired when value changes after commit.
  • <<Input>>: Fired on each keystroke.
  • <<Valid>>: Fired when validation passes.
  • <<Invalid>>: Fired when validation fails.

Attributes:

Name Type Description
entry_widget NumberEntryPart

The underlying entry widget.
label_widget Label

The label widget.
message_widget Label

The message label widget.
addons dict[str, Widget]

Dictionary of inserted addon widgets by name.
variable Variable

Tkinter Variable linked to entry text.
signal Signal

Signal object for reactive updates.

increment_widget property 

increment_widget

Get the increment spin button widget.

decrement_widget property 

decrement_widget

Get the decrement spin button widget.

__init__ 

__init__(
    master: Master = None,
    value: int | float = 0,
    label: str = None,
    message: str = None,
    show_spin_buttons: bool = True,
    minvalue: int | float | None = None,
    maxvalue: int | float | None = None,
    increment: int | float = 1,
    **kwargs: Unpack[FieldOptions],
)

Initialize a NumericEntry widget.

Creates a numeric entry field with optional label, validation, bounds constraints, and increment/decrement spin buttons. The widget supports keyboard stepping (Up/Down arrows), mouse wheel interaction, and optional value wrapping at boundaries.

Parameters:

Name Type Description Default
master Master

Parent widget. If None, uses the default root window.

 None
value int | float

Initial numeric value to display.

 0
label str

Optional label text to display above the entry field. If required=True, an asterisk (*) is automatically appended.

 None
message str

Optional message text to display below the entry field. Used for hints or help text. Replaced by validation errors when validation fails.

 None
show_spin_buttons bool

If True, displays increment/decrement buttons (plus and minus icons) to the right of the entry.

 True
minvalue int | float

Minimum allowed value (inclusive). Values below this will be clamped or wrapped depending on the wrap setting.

 None
maxvalue int | float

Maximum allowed value (inclusive). Values above this will be clamped or wrapped depending on the wrap setting.

 None
increment int | float

Step size for increment/decrement operations.

 1

Other Parameters:

Name Type Description
wrap bool

If True, values wrap around at min/max boundaries.
value_format str

Number format specification for IntlFormatter. Examples: 'decimal', 'percent', 'currency', '#,##0.00'.
locale str

Locale identifier for number formatting (e.g., 'en_US').
required bool

If True, field cannot be empty.
accent str

Accent token for the focus ring and active border.
bootstyle str

DEPRECATED - Use accent instead.
allow_blank bool

If True, empty input is allowed (sets value to None).
cursor str

Cursor style when hovering.
exportselection bool

Export selection to clipboard.
font str

Font for text display.
foreground str

Text color.
initial_focus bool

If True, widget receives focus on creation.
justify str

Text alignment ('left', 'center', 'right').
show_message bool

If True, displays message area.
padding int | tuple

Padding around entry widget.
takefocus bool

If True, widget accepts Tab focus.
textvariable Variable

Tkinter Variable to link with text.
textsignal Signal

Signal object for reactive updates.
width int

Width in characters.
xscrollcommand Callable

Callback for horizontal scrolling.

increment 

increment()

Increment the numeric value by one step.

decrement 

decrement()

Decrement the numeric value by one step.