QSpinBox Widget In PyQt6

In this article, I am going to explain all about the PyQt6 QSpinBox Widget that you need to know.

A QSpinBox widget allows users to select a number value by clicking up/down arrows or using keyboard arrows to increase/decrease the value.

It is perfect when you need users to input numeric values within a specific range.

Table of Contents

QSpinBox Widget in PyQt6

In PyQt6, the QSpinBox widget provides a user-friendly way to input integer values using a graphical up-down interface. It’s useful in forms where you want users to select a number within a defined range such as age, quantity, or ratings.

If you are working on building a settings panel or product configuration screen, QSpinBox offers a clean and simple numeric input option that improves both UX and data accuracy.

Read QCheckBox Widget in PyQt6

Create QSpinBox Widget in PyQt6

Let me explain to you the different methods to create QSpinBox widget in PyQt6.

Method 1: Basic SpinBox Creation

In simple words, I can say that QSpinBox is like a digital counter where the counter can select numbers easily instead of typing them, by clicking the arrows you can adjust the value up or downwards.

Here’s a complete example:

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QSpinBox, QVBoxLayout, QLabel

class SimpleSpinBoxDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Simple SpinBox")
        self.setGeometry(100, 100, 300, 150)
        
        layout = QVBoxLayout()
        
        # Label
        label = QLabel("Select a value:")
        layout.addWidget(label)
        
        # SpinBox
        spinbox = QSpinBox()
        spinbox.setMinimum(0)
        spinbox.setMaximum(100)
        spinbox.setValue(10)
        layout.addWidget(spinbox)
        
        self.setLayout(layout)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = SimpleSpinBoxDemo()
    window.show()
    sys.exit(app.exec())

I executed the above example code and added the screenshot below.

This example creates a simple widget with a spinbox that:

Has a range from 0 to 100.
Starts with a default value of 10
Uses default step of 1

Check out QRadioButton Widget in PyQt6

Method 2: Display SpinBox Values in PyQt6

In this example, the program will respond immediately when the user changes the spinbox value, like updating a label or doing some calculation based on the selected number. Instead of just letting the user pick a number, connect the spinbox to a function that does something as the value changes.

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel, QSpinBox

class SpinBoxDynamicDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("SpinBox Dynamic Update")
        self.setGeometry(100, 100, 300, 150)
        
        layout = QVBoxLayout()

        # Create a label to show the value
        self.label = QLabel("Current value: 0")
        layout.addWidget(self.label)

        # Create the spinbox
        self.spinbox = QSpinBox()
        self.spinbox.setRange(0, 100)
        self.spinbox.setValue(0)
        
        # Connect the valueChanged signal to a function
        self.spinbox.valueChanged.connect(self.update_label)
        
        layout.addWidget(self.spinbox)
        self.setLayout(layout)

    def update_label(self, value):
        # This function updates the label every time the spinbox changes
        self.label.setText(f"Current value: {value}")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = SpinBoxDynamicDemo()
    window.show()
    sys.exit(app.exec())

I executed the above example code and added the screenshot below.

Shows a label that says: Current value: 15. Lets the user change the value using the spin box. Automatically updates the label every time the number changes.

Read How to Handle Button Click Events Using Signals and Slots in PyQt6?

Method 3: Customize Appearance and Alignment

In PyQt6, the QSpinBox widget can be easily customized to improve the look and feel of your application. You can change its font, add units like “kg” or “%”, and adjust the alignment to match your design.

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel, QSpinBox
from PyQt6.QtGui import QFont
from PyQt6.QtCore import Qt

class StyledSpinBoxDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Styled SpinBox Example")
        self.setGeometry(100, 100, 300, 150)

        layout = QVBoxLayout()

        # Create a label
        label = QLabel("Select your weight:")
        label.setFont(QFont("Arial", 12))
        label.setAlignment(Qt.AlignmentFlag.AlignCenter)
        layout.addWidget(label)

        # Create a customized spinbox
        spinbox = QSpinBox()
        spinbox.setRange(0, 200)
        spinbox.setValue(70)
        spinbox.setSuffix(" kg")  # Adds "kg" after the number
        spinbox.setFont(QFont("Verdana", 14))  # Bigger text
        spinbox.setAlignment(Qt.AlignmentFlag.AlignCenter)  # Center the number
        layout.addWidget(spinbox)

        self.setLayout(layout)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = StyledSpinBoxDemo()
    window.show()
    sys.exit(app.exec())

I executed the above example code and added the screenshot below.

This example shows how to style a QSpinBox with custom fonts, centered alignment, and a suffix for clarity. Small visual changes like these can make your GUI more user-friendly and professional.

Check out QComboBox Widget in PyQt6

Use SpinBox Inside Layouts

In PyQt6, layouts help organize widgets inside a window. When you use a QSpinBox inside layout (like QVBoxLayout or QHBoxLayout), it automatically adjusts its size and position, making your UI look clean and responsive.

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel, QSpinBox

class LayoutSpinBoxDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("SpinBox in Layout")
        self.setGeometry(100, 100, 300, 150)

        # Create a vertical layout
        layout = QVBoxLayout()

        # Add a label
        label = QLabel("Choose a number:")
        layout.addWidget(label)

        # Add the spinbox
        spinbox = QSpinBox()
        spinbox.setRange(1, 10)
        layout.addWidget(spinbox)

        # Set the layout to the window
        self.setLayout(layout)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = LayoutSpinBoxDemo()
    window.show()
    sys.exit(app.exec())

Placing a QSpinBox inside a layout makes it easier to manage spacing and alignment in your GUI. Layouts are the recommended way to arrange widgets, especially when building larger or more dynamic interfaces.

Read How to Use QVBoxLayout in PyQt6 for Vertical Layouts?

Enable or Disable QSpinBox Dynamically in PyQt6

When you want to control access to options based on a checkbox, button, or other user input, you can enable or disable a QSpinBox using logic in your PyQt6 code. You can use this when you want a user to interact with a widget under certain conditions.

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel, QSpinBox, QCheckBox

class EnableSpinBoxDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Enable/Disable SpinBox")
        self.setGeometry(100, 100, 300, 150)

        layout = QVBoxLayout()

        # Checkbox to control the spinbox
        self.checkbox = QCheckBox("Enable SpinBox")
        self.checkbox.stateChanged.connect(self.toggle_spinbox)
        layout.addWidget(self.checkbox)

        # Spinbox (disabled by default)
        self.spinbox = QSpinBox()
        self.spinbox.setRange(1, 10)
        self.spinbox.setEnabled(False)  # Start disabled
        layout.addWidget(self.spinbox)

        self.setLayout(layout)

    def toggle_spinbox(self, state):
        self.spinbox.setEnabled(state == 2)  # 2 means checked

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = EnableSpinBoxDemo()
    window.show()
    sys.exit(app.exec())

This example shows how to control when a QSpinBox is active by linking it to a checkbox. Disabling and enabling widgets based on conditions helps you create smarter, more user-friendly interfaces that guide user input effectively.

Check out How to Create QPushButton Widget in PyQt6?

Best Practices for Using SpinBoxes in PyQt6

I have listed some best practices to follow to make the most of it and provide a clean, user-friendly experience.

1. Set Reasonable Ranges

Always define a minimum and maximum value using .setRange(min, max).
Prevents users from entering values that are not meaningful to your application.

2. Provide a Default Value

Set a sensible starting value with .setValue() to avoid confusion.
Helps guide the user toward the expected input.

3. Align SpinBox in Layouts

Use layout managers to keep your UI aligned and accessible.
Avoid hardcoding positions.

4. Style the Widget for Better UX

Use stylesheets to make the spin box match your application’s theme.
Improves visual consistency.

In this tutorial, I explained all about the QSpinBox Widget in PyQt6. Some important methods to create the QSpinBox Widget in PyQt6 are basic creation, displaying SpinBox values in PyQt6, and customizing appearance and alignment. I also discussed how to use SpinBox inside layouts, and enabling or disabling QSpinBox dynamically in PyQt6.