List views

A ListView is a scrollable control used to display a list of items.

Screens showing a ListView with a default appearance and a ListView with a customized appearance.

The content of a list is defined using data models. A data model provides the information to display in a list. This data is typically ordered hierarchically and uses index paths to uniquely identify each item in the model.

The appearance of a ListView depends on the contents of the list, the use of headers, and the device being used.

You can use the Header and StandardListItem classes to get your list up and running quickly. These classes provide a basic template for the appearance of list items.

You can also create your own styles for list items by using custom ListItemComponent objects. For more information on the different appearances you can use, see Creating a list view in QML.


Responding to list item selection

When a user taps an item in a ListView, the ListView emits the triggered() signal that you can use to affect the behavior of your app.

In QML, you can use the onTriggered signal handler to capture the triggered() signal. The following example shows how to capture the triggered() signal and update text in a label with information from a list.

ListView {
    // Set the data model for the list
    dataModel: XmlDataModel {
        source: "items.xml"
    listItemComponents: [
        ListItemComponent {
            type: "header"
            // Use the Header class to apply
            // default styling to header items. The
            // header items are specified in the data model
            // using the title label
            Header {
                title: ListItemData.title
        ListItemComponent {
            type: "listItem"
            // Create the list items as standard
            // list items. The list items are specified in the
            // data model using the name label
            StandardListItem {
        onTriggered: {
            // Update the Label with the name and PIN
            // for the selected list item
            var selectedItem =;
            myLabel.text = "The PIN for " + 
       + " is " + 
Label {
    id: myLabel
    multiline: true 
    text: "Make a selection"
    horizontalAlignment: HorizontalAlignment.Center
    minHeight: 150
    maxWidth: 600

And here is the data model refererenced above, in items.xml:

    <header title="Contacts">
        <listItem name="Westlee Barichak" pin="82G61H56" />
        <listItem name="Mike Chepesky" pin="97I55J42" />
        <listItem name="Mark Tiegs" pin="21K43L56" />
        <listItem name="Denise Marshall" pin="12Q87J43" />

List view example

The Lists documentation has a comprehensive tutorial on implementing a ListView in your app. For more information, see Tutorial: Lists.

Animation showing a list item being selected in the Quotes sample app.

Last modified: 2013-12-21

comments powered by Disqus