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" />


A Header is used to group or organize items in a list.

Screen shot showing a header.

A Header consists of a title label, a subtitle label, and a visual separator.

The title label appears on the left side of the header, in bold font.

The subtitle label appears on the right side of the header. The font for the subtitle label is smaller than the font for the title label.

The font and font size for the labels are fixed and can't be changed.


Interactive list header 10.3

Since 10.3, you can specify the mode of a Header using the HeaderMode::Type enumeration. A header supports several modes, including:

Using the Interactive mode, you can specify the behavior of the interactive list header using the onClicked() signal, and prompt a user to tap for additional information using the subtitle property. In addition to the text you specify in the subtitle property, an additional UI component is added to the header to indicate that the header is interactive. The following image shows an interactive list header:

Screen shot showing an interactive header.

Connecting an onClicked() signal to a header in HeaderMode::Default changes the behavior and appearance to that of an interactive list header automatically. However, if you want the additional UI prompt to appear without connecting an onClicked() signal, you need to explicitly set the mode to HeaderMode::Interactive. By default, the header mode is set to HeaderMode::Default.

The following code sample creates the interactive list header shown in the image above:

Header {
    id: interactiveheader
    title: "Interactive Qml header"
    subtitle: "Find out more"
    mode: HeaderMode.Interactive
        onClicked: {

In an interactive list header, the subtitle text is used to inform your users they can tap the header to view additional information. In addition to the text you specifiy, an arrow is added to the UI automatically prompting users to tap the header.

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: 2014-06-24

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus