ToggleButton (Qt animated toggle switch with dark/light adaptive colors)

English | 中文

A lightweight Qt widget that provides a modern animated toggle switch. It supports smooth knob/background animations, optional ON/OFF text, and automatically adapts to dark/light color schemes via the application palette and style hints. This component is based on the AntDesign library, specifically the AntToggleButton implementation. Special thanks to byralpha for the beautiful design.

Features

• 🎞️ Smooth animations for knob position and background color (QPropertyAnimation, QParallelAnimationGroup)
• 🌓 Dark/Light adaptive colors (auto picks QPalette::Accent and reacts to color scheme changes)
• 🏷️ Optional embedded ON/OFF text display
• 🖱️ Click to toggle with debounced animation state
• 📏 Sensible default size (52x26), auto-resizes knob to fit
• 🔔 Simple signal: toggled(bool)
• 🧩 Pure Qt Widgets, no extra dependencies

Requirements

• Qt 6.5+ (Widgets)
• C++17 or newer (recommended by modern Qt templates)
• Platforms: Windows, macOS, Linux

Note: The widget uses QStyleHints::colorScheme and colorSchemeChanged, which are available in Qt 6. For Qt 5 compatibility, minor code changes would be required.

Integration

1. Copy togglebutton.h and togglebutton.cpp into your Qt project
2. Include the header where needed:

   #include "togglebutton.h"

3. Add the files to your build system

qmake (.pro)

QT += widgets

SOURCES += \
    togglebutton.cpp

HEADERS += \
    togglebutton.h

CMake (Qt 6)

find_package(Qt6 REQUIRED COMPONENTS Widgets)

# add to an existing target
target_sources(your_target PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/togglebutton.cpp
)

target_include_directories(your_target PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}
)

target_link_libraries(your_target PRIVATE Qt6::Widgets)

Usage Examples

Basic

#include <QApplication>
#include <QVBoxLayout>
#include <QLabel>
#include "togglebutton.h"

class DemoWidget : public QWidget {
    Q_OBJECT
public:
    DemoWidget() {
        auto *layout = new QVBoxLayout(this);
        auto *label = new QLabel("State: OFF", this);
        auto *toggle = new ToggleButton(this);

        connect(toggle, &ToggleButton::toggled, this, [label](bool on) {
            label->setText(QString("State: %1").arg(on ? "ON" : "OFF"));
        });

        layout->addWidget(label);
        layout->addWidget(toggle);
        setLayout(layout);
    }
};

Control ON/OFF text visibility

ToggleButton *toggle = new ToggleButton(parent);
toggle->setShowText(false); // hide embedded ON/OFF text if you prefer a cleaner look

Programmatically set state

toggle->setChecked(true);    // turn ON
bool on = toggle->isChecked();

API Overview

Constructors

• ToggleButton(QWidget *parent = nullptr)

State

• void setChecked(bool checked) / bool isChecked() const

Appearance

• void setShowText(bool show)

Signals

• void toggled(bool checked)

Animated/Internal Properties (via Q_PROPERTY)

• int m_circleX (knob x position)
• int m_circleWidth (knob width, auto-derived from height)
• QColor m_bgColor (background color for the track)

These are primarily for the internal animation system and not typically manipulated directly by user code.

Notes

• The widget adapts its colors to the current color scheme. When toggled ON, the background uses QPalette::Accent from the application palette.
• If you resize the widget, the knob width and positions are recalculated to fit the new size smoothly.
• The animations are debounced: a click during an ongoing animation is ignored until the animation completes.
• The default fixed size is set to 52x26 on construction; you can call setFixedSize() or place it in layouts to adjust if needed.

Roadmap / Ideas

• Public customization hooks for colors and durations
• Optional text localization and custom strings
• Accessible properties (focus, keyboard toggle)

Contributing

Issues and pull requests are welcome. Please include:

• Clear description of the issue or enhancement
• Reproduction steps (if applicable)
• Platform and Qt version information
• Code examples when relevant