English | 简体中文

Fluent-Qt

A cross-platform Fluent-style C++ UI component library for Qt Widgets.

Try the live C++ Web Gallery · Project website · Questions & community · Support the project

Fluent-Qt (FluentQt) is a cross-platform, Fluent-style C++ UI component library built on Qt Widgets. It provides native controls for input, navigation, collections, data grids, charts, overlays, and windows. Written in C++17, it integrates into existing Qt projects through CMake and offers optional PySide6 bindings.

The library supports Windows, macOS, Linux, and WebAssembly. It includes Light, Dark, and High Contrast themes, with options to reduce or disable motion. The optional Spatial plugin adds 3D presentation to Widgets interfaces. QmlBridge provides QML support, loading QML pages that share application data and Fluent theme settings with Widgets.

🧩 Library modules

Core

FluentQt::FluentQt provides native controls, themes, design tokens, and shared widget foundations. Ordinary 2D applications only need this target.

Plugins

The optional Plugins module handles registration, dependencies, activation, and cleanup. C++ applications link FluentQt::Plugins; each plugin has its own target for any extra dependencies.

C++ applications call the library directly. Python uses matching PySide6 bindings, and WebAssembly builds compile the same C++ code to run in the browser.

Particles

The Particles plugin provides ParticleBackdrop, an animated particle background. It draws on the CPU and does not need Spatial or OpenGL. ParticlesSession pauses and resumes the backgrounds it manages.

Build with FLUENT_QT_BUILD_PARTICLES=ON and link FluentQt::Particles. The core library FluentQt::FluentQt does not include particle effects.

Open Plugins → Particles in Gallery to see the examples.

Spatial

The Spatial plugin adds 3D presentation to existing Qt Widgets interfaces. SpatialSession activates the plugin, creates views, and cleans up when the plugin stops.

Linking FluentQt::Spatial also links FluentQt::Plugins and adds OpenGL dependencies. Spatial supports a native 2D fallback when 3D is unavailable.

Open Plugins → Spatial in Gallery to see SpatialView and SpatialItem examples. Turn on 3D in Settings → 3D Gallery.

QmlBridge

QmlBridge is FluentQt's QML compatibility plugin. It loads QML pages in Widgets interfaces and shares application data and Fluent theme settings with the page.

Enable FLUENT_QT_BUILD_QML_BRIDGE=ON and link FluentQt::QmlBridge. This optional module adds the Qt Qml, Quick, and QuickWidgets dependencies.

Try Plugins → QmlBridge → QmlView in Gallery, or build the minimal example. Setup details are in the integration guide.

🖼 Gallery

Use Gallery to browse controls, try interactions, and read example code.

Try it on	Entry point
Browser	Live Gallery · Project website
Windows, macOS, Linux	Download a Gallery package

Python compatibility Gallery

The Python Gallery is available from PyPI.

python -m pip install FluentQt-Gallery
python -m fluentqt_gallery

FluentQt-Gallery installs the matching FluentQt version automatically.

🤖 Build with AI

Use build-fluentqt-gui in Codex, Claude Code, or Cursor to build a desktop app, add a GUI to a project, or fix an interface. Example · Install and use

When tuning a Gallery sample, use Live Scene to see each saved change, then check the result in the compiled C++ sample. How it works

🚀 Quick Start

The C++ integration requires C++17, CMake 3.16+, and Qt Widgets 5.15+ or 6.2+. Use FetchContent for new projects.

C++ setup

FetchContent integration

cmake_minimum_required(VERSION 3.16)
project(my_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)
FetchContent_Declare(
    fluentqt
    GIT_REPOSITORY https://github.com/calvinhxx/Fluent-Qt.git
    GIT_TAG v1.11.3
    GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(fluentqt)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE FluentQt::FluentQt)

Source integration

After defining your application target, add the Fluent-Qt source directory and link the exported target:

add_subdirectory(Fluent-Qt)
target_link_libraries(my_app PRIVATE FluentQt::FluentQt)

Installed library integration

Use a FluentQt installation that includes the development headers and CMake package files. See the library build and installation guide.

find_package(FluentQt CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE FluentQt::FluentQt)

If FluentQt is outside the system search path, configure with -DCMAKE_PREFIX_PATH=/path/to/fluentqt.

C++ minimal example

main.cpp:

#include <FluentQt/FluentQt.h>

#include <QApplication>
#include <QVBoxLayout>
#include <QWidget>

