API Documentation

Documentation for developing SailfishOS applications

ListItem QML Type

A simple Sailfish-styled item for building touch-interactive list items More...

Import Statement: import Sailfish.Silica 1.0




Detailed Description

The ListItem type provides a Sailfish-styled list-entry item with touch interaction and optional features common to list-type items. It can:

  • show a context menu (specified with the menu property) when the press-and-hold gesture is triggered
  • replace itself with a RemorseItem when remorseAction() is called (this is commonly used to show a remorse timer when the user triggers the item's removal via a context menu option)
  • run a remove-type animation on itself when animateRemoval() is called

An example:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 ListView {
     id: view

     delegate: ListItem {
         id: listItem
         menu: contextMenu
         contentHeight: Theme.itemSizeMedium // two line delegate
         ListView.onRemove: animateRemoval(listItem)

         function remove() {
             remorseAction("Deleting", function() { view.model.remove(index) })

         Label {
             id: label
             text: "Item: " + index
             color: listItem.highlighted ? Theme.highlightColor : Theme.primaryColor
         Label {
             anchors.top: label.bottom
             text: "Bottom line of text"
             font.pixelSize: Theme.fontSizeSmall
             color: listItem.highlighted ? Theme.highlightColor : Theme.secondaryColor

         Component {
             id: contextMenu
             ContextMenu {
                 MenuItem {
                     text: "Remove"
                     onClicked: remove()


Notice that the label text is colored differently when the item is highlighted. See the Theme documentation for guidelines on styling interactive controls in Sailfish OS.

Note: The ListItem height should not be modified, as the height automatically expands when the menu is opened. Set the contentHeight property instead.

See also BackgroundItem.

Property Documentation

contentHeight : real

Sets the normal height of the delegate. The delegate height may expand when a ContextMenu is open, but the content height will remain contentHeight.

The default value is Theme.itemSizeSmall.

highlighted : bool

This is true if down is true or the menu is open and thus the contents should be shown in a highlighted manner.

(See the Theme documentation for guidelines on styling interactive controls in Sailfish OS.)

See also BackgroundItem::highlighted.

This property holds the ContextMenu to open when "press and hold" is activated.

This property may be either a Component with a top-level ContextMenu, or a pre-created ContextMenu object. If a Component is provided the ContextMenu will be created and destroyed as needed.

True if the menu is open, otherwise false.

openMenuOnPressAndHold : bool

True if the menu should be opened when "press and hold" is activated, otherwise false.

The default value is true.

Method Documentation

animateRemoval(Item delegate)

Creates and starts a RemoveAnimation. If the ListItem is not the top-level Item of the delegate, the delegate must be set to the top level Item of the delegate.

Using animateRemoval() this is slightly faster than creating the RemoveAnimation during delegate creation.

See also RemoveAnimation.


Hides the menu if it is currently shown.

openMenu(object properties)

Displays the supplied menu.

The optional properties parameter specifies a map of properties to be set on the menu.

remorseAction(string title, object action, int timeout)

Creates a RemorseItem with title and sets the callback to action. timeout is optional and will default to 5 seconds if not provided.

Returns the RemorseItem instance created. This instance will be destroyed automatically after the action is either triggered or canceled.

We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.