A QGroupBox draws a frame with a title around a set of widgets. It does not change any behaviour, it just makes a form easier to read once it has more than a few inputs.

A groupbox visualization in PyQt5 Python

What is a GroupBox in PyQt5?

At its core, a GroupBox serves as a container for other widgets. Think of it as a frame where you can place buttons, texts, images, and other UI elements. This is especially useful in complex applications where you need to present multiple options or categories to the user.

The hierarchy works as follows:

  1. A main window in PyQt5 can contain a layout such as a grid.
  2. Within this grid layout, one can add multiple group boxes.
  3. Inside these group boxes, you can place the desired widgets.

For the grid structure, the class QGridLayout is used. As with other layouts, it’s essential to add this to your main application window. On the other hand, QGroupBox is the class responsible for creating a groupbox.

Step-by-Step GroupBox Implementation

The following code provides a concise example of implementing a 2x2 grid of group boxes within a window. Each groupbox contains radio buttons with different food items. Check it out:

# Source: https://pythonprogramminglanguage.com/pyqt5-groupbox/
import sys
from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import (QApplication, QCheckBox, QGridLayout, QGroupBox,
        QMenu, QPushButton, QRadioButton, QVBoxLayout, QWidget)

class Window(QWidget):
    def __init__(self, parent=None):
        super(Window, self).__init__(parent)

        grid = QGridLayout()
        grid.addWidget(self.createExampleGroup(), 0, 0)
        grid.addWidget(self.createExampleGroup(), 1, 0)
        grid.addWidget(self.createExampleGroup(), 0, 1)
        grid.addWidget(self.createExampleGroup(), 1, 1)
        self.setLayout(grid)

        self.setWindowTitle("PyQt5 Group Box Example")
        self.resize(400, 300)

    def createExampleGroup(self):
        groupBox = QGroupBox("Select Your Favorite Food")

        radio1 = QRadioButton("&Pizza")
        radio2 = QRadioButton("&Taco")
        radio3 = QRadioButton("&Burrito")

        radio1.setChecked(True)

        vbox = QVBoxLayout()
        vbox.addWidget(radio1)
        vbox.addWidget(radio2)
        vbox.addWidget(radio3)
        vbox.addStretch(1)
        groupBox.setLayout(vbox)

        return groupBox

if __name__ == '__main__':
    app = QApplication(sys.argv)
    windowInstance = Window()
    windowInstance.show()
    sys.exit(app.exec_())

to make the most out of PyQt5 in your projects.

How to use one

  • Create it with groupbox = QtWidgets.QGroupBox('Settings'). The string is the title.
  • Put the widgets in a layout inside the groupbox.
  • Add that layout to the groupbox with groupbox.setLayout(layout).
  • Add the groupbox itself to the window layout.
  • setFlat(True) drops the border, setTitle('...') changes the text.
  • setCheckable(True) adds a tick box that greys out everything inside.
  • setEnabled(False) disables the whole group at once.

Nesting groupboxes works too. One for the general settings and one inside it for the advanced ones.

The fastest way to learn this is to write it yourself. The PyChallenge exercises run in your browser, no install needed.