Using QML modules with plugins | Qt Creator Documentation
Description: Use C++ plugins to expose custom components to Qt Quick applications.

- Qt Creator Documentation
- Using QML modules with plugins
- Qt Creator 19.0.0

UI files ◦ SDK Tool

# Using QML modules with plugins

QML modules may use C++ plugins to expose components defined in C++ to Qt Quick applications.

To create a QML module:

1. Create custom components and place all the `.qml` files in a directory dedicated to your module. For example, `imports\asset_imports`.
2. For Qt Quick UI Prototype projects (`.qmlproject`), specify the path to the directory that has the module in the `.qmlproject` file of the application where you want to use the module as a value of the `importPaths` variable. For example, `importPaths: [ "imports", "asset_imports" ]`.
3. Create a `qmldir` file for your module and place it in the module directory. For more information, see Module Definition qmldir Files.
4. Create a directory named `designer` in your module directory.
5. Create a `.metainfo` file for your module and place it in the `designer` directory. Use a metainfo file delivered with Qt, such as `qtquickcontrols2.metainfo`, as an example.
6. Import the module into the project, as instructed in Importing QML modules.

Note: If Qt Creator cannot find the new QML module, build the project and then go to Tools > QML/JS > Reset Code Model to reset the code model.

## Developing with Qt 6.1 or earlier

Since Qt 6.2, CMake generates the `qmltypes` and `qmldir` files automatically.

## Generating type description files

When registering QML types, make sure that the QML module has a `plugins.qmltypes` file. Ideally, it should be located in the same directory as the `qmldir` file. The `qmltypes` file has a description of the components exported by the module's plugins and is loaded by Qt Creator when the module is imported.

For more information, see Type Description Files.

### Dumping plugins automatically

If a module with plugins lacks the `qmltypes` file, Qt Creator tries to generate a temporary file itself by running the `qmldump` program in the background. However, this automatic dumping is a fallback mechanism with many points of failure and you cannot rely upon it.

## Importing QML modules

By default, Qt Creator will look in the QML import path of Qt for QML modules.

If you use qmake and your application adds additional import paths that Qt Creator should use, specify them using `QML_IMPORT_PATH` in the `.pro` file of your application: `QML_IMPORT_PATH += path/to/module`.

If you use CMake, add the following command to the `CMakeLists.txt` file to set the QML import path:

     set(QML_IMPORT_PATH ${CMAKE_SOURCE_DIR}/qml ${CMAKE_BINARY_DIR}/imports CACHE STRING "" FORCE)

The import path affects all the targets built by the CMake project.

## Running QML modules in Design mode

The QML Puppet is used in the Design mode to render and preview images and to collect data. To be able to render custom components correctly from QML modules, the QML Puppet must be built with the same Qt version and compiler as the QML modules.

A plugin should behave differently depending on whether it is run by the QML Puppet or an application. For example, animations should not be run in the Design mode. You can use the value of the `QML_PUPPET_MODE` environment variable to check whether the plugin is currently being run by an application or edited in the Design mode.

See also Resetting the code model.

UI files ◦ SDK Tool