QML Basic Type: list

A list type contains a list of objects. While not technically a basic type, QML supports lists of object types. When used from QML, the engine automatically appends each value to the list. Items in the list can be accessed by index using the usual listName[index] syntax.

For example, the Item class contains a list property named children that can be used like this:

 Item {
     children: [
         Item { id: child1 },
         Rectangle { id: child2; width: 200 },
         Text { id: child3 }
     ]

     Component.onCompleted: {
         console.log("Width of child rectangle:", children[1].width)
     }
 }

child1, child2 and child3 will be added to the children list in the order in which they appear.

List properties can be created as a variant type, or as a list<Type> type, where Type is the type of the object in the list:

 Item {
     property variant values: [ 10, 20, 'abc', 'xyz' ]

     property list<Rectangle> rects: [
         Rectangle { width: 100; height: 100},
         Rectangle { width: 200; height: 200}
     ]
 }

A variant list can contain values of any of the basic QML types such as numbers, strings, etc. while a list<Type> list can only contain values that match (or are derived from) the specified Type.

A list property can be cleared by setting it to an empty list:

 Item {
     children: []
 }

A list property cannot be modified in any other way. Items cannot be dynamically added to or removed from the list through JavaScript operations; any push() operations on the list only modify a copy of the list and not the actual list. (These current limitations are due to restrictions on Property Binding where lists are involved.)

You can, however, modify a copy of the list and then reassign the property to the modified value. Other options are to create an array object from within a .js JavaScript file, or implement a custom list element in C++. Here is a QML element that modifies the list in a JavaScript file:

 // QML
 import "script.js" as Script

 Item {
     Component.onCompleted: {
         Script.addItem('abc')
         console.log("Added:", Script.getList()[0])
     }
 }

 // script.js
 var myArray = new Array()

 function getList() {
     return myArray
 }

 function addItem(item) {
     myArray.push(item)
 }

However, note that a JavaScript list should not be used as a QML property value, as the property is not updated when the list changes.