Import Statements

The most common type of import is a module import. Clients can import QML modules which register QML object types and JavaScript resources into a given namespace.

The generic form of a module import is as follows:

import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]

• The <ModuleIdentifier> is an identifier specified in dotted URI notation, which uniquely identifies the type namespace provided by the module.

• The <Version.Number> is a version of the form MajorVersion.MinorVersion which specifies which definitions of various object types and JavaScript resources will be made available due to the import. It can be omitted, in which case the latest version of the module is imported. It is also possible to only omit the minor version. Then the latest minor version of the given major version is imported.

• The <Qualifier> is an optional local namespace identifier into which the object types and JavaScript resources provided by the module will be installed, if given. If omitted, the object types and JavaScript resources provided by the module will be installed into the global namespace.

An example of an unqualified module import is as follows:

import QtQuick

This import allows the use of all of the types provided by the QtQuick module without needing to specify a qualifier. For example, the client code to create a rectangle is as follows:

import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"
}

An example of an unqualified import with version would be

import QtQuick 2.10

In that case, any types defined in QtQuick 2.11 and higher or in any higher major version, like 6.0, would not be available to the file.

An example of a qualified module import is as follows:

import QtQuick as Quick

This import allows multiple modules which provide conflicting type names to be imported at the same time, however since each usage of a type provided by a module which was imported into a qualified namespace must be preceded by the qualifier, the conflict is able to be resolved unambiguously by the QML engine.

An example of client code which creates a rectangle after using a qualified module import is as follows:

import QtQuick as Quick

Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}

For more information about qualified imports, see the upcoming section on Importing Into A Qualified Local Namespace.

Note that if a QML document does not import a module which provides a particular QML object type, but attempts to use that object type anyway, an error will occur. For example, the following QML document does not import QtQuick and thus attempting to use the Rectangle type will fail:

Rectangle {
    width: 200
    height: 100
    color: "red"
}

In this case, the engine will emit an error and refuse to load the file.

C++ Module Imports▲

Importing into a Qualified Local Namespace▲

import QtQuick as CoreItems

CoreItems.Rectangle {
    width: 100; height: 100

    CoreItems.Text { text: "Hello, world!" }

    // WRONG! No namespace prefix - the Text type won't be found
    Text { text: "Hello, world!" }
}

import QtQuick as CoreItems
import "../textwidgets" as MyModule

CoreItems.Rectangle {
    width: 100; height: 100

    MyModule.Text { text: "Hello from my custom text item!" }
    CoreItems.Text { text: "Hello from Qt Quick!" }
}

import QtQuick as Project
import QtMultimedia as Project

Project.Rectangle {
    width: 100; height: 50

    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}

A directory which contains QML documents may also be imported directly in a QML document. This provides a simple way for QML types to be segmented into reusable groupings: directories on the filesystem.

The generic form of a directory import is as follows:

import "<DirectoryPath>" [as <Qualifier>]

Similar semantics for the <Qualifier> apply to directory imports as for module imports; for more information on the topic, please see the previous section about Importing into a Qualified Local Namespace.

For more information about directory imports, please see the in-depth documentation about directory imports.

JavaScript resources may be imported directly in a QML document. Every JavaScript resource must have an identifier by which it is accessed.

The generic form of a JavaScript resource import is as follows:

import "<JavaScriptFile>" as <Identifier>

Note that the <Identifier> must be unique within a QML document, unlike the local namespace qualifier which can be applied to module imports.

JavaScript Resources from Modules▲

module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js

import QtQuick
import projects.MyQMLProject.MyFunctions

Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}

import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs

Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}

Further Information▲