- Qt 6.5
- Qt QML
- QML Types
- list
- Qt 6.5.1 Reference Documentation

# list QML Value Type

a list of QML objects. More...

## Detailed Description

The `list` type refers to a list of QML objects or values.

Properties of type `list` are empty by default.

A `list` can store QML objects or value type values.

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

Similarly any `QList<T>` of a registered value type `T` 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

     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

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

You can also declare your own list properties in QML:

     import QtQml

     QtObject {
         property list<int> intList: [1, 2, 3, 4]
         property list<QtObject> objectList
     }

Lists can be used much like JavaScript arrays. For example:

- 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
- You can use `push()` to append entries
- You can set the `length` property of the list to truncate or extend it.

However, you can not automatically extend the list by assigning to an index currently out of range. Furthermore, if you insert `null` values into a list of objects, those are converted to `nullptr` entries in the underlying QQmlListProperty.

A list of value types is different from a JavaScript array in one further important aspect: Growing it by setting its length does not produce undefined entries, but rather default-constructed instances of the value type.

Similarly, growing a list of object types this way produces null entries, rather than undefined entries.

This value type is provided by the QML language.

See also QML Value Types.