# KDDockWidgets: a drop-in replacement for Qt's QDockWidget

> KDDockWidgets is KDAB's C++ docking framework for Qt that replaces QDockWidget with native window resize, precise drop indicators, affinities, per-widget customisation and layouts that survive save and restore, under GPL 2.0 or GPL 3.0.

**KDAB/KDDockWidgets** — KDAB's Dock Widget Framework for Qt

- Repository: https://github.com/KDAB/KDDockWidgets
- Website: https://www.kdab.com/development-resources/qt-tools/kddockwidgets
- Stars: 943 · Forks: 208
- Language: C++
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/kdab-kddockwidgets

## The gap KDDockWidgets fills is what QDockWidget refuses to do

Qt ships QDockWidget, and every Qt developer has used it. KDAB's project exists because that class is convenient and limited. KDDockWidgets is a Qt dock widget library written by KDAB, suitable for replacing `QDockWidget` and implementing advanced functionalities missing in Qt.

The two claims in that sentence are both important, and the second is the unusual one. The library is not only a drop-in replacement; it is also meant to be seen as a framework for building very tailored custom docking systems. The stated goal is to expose every internal widget and every knob for the app developer to tune. That is the opposite of the encapsulation most Qt widgets offer, and it is the reason the class can be adapted to a proprietary design system rather than fought.

The audience is desktop application teams in Qt. The project description on the vendor site calls it a dock widget framework for Qt, and the repository is C++ with CMake, a `src/` tree, a `tests/` tree and an `examples/` tree. The features list also names PySide2 bindings, which opens the door to Python-driven tooling or a Python front end over the same docking system.

The entry point for everything is the manual at kdab.github.io/KDDockWidgets. The repository README states plainly that it "only provides minimal information", so the documentation site, not the README, is where the real reference lives.

## Windows resize natively, and drop indicators become precise

The first group of features concerns the parts of docking that Qt handles badly or not at all.

Native window resize on Windows is listed first, and the note in parentheses explains why it matters: it allows for Aero-snap even with custom title bar decorations. In other words, if you replace the title bar with your own artwork, a floating dock window can still snap to the screen edge the way a normal Windows window does. This is the kind of detail that decides whether a docking system feels native or bolted on.

Drop precision is the second concern. The library provides arrow drop indicators for great drop precision, and it allows for totally different, user provided, drop indicator types. That second point is a framework statement rather than a feature: the drop indicator is a widget you can replace, so an application can draw its own hover highlight, animate it, or match a custom theme.

The list of docking behaviours goes well beyond repositioning panels. You can nest dock widgets in a floating window and dock that group back to the main window, dock to any main window rather than only the parent one, and dock to the center of the main window or remove the concept of a central widget altogether. A main window can support detachable tabs in its center widget, arbitrary tabs can be detached from a tab bar into a dock area, and more than one main window is supported. There are also affinities, which make some dock widgets dockable only on certain main windows.

Together these describe a docking system that is closer to a document window manager than to QDockWidget's panel model.

## Every visual part of a dock is a widget you can replace

The customisation story is stated as a design principle: inner helper widgets are exposed so the user can customize them or provide his own. The list names the specific pieces: tab widgets, title bars, window frames and custom widget separators.

That is what makes the framework claim credible. A docking system that renders its own chrome internally is a black box for the designer of your application. Here the title bar is a widget, so you can restyle it, replace it, or hide it entirely: the features list includes allowing to hide the TitleBar and just show tabs, and dragging via the tab bar instead.

Behaviour is configurable per widget too. A dock widget can be made non-closable and/or non-dockable, which is how you lock a tool panel in place, and the title bar can carry optional minimize and maximize buttons. FloatingWindows can be utility windows or full native windows, so a floating palette does not have to be a separate top-level window type with its own quirks.

Interaction details are listed alongside: lazy separator resize, reordering tabs with mouse, a double click on the title bar to maximize, a double click on a separator to distribute space equally, and a close button on tabs.

