List views

A ListView is a scrollable control that's 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.


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.

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

Not applicable

Not applicable


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

If you are using API level 10.3.0 or later, you can specify the mode of a Header using the HeaderMode 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 that 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: {

Not applicable

Not applicable

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 that you specify, an arrow that prompts users to tap the header is added to the UI automatically.

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: 2015-05-07

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

comments powered by Disqus