Qt Reference Documentation

QML ListItem Element

Symbian: Provides a template for creating a ListView delegate. More...

Inherited by SelectionListItem.

This element was introduced in Qt Quick Components 1.0.


Signal Handlers

Detailed Description

A ListItem does not contain any visible content by default, it has only an invisible padding area to which you can anchor other items. This means that all the ListItem components in a list can have common margins.

A ListItem with the padding rectangle drawn as white

A ListItem with items anchored to the padding area

Implementing a ListItem

The following code snippet implements a ListItem with a text item on the top and subtitle text below. The two items are aligned in a column and they have the standard vertical spacing for a ListItem. The code snippet results a default state list item shown in the list below.

 ListItem {
      id: listItem1
      Column {
          anchors.fill: listItem1.paddingItem
          ListItemText {
              id: titleText
              mode: listItem1.mode
              role: "Title"
              text: "Title text"
          ListItemText {
              id: subtitleText
              mode: listItem1.mode
              role: "SubTitle"
              text: "Subtitle text"

ListItem States

A ListItem can have one of the four internal states:

  • "" - The default state of a ListItem.

  • "Pressed" - The ListItem enters this state when the user presses the ListItem.

  • "Focused" - This state indicates that the list item has the focus but is not yet selected. This is only available on devices that have hardware selection keys that allow the user to navigate a list without touching the screen.

  • "Disabled" - In this state the ListItem does not handle any touch or hardware inputs and the ListItem does not emit signals.

See also ListHeading, ListItemText, and ListView.

Property Documentation

enabled : bool

If true, the user can interact with this list item. If false, the list item is disabled and does nothing when the user selects it. The default value of the property is true.

mode : string

The mode of the ListItem.

This property can be used to create an association between ListItem and ListItemText. This way ListItemText is aware of the internal state of ListItem.

 ListItem {
     id: listItem2

     ListItemText {
         anchors.fill: listItem2.paddingItem
         role: "Title"
         mode: listItem2.mode
         text: "Hello world!"

paddingItem : Item

The invisible padding rectangle for the ListItem that objects can be anchored to.

platformInverted : bool


If platformInverted is true, the component is visualized with the inverted style. For more information, see Using Inverted Style with Symbian Components. By default platformInverted is false.

This property group was introduced in Qt Quick Components 1.1.

subItemIndicator : bool

If true, the list item shows a graphical indication that pressing it will show the user another item to select. For example, when the user presses the item, another ListView is shown to the user.

The default value of the property is false.

Note: It is the responsibility of a developer to implement what happens when a ListItem with a subItemIndicator is pressed. This can be done by handling the pressed signal of a ListItem.

ListItem with with a subitem indicator

Signal Handler Documentation

ListItem::clicked ()

This signal is emitted when the user presses and then releases the list item.

ListItem::pressAndHold ()

This signal is emitted when the user presses on the list item for the "long press" period of time. The length of time for a long press is the same as for MouseArea::onPressAndHold() which is currently 800ms.