The layouting engine honours min and max size constraints and some size policies, and partial layout save and restore is supported, affecting only a chosen sub-set. That last one matters for real applications: a user can save the arrangement of the panels they care about without the framework writing a global layout file that clobbers the rest of the window.

## Wayland, WebAssembly and EGLFS come with their own notes

The platform list is long and honest: macOS, Linux, Windows, WebAssembly, Wayland, X11/XCB and EGLFS are all listed as working. The README points at README-Wayland.md and README-WASM.md for platform specific information, and the repository also carries README-porting.md and a README-troubleshooting directory.

The reason a docking library needs per-platform notes is that docking is a window-management problem, and window management differs by display server. A floating dock window on X11 can be resized natively and positioned freely; the same widget on Wayland faces compositor rules about what a client is allowed to do with its own window. A WebAssembly build has no desktop window manager at all.

The repository reflects that attention. There are dedicated CI workflows for Qt5, Qt6, a valgrind leak check and a Qt6 asan build, and the top level carries `docker/`, `conan/`, a `CMakePresets.json` and a `CMakeUserPresets-example.json`. The presets example is the usual invitation to keep local build configuration out of the repository, which is worth copying if you integrate the library into a larger build.

For a team shipping a desktop application, the practical takeaway is that the platform matrix is real but unevenly documented, and the two README files are the first thing to read before promising Wayland or WASM support in your own release notes.

## Two hundred tests, a fuzzer, and a GUI that is actually exercised

The quality claims in the feature list are specific enough to check. The library lists great test coverage, even the GUI and DnD operations are tested, with 200 tests currently, and a fuzzer for doing random testing and finding bugs. The repository backs that up with a `tests/` directory, a valgrind suppression file, and CI workflows for leak checking and for address sanitization on Qt6.

Testing drag and drop in a GUI is the part most docking libraries skip, and it is where the bugs actually live: a panel dropped onto a drop area at the wrong moment, a tab reordered while a floating group is being dragged, a layout restored into a window that is smaller than the saved geometry. A framework that automates those interactions is telling you something about its confidence in the hard cases.

The project also states a design rule for the codebase itself: not mixing GUI with state with logic with animations. For a library whose whole value is the visual layer, keeping animation code out of the state and logic paths is what makes the layout engine testable in isolation.

There is a `layout_schema.json` at the repository root, which suggests the saved layout format has a documented schema, and a `Changelog` file for release notes. The examples directory shows the range of setups: `examples/minimal/`, `examples/dockwidgets/`, `examples/mdi/`, `examples/mdi_with_docking/`, `examples/qtquick/`, `examples/misc/` and `examples/vcpkg/`.

## GPL 2.0 or GPL 3.0, with a commercial route through KDAB

The licensing section is short. KDDockWidgets is copyright Klarälvdalens Datakonsult AB, also known as KDAB, and is licensed according to the terms of the GPL 2.0 or the GPL 3.0. The repository holds `LICENSE.txt`, `LICENSE.GPL.txt` and a `LICENSES/` directory with the GPL 2.0 and GPL 3.0 texts, and the licence field on the repository says it is a custom licence that GitHub cannot classify.

That combination means there is no permissive default. For a closed-source commercial product, the options are a commercial licence from KDAB or not using the library, and the project states the contact address for commercial licensing enquiries. The two GPL versions being offered is a convenience for compliance checklists, not a choice between a weak and a strong copyleft. This is not legal advice, and any product decision should be reviewed by whoever handles your licensing.

The project is supported and maintained by KDAB, and the maintenance record backs that up. The repository is not archived, the last push was on 2026-10-18, and the release history shows v2.5.0 on 2026-10-18, v2.4.1 on 2026-07-20 and v2.4.0 on 2025-11-01. That is a steady release train, and a commercial vendor behind it, which is a different kind of assurance from a hobby project that happens to be popular.