int main(int argc, char* argv[])
{
    fluent::prepareHighDpiApplication();
    QApplication app(argc, argv);
    fluent::initializeResources();
    app.setFont(Typography::fontStyle(Typography::FontRole::Body).toQFont());

    fluent::windowing::Window window;
    window.setWindowTitle(QStringLiteral("FluentQt Hello World"));
    window.resize(480, 320);

    auto* content = new QWidget;
    auto* layout = new QVBoxLayout(content);
    layout->setContentsMargins(32, 32, 32, 32);

    auto* button = new fluent::basicinput::Button(
        QStringLiteral("Hello from FluentQt"), content);
    button->setFluentStyle(fluent::basicinput::Button::Accent);
    layout->addStretch();
    layout->addWidget(button, 0, Qt::AlignCenter);
    layout->addStretch();

    window.setContentWidget(content);
    window.show();
    return app.exec();
}

See examples/hello_world for the complete project, or run the fluentqt_hello_world target directly from an IDE.

Optional Python compatibility

The PySide6 compatibility layer exposes Fluent-Qt's native C++ widgets to Python through Shiboken6.

python -m pip install FluentQt

See the Python guide for installation, examples, compatibility, and source builds.

🛠 Build

Dependencies

Scope	Dependencies
FluentQt C++ library	C++17, CMake 3.16+, Qt Widgets 5.15+ or 6.2+
C++ Gallery	FluentQt, Qt Network, spdlog/fmt
C++ WebAssembly	Qt 6.9.3 wasm_singlethread, Emscripten 3.1.70
Tests	FluentQt, Qt Test/Network, GTest, spdlog/fmt
Optional PySide6 bindings	Qt/PySide6/Shiboken6 6.2.4+; Python 3.10+ for source builds

Library

cmake -S . -B build/fluentqt \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH=/path/to/Qt
python3 tools/dev/fluent_qt_build.py build/fluentqt --config Release --target FluentQt
cmake --install build/fluentqt --config Release \
  --component Development --prefix /path/to/install

The build script selects parallelism from available CPU and memory. See the build workflow for configuration.

Optional extensions

Enable the Plugins infrastructure or a plugin module when configuring FluentQt, then link the corresponding target in your application.

Extension scope	Build option	CMake target	Integration example
Plugins infrastructure	-DFLUENT_QT_BUILD_PLUGINS=ON	FluentQt::Plugins	Minimal plugin example
Plugins → Particles	-DFLUENT_QT_BUILD_PARTICLES=ON	FluentQt::Particles	Particles integration
Plugins → Spatial	-DFLUENT_QT_BUILD_SPATIAL=ON	FluentQt::Spatial (automatically includes Plugins)	Spatial Hello World
Plugins → QmlBridge	-DFLUENT_QT_BUILD_QML_BRIDGE=ON	FluentQt::QmlBridge (automatically includes Plugins)	QML host example

For source integration, set the option before add_subdirectory() or FetchContent_MakeAvailable(). See each module's guide for installed-package integration. Matched Python builds expose enabled modules through fluentqt.plugins, fluentqt.spatial, and fluentqt.qmlbridge. WebAssembly uses the shared C++ implementation.

Build Gallery locally

Repository presets require CMake 3.25+ and VCPKG_ROOT. Configure your Qt kit using the first-use setup.

List the presets available on the current host:

cmake --list-presets

On Apple Silicon, use vcpkg-osx:

cmake --preset vcpkg-osx
python3 tools/dev/fluent_qt_build.py \
  --preset vcpkg-osx \
  --target fluent_qt_gallery

Use the matching preset on other platforms:

Platform	Preset
Apple Silicon Mac	vcpkg-osx
Intel Mac or Rosetta	vcpkg-osx-x64
Linux x64	vcpkg-linux
Linux ARM64	vcpkg-linux-arm64
Windows x64	vcpkg-windows
Windows ARM64	vcpkg-windows-arm64

For packaging, use the matching -release preset and the verification steps in the packaging workflow.

WebAssembly

See the WebAssembly workflow for the browser toolchain, local builds, validation, and Pages deployment.

Source package

Create the reduced library source package for offline or source integration:

python3 tools/dev/fluent_qt_build.py build/fluentqt --target fluent_qt_source_package

📚 Documentation

Start with the documentation map, or choose a path:

Goal	Entry point
Evaluate controls	Component documentation · WebAssembly Gallery
Build an application	AI-assisted development · Onboarding tools
Contribute to FluentQt	Development tree · Architecture · Fluent design
Package or release	Packaging · Release governance · Release notes
Get help or report a problem	Community · Support · Security

See Contributing and the Code of Conduct before opening a change.

🔗 References

Entry	Purpose
Windows UI Kit (Community)	Fluent / Windows visual reference
WinUI Gallery	Component behavior and sample page reference

License

Fluent-Qt's own source code is released under the MIT License. Bundled assets and packaged runtime dependencies retain their upstream terms; versions, provenance, source-availability rules, and license locations are listed in THIRD_PARTY_NOTICES.md. Product names, logos, and external design references are addressed in TRADEMARKS.md.