- Qt 6.12
- Qt Qml
- The QML Reference
- QML Modules
- Qt 6.12.0 Reference Documentation

Embedding C++ Objects into QML with Context Properties ◦ Defining Object Types through QML Documents

# QML Modules

A QML module provides versioned types and JavaScript resources in a type namespace which may be used by clients who import the module. The types which a module provides may be defined in C++ within a plugin, or in QML documents. Modules make use of the QML versioning system which allows modules to be independently updated.

Defining of a QML module allows:

- The sharing of common QML types within a project - for example, a group of UI components that are used by different windows
- The distribution of QML-based libraries
- The modularization of distinct features, so that applications only load the libraries necessary for their individual needs
- Versioning of types and resources so that the module can be updated safely without breaking client code

## Modern QML Modules

QML Modules are best defined using the CMake API, in particular qt_add_qml_module. The following sections describe all aspects of creating a modern QML module.

### Defining Object Types through QML Documents

QML types can be defined directly in QML documents, which is the simplest way to create reusable components. Each QML file that starts with a capital letter automatically defines a type that can be used by other QML files in the same module.

### Defining QML Types from C++

For better performance or access to low-level APIs, types can be defined in C++ and exposed to QML. C++ types provide full control over properties, methods, and signals while benefiting from static typing and compilation.

### Tying it All Together with CMake

The `qt_add_qml_module` CMake command brings together QML files, C++ types, and resources into a cohesive module. It handles type registration, resource compilation, and QML tooling integration automatically, making it the recommended approach for modern QML module development.

### Modernizing QML Modules

This guide helps migrate older CMake-based QML modules to newer versions of Qt. It covers how to adapt to newer CMake policies and avoid outdated techniques.

### Fine Tuning QML Modules

Advanced module configuration options in Writing QML Modules allow fine-grained control over module behavior. This includes adding multiple QML modules to the same binary, versioning, custom directory layouts, and advanced topics on QML plugins.

## Old QML Modules

Note: Use the CMake API to define a QML Module. Define your QML module manually only if you need to use `qmake`.

A module is defined by a module definition qmldir file. Each module has an associated type namespace, which is the module's identifier. A module can provide QML object types (defined either by QML documents or via a C++ plugin) and JavaScript resources, and may be imported by clients.

To define a module, a developer should gather together the various QML documents, JavaScript resources and C++ plugins which belong in the module into a single directory, and write an appropriate module definition qmldir file which should also be placed into the directory. The directory can then be installed into the QML import path as a module.

Note that defining a module is not the only way to share common QML types within a project - a simple QML document directory import may also be used for this purpose.

### Supported QML Module Types

There are two different types of modules supported by QML:

- Identified Modules
- Legacy Modules (deprecated)

Identified modules explicitly define their identifier and are installed into QML import path. Identified modules are more maintainable (due to type versioning) and are provided with type registration guarantees by the QML engine which are not provided to legacy modules. Legacy modules are only supported to allow legacy code to continue to work with the latest version of QML, and should be avoided by clients if possible.

Clients may import a QML module from within QML documents or JavaScript files. Please see the documentation about importing a QML module for more information on the topic.

### Providing Types and Functionality in a C++ Plugin

An application which has a lot of logic implemented in C++, or which defines types in C++ and exposes them to QML, may wish to implement a QML plugin. A QML extension module developer may wish to implement some types in a C++ plugin (as opposed to defining them via QML documents) to achieve better performance or for greater flexibility.

Every C++ plugin for QML has an initialization function which is called by the QML engine when it loads the plugin. This initialization function must register any types that the plugin provides, but must not do anything else (for example, instantiating QObjects is not allowed).

See Creating C++ Plugins For QML for more information.

See also Modernizing QML Modules and Port QML modules to CMake.

Embedding C++ Objects into QML with Context Properties ◦ Defining Object Types through QML Documents