One adoption datapoint is worth naming, though it is a vendor claim rather than a measurement: the README links a write-up about NVIDIA implementing KDDockWidgets in the NSight Suite developer toolkit, which is built with Qt.

## Docking is not the only option, and the repository shows both

The alternative to a docking system is not another docking library, it is a different layout model, and the examples directory makes that comparison concrete. The repository ships `examples/mdi/` and `examples/mdi_with_docking/`, which is the clearest possible statement that a document-window approach and a docking approach can coexist.

A document window model treats each panel as a window with a title bar, overlapping and rearranged freely, which suits editors and viewers that behave like documents. A docking model treats panels as pieces of a layout that snap into a main window, which suits tool panels, sidebars and inspectors. The difference in approach shows up in what the framework has to solve: the document model needs z-order, cascade and window management, while the docking model needs drop areas, tab groups and layout persistence.

Within Qt itself, the honest baseline is QDockWidget, which KDDockWidgets replaces. The difference is the framework posture. QDockWidget gives you a fixed widget with a fixed chrome and limited behaviour; KDDockWidgets exposes the title bar, the tab widget, the separators and the drop indicators as replaceable widgets, which is what makes custom design systems and the native Windows resize behaviour possible.

A second axis is language binding. The library provides PySide2 bindings, so a Python team can drive the same docking system, whereas a C++-only approach needs a binding layer before Python code can use it.

## Conclusion

KDDockWidgets is worth adopting when your Qt application ships a docked layout that users rearrange, when native window behaviour on Windows matters more than the zero-cost default, or when you need to control the title bar and drop indicator markup in your own product design. It is the wrong choice for a small utility with a fixed layout, and for a closed-source product that cannot accept GPL obligations, because the licensing section offers only GPL 2.0 or GPL 3.0 unless you arrange a commercial licence with KDAB. Before starting, read the manual at kdab.github.io/KDDockWidgets for the QtQuick and platform notes, decide whether your target platforms include Wayland or WebAssembly since those have separate README files, and check the porting guide for the QDockWidget to KDDockWidgets migration path. The last push was on 2026-10-18 and v2.5.0 was released the same day.

## FAQ

### What is the difference between KDDockWidgets and QDockWidget?

KDDockWidgets is a drop-in replacement for QDockWidget that adds behaviour Qt does not provide, such as native window resize on Windows, arrow drop indicators, docking to any main window, affinities and multiple main windows. It also exposes its internal widgets, including title bars, tab widgets, window frames and separators, so they can be restyled or replaced.

### How do I get started with KDDockWidgets?

The manual at kdab.github.io/KDDockWidgets is the documentation entry point, and the README only carries minimal information. The repository ships CMakePresets.json plus a CMakeUserPresets-example.json for local build configuration, and the examples directory contains a minimal project to start from.

### Is KDDockWidgets available under a permissive licence?

The licensing section offers GPL 2.0 or GPL 3.0, and the project states that KDAB can be contacted to inquire about commercial licensing. There is no permissive default in the repository.

### Does KDDockWidgets work with Wayland and WebAssembly?

The feature list names macOS, Linux, Windows, WebAssembly, Wayland, X11/XCB and EGLFS as working, and points to README-Wayland.md and README-WASM.md for platform specific information. The repository also ships a separate README-QtQuick.md for the QtQuick side.

### Can I use KDDockWidgets from Python?

The feature list includes PySide2 bindings, and the repository contains a python/ directory along with a PySide2 example.

## Sources

- [Issues](https://github.com/KDAB/KDDockWidgets/issues)
- [KDAB/KDDockWidgets on GitHub](https://github.com/KDAB/KDDockWidgets)
- [Project website](https://www.kdab.com/development-resources/qt-tools/kddockwidgets)
- [README](https://github.com/KDAB/KDDockWidgets/blob/main/README.md)
- [Releases](https://github.com/KDAB/KDDockWidgets/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kdab-kddockwidgets