list QML Basic Type

a list of QML objects.

The list type refers to a list of QML objects.

A list value can be accessed in a similar way to a JavaScript array:

  • Values are assigned using the [] square bracket syntax with comma-separated values
  • The length property provides the number of items in the list
  • Values in the list are accessed using the [index] syntax

Values can be dynamically added to the list by using the push method, as if it were a JavaScript Array

A list can only store QML objects, and cannot contain any basic type values. (To store basic types within a list, use the var type instead.)

When integrating with C++, note that any QQmlListProperty value passed into QML from C++ is automatically converted into a list value, and vice-versa.

Using the list Type

For example, the Item type has a states list-type property that can be assigned to and used as follows:

import QtQuick 2.0

Item {
    width: 100; height: 100

    states: [
        State { name: "activated" },
        State { name: "deactivated" }

    Component.onCompleted: {
        console.log("Name of first state:", states[0].name)
        for (var i = 0; i < states.length; i++)
            console.log("state", i, states[i].name)

The defined State objects will be added to the states list in the order in which they are defined.

If the list only contains one object, the square brackets may be omitted:

import QtQuick 2.0

Item {
    width: 100; height: 100
    states: State { name: "activated" }

Note that objects cannot be individually added to or removed from the list once created; to modify the contents of a list, it must be reassigned to a new list.

Note: The list type is not recommended as a type for custom properties. The var type should be used instead for this purpose as lists stored by the var type can be manipulated with greater flexibility from within QML.

This basic type is provided by the QML language.

See also QML Basic Types.

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
create apps
create games
cross platform
native performance
3rd party services
game network
level editor
easiest to learn
biggest time saving
best support