Exposing State from C++ to QML

It is often desirable to expose some properties from C++ to all QML elements in a particular component, all QML elements in a module, or even all QML elements overall. You can do this by introducing singletons or by adding properties to the root objects of select components.

Using Singletons

If you want to expose a number of global properties to all elements in a module or all elements overall, you can define a singleton in C++. To do this, add the QML_ELEMENT or QML_NAMED_ELEMENT macros and the QML_SINGLETON macro to a class containing the properties you want to expose as Q_PROPERTY declarations:

// Singleton.h
class Singleton : public QObject
    Q_PROPERTY(int thing READ thing WRITE setThing NOTIFY thingChanged FINAL)

    Singleton(QObject *parent = nullptr) : QObject(parent) {}

    int thing() const { return m_value; }
    void setThing(int v)
        if (v != m_value) {
            m_value = v;
            emit thingChanged();

    void thingChanged();

    int m_value = 12;

Now you can access the thing property of the singleton from any QML code that imports this module:

import QtQml

QtObject {
    objectName: "The thing is " + Singleton.thing

If you have placed your QML files in the same directory as the module (which is highly recommended), the singleton is available from the implicit import within your module. You don't need to import anything explicitly. If not, or if you want to access the thing property from other modules, you do need to import the module the singleton belongs to.

In order to set the value of the property from C++, you may need to retrieve the singleton instance. For this purpose you may use QQmlEngine::singletonInstance. The preferred way to do this is by giving a module and type name as parameters:

    Singleton *singleton
            = engine->singletonInstance<Singleton *>("MyModule", "Singleton");

Using Object Properties

If you want to expose some properties to only the QML elements in a specific component, you can add them as regular properties to the root object of the component. In order to make sure they are actually set in all cases, you can make them Required Properties. You might write your QML component as follows:

pragma ComponentBehavior: Bound

import QtQuick

Window {
    id: root
    visible: true

    required property int thing

    Text {
        anchors.fill: parent
        text: "The thing is " + root.thing

    component Inner: QtObject {
        objectName: "I can see " + root.thing + " because I'm bound."

We use an ID for the root element of the component and reference the property by ID and name from any inner objects. In order to safely make the ID of the root element available to any nested components, we use ComponentBehavior.

Then, in C++, when you create an object from such a component, you need to make sure to call the QQmlComponent::createWithInitialProperties, QQmlApplicationEngine::setInitialProperties, or QQuickView::setInitialProperties in order to initialize the properties. For example:

    QQmlEngine engine;

    QQmlComponent component(&engine, "MyModule", "RequiredProperties");
    QScopedPointer<QObject> o(component.createWithInitialProperties({
            {"thing", 11}

This is assuming your module URI is MyModule and the module is available in the QML import path.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.