# Titanium.UI.ListItem

A list item is an individual item in a list section.

Availability
3.1.0
3.1.0
9.2.0

# Overview

A list item is a combination of a ListDataItem and ItemTemplate. The list data item represents the actual data, while the item template represents the style elements of the item.

You should not create ListItem objects with a JavaScript factory method, as you do other Titanium proxies. Instead, you should pass a ListDataItem array to the setItems method of a ListSection. The list data items contain the data you want to display in the list.

Alloy applications can use <ListItem> elements to create ListItem objects. <ListItem> elements must be nested inside a <ListSection> element, which itself is nested in a <ListView> element, as shown below:

<Alloy>
    <ListView id="list">
        <ListSection id="accounts">
            <ListItem image="images/checking_account.png" title="Checking"/>
            <ListItem image="images/saving_account.png" title="Savings"/>
        </ListSection>
    </ListView>
</Alloy>

By default, only the title, image and accessoryType keys of the list data item's properties dictionary are displayed if an item template is not defined. See "Default List Items" under "Examples" section for an example of using the default template.

# Item Templates

To customize the style of a list item, use an item template to create your view structure.

Add key-value pairs of view properties and their values to the properties dictionary of the item template to set view properties of the list item.

Note: If possible, do not use Ti.UI.SIZE or non-static dimensions to set the dimensions of view elements in list items. Instead, try to use static dimensions. Scrolling in the list view may be jerky if you use non-static dimensions.

Add key-value pairs of event names and their callback functions (or array of callback functions for multiple callback bindings) to the events dictionary of the item template to bind callbacks to events, which are bubbled from the subcomponents of the item.

Add additional views, such as labels or image views, to the childTemplates array of the item template. The child templates are item templates with two extra properties:

  • Set the type property to a Titanium view class, such as Ti.UI.Label or Ti.UI.ImageView, to use that view in your template.
  • Set the bindId to bind the template to a custom property in the list data item. The custom properties in the list data item contain key-value pairs of view properties and their values.

A list template supports the following view classes:

For example, suppose you have a list data item defined as {foo:{text: 'foobar'}} and an item template defined as {childTemplates: [{type: 'Ti.UI.Label', bindId: 'foo'}]}. The foo property in the list data item binds to the label in the template, which sets the text property of the label in the template to the text property in the list data item.

To bind the list data item to an item template, use the Titanium.UI.ListView.templates property to map the template to a style name, then use the style name to either set the Titanium.UI.ListView.defaultItemTemplate property to globally set the style for all items or set the template property of the list data item to override or individually set the style.

On iOS, you can specify one of the template constants for the ListDataItem.template property or Titanium.UI.ListView.defaultItemTemplate property: Titanium.UI.LIST_ITEM_TEMPLATE_CONTACTS, Titanium.UI.LIST_ITEM_TEMPLATE_SETTINGS or Titanium.UI.LIST_ITEM_TEMPLATE_SUBTITLE.

# Eventing

Unlike other views, you cannot use the addEventListener method to bind callbacks to events for a ListItem.

Use list view's Titanium.UI.ListView.itemclick event to monitor click events on items in the list view. Do not rely on the source property to determine which item fired the event. Either use the sectionIndex and itemIndex, or the itemId to determine the list item that generated the event and use the bindId to check which child control fired the event. See "Default List Item" under "Examples" section for an example of using the itemclick event.

To monitor events that bubble to the ListItem or to monitor events of the view subcomponents, bind them to the item by using the events dictionary of the item template or the child view templates respectively. Add the bindings as key-value pairs, where the key is the event name and the value is the callback (or array of callbacks for multiple bindings). See "List Items with an Item Template" under "Examples" section for an example of binding a click event to an item using an item template.

# Examples

# Default List Items

Creates a list without using an item template. Monitors the itemclick event to check and uncheck tasks.

var win = Ti.UI.createWindow({backgroundColor: 'white'});
var listView = Ti.UI.createListView();

var tasks = [
    {id: 'trash', name: 'Take Out the Trash', icon: 'trash.png'},
    {id: 'dishes', name: 'Do the Dishes', icon: 'dishes.png'},
    {id: 'doggie', name: 'Walk the Dog', icon: 'doggie.png'}
];

var data = [];
for (var i = 0; i < tasks.length; i++) {
    data.push({ 
        properties: {
            itemId: tasks[i].id,
            title: tasks[i].name,
            image: tasks[i].icon,
            accessoryType: Ti.UI.LIST_ACCESSORY_TYPE_NONE,
            color: 'black'
        }
    });
}

var section = Ti.UI.createListSection();
section.items = data;
listView.sections = [section];
listView.addEventListener('itemclick', function(e) {
    var item = section.getItemAt(e.itemIndex);
    if (item.properties.accessoryType == Ti.UI.LIST_ACCESSORY_TYPE_NONE) {
        item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_CHECKMARK;
        item.properties.color = 'red';
    } else {
        item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_NONE;
        item.properties.color = 'black';
    }
    section.updateItemAt(e.itemIndex, item);
});
win.add(listView);
win.open();

# Default List Items (Alloy version)

Alloy version of previous example. For additional Alloy examples of using ListView, see Titanium.UI.ListView.

index.xml

<!-- views/index.xml -->
<Alloy>
    <Window class="container" title="Some things">
        <ListView id="listView">
            <ListSection id="section">
                <ListItem image="images/trash.jpg" title="Take Out the Trash"/>
                <ListItem image="images/dishes.png" title="Do the Dishes"/>
                <ListItem image="images/doge.png" title="Walk the Dog"/>
            </ListSection>
        </ListView>
    </Window>
</Alloy>

index.js

// controllers/index.js
$.listView.addEventListener('itemclick', function(e) {
    var item = $.section.getItemAt(e.itemIndex);
    if (item.properties.accessoryType == Ti.UI.LIST_ACCESSORY_TYPE_NONE) {
        item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_CHECKMARK;
        item.properties.color = 'red';
    } else {
        item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_NONE;
        item.properties.color = 'black';
    }
    $.section.updateItemAt(e.itemIndex, item);
});

# List Items with an Item Template

Previous example modified to use an item template. The template defines a small icon on the far left, a title label to the right of the icon and a subtitle below the title label in smaller text.

Monitors the click event of the item rather than the itemclick event of the list view.

var win = Ti.UI.createWindow({backgroundColor: 'white'});

var plainTemplate = {
    childTemplates: [
        {                            // Image justified left
            type: 'Ti.UI.ImageView', // Use an image view for the image
            bindId: 'pic',           // Maps to a custom pic property of the item data
            properties: {            // Sets the image view properties
                width: '50dp', height: '50dp', left: 0
            }
        },
        {                            // Title
            type: 'Ti.UI.Label',     // Use a label for the title
            bindId: 'title',         // Maps to a custom title property of the item data
            properties: {            // Sets the label properties
                color: 'black',
                font: { fontFamily:'Arial', fontSize: '20dp', fontWeight:'bold' },
                left: '60dp', top: 0,
            },
        },
        {                            // Subtitle
            type: 'Ti.UI.Label',     // Use a label for the subtitle
            bindId: 'subtitle',      // Maps to a custom subtitle property of the item data
            properties: {            // Sets the label properties
                color: 'gray',
                font: { fontFamily:'Arial', fontSize: '14dp' },
                left: '60dp', top: '25dp',
            }
        }
    ],
    // Binds a callback to the click event, which catches events bubbled by the view subcomponents.
    events: {click: toggleCheck }
};

// The following JSON API calls copy the plainTemplate object minus functions.
// This method of copying an object is simple but not quick.
// If performance is a factor, create your own method to copy an object.

var redTemplate = JSON.parse(JSON.stringify(plainTemplate));
// Change the text color to red
redTemplate.childTemplates[1].properties.color = 'red';
redTemplate.childTemplates[2].properties.color = 'red';
// Rebind the click event callback
redTemplate.events.click = toggleCheck;

var listView = Ti.UI.createListView({
    // Maps plainTemplate to 'uncheck' and redTemplate to 'check' 
    templates: { 'uncheck': plainTemplate, 'check': redTemplate },
    // Use 'uncheck', that is, the plainTemplate created earlier for all items
    // Can be overridden by the item's template property
    defaultItemTemplate: 'uncheck'
});

var tasks = [
    {id: 'trash', name: 'Take Out the Trash', person: 'Yakko', icon: 'trash.png'},
    {id: 'dishes', name: 'Do the Dishes', person: 'Wakko', icon: 'dishes.png'},
    {id: 'doggie', name: 'Walk the Dog', person: 'Dot', icon: 'doggie.png'}
];

var data = [];
for (var i = 0; i < tasks.length; i++) {
    data.push({
        // Maps to the title component in the template
        // Sets the text property of the Label component
        title : { text: tasks[i].name },
        // Maps to the subtitle component in the template
        // Sets the text property of the Label component
        subtitle : { text : tasks[i].person },
        // Maps to the pic component in the template
        // Sets the image property of the ImageView component
        pic : { image : tasks[i].icon },
        // Sets the regular list data properties
        properties : {
            itemId: tasks[i].id,
            accessoryType: Ti.UI.LIST_ACCESSORY_TYPE_NONE,
        }
    });
}

var section = Ti.UI.createListSection();
section.items = data;
listView.sections = [section];

// Modified version of the `itemclick` event listener
// Changes the item template rather than the list item's color property
function toggleCheck(e) {
    var item = section.getItemAt(e.itemIndex);
    if (item.properties.accessoryType == Ti.UI.LIST_ACCESSORY_TYPE_NONE) {
        item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_CHECKMARK;
        item.template = 'check';
    } else {
        item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_NONE;
        item.template = 'uncheck';
    }
    section.updateItemAt(e.itemIndex, item);
} 

win.add(listView);
win.open();

# Properties

# accessoryType

Availability
3.1.0
3.1.0
9.2.0
accessoryType :Number

Sets an accessory on the right side of an item.

Default: Titanium.UI.LIST_ACCESSORY_TYPE_NONE


# backgroundColor

Availability
3.1.0
3.1.0
9.2.0
backgroundColor :String | Titanium.UI.Color

Background color of the view, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: Transparent


# backgroundGradient

Availability
3.2.0
3.2.0
9.2.0
backgroundGradient :Gradient

Background gradient to render when the item is not selected.


# backgroundImage

Availability
3.2.0
3.2.0
9.2.0
backgroundImage :String

Background image to render when the item is not selected.

Must be a local resource.


# backgroundSelectedColor

Availability
10.0.0
10.0.0
10.0.0
backgroundSelectedColor :String | Titanium.UI.Color

Background color of the view, as a color name or hex triplet when item is selected.

On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false. For information about color values, see the "Colors" section of Titanium.UI.

Default: transparent


# backgroundSelectedGradient

Availability
10.0.0
10.0.0
backgroundSelectedGradient :Gradient

Background gradient to render when the item is selected.


# backgroundSelectedImage

Availability
10.0.0
10.0.0
10.0.0
backgroundSelectedImage :String

Background image to render when the item is selected.

Must be a local resource. On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false.


# canEdit

Availability
9.3.0
3.2.0
9.2.0
canEdit :Boolean

Specifies if the item can be deleted by a user initiated action.

For more information see the "Editing Support" section of Titanium.UI.ListView.

Default: false


# canInsert

Availability
5.2.0
9.2.0
canInsert :Boolean

Specifies if the item can be inserted by a user initiated action.

For more information see the "Editing Support" section of Titanium.UI.ListView.

Default: false


# canMove

Availability
9.3.0
3.2.0
9.2.0
canMove :Boolean

Specifies if the item can be reordered within the list view by a user initiated action.

For more information see the "Editing Support" section of Titanium.UI.ListView.

Default: false


# color

Availability
3.1.0
3.1.0
9.2.0
color :String | Titanium.UI.Color

Default text color of the item when not selected, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

On Android, selectedColor is not supported, so the text is always displayed in this color.

Only applies to the built-in templates.


# editActions

Availability
4.1.0
9.2.0
editActions :Array<RowActionType>

Specifies custom action items to be shown when when a list item is edited.

For more information see the "Editing Support" section of Titanium.UI.ListView.


# font

Availability
3.1.0
3.1.0
9.2.0
font :Font

Font to use for the item title.

Only applies to the built-in templates.

Default: System default font.


# height

Availability
3.1.0
3.1.0
9.2.0
height :Number | String

Row height in platform-specific units.

On Android, the value can be either a float value or a dimension string, for example, '40dp'. By default, the minimum height is 30 dp on the Android platform.

On iOS, the value can only be an absolute value.


# image

Availability
3.1.0
3.1.0
9.2.0
image :String

Image to render in the image area of the item, specified as a local path or URL.

On iOS, the image is on the left, and on Android, the image is on the right.

On Android, this image only appears on the default template.

On iOS, only local images are supported.

On iOS, this image only appears if the ListDataItem template property or ListView defaultItemTemplate property is either: LIST_ITEM_TEMPLATE_DEFAULT, LIST_ITEM_TEMPLATE_SETTINGS or LIST_ITEM_TEMPLATE_SUBTITLE.


# itemId

Availability
3.1.0
3.1.0
9.2.0
itemId :String

A user defined string that gets passed to events.


# searchableText

Availability
3.2.0
3.2.0
9.2.0
searchableText :String

The text to match against when the Titanium.UI.ListView is performing a search.

Used in conjunction with searchView, searchText and caseInsensitiveSearch properties of ListView.


# selectedBackgroundColor DEPRECATED

Availability
3.2.0
3.2.0
9.2.0
selectedBackgroundColor :String | Titanium.UI.Color

DEPRECATED SINCE 10.0.0

This property has been deprecated in favor of backgroundSelectedColor.

Background color of the view, as a color name or hex triplet when item is selected.

On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false. For information about color values, see the "Colors" section of Titanium.UI.

Default: transparent


# selectedBackgroundGradient DEPRECATED

Availability
3.2.0
9.2.0
selectedBackgroundGradient :Gradient

DEPRECATED SINCE 10.0.0

This property has been deprecated in favor of backgroundSelectedGradient.

Background gradient to render when the item is selected.


# selectedBackgroundImage DEPRECATED

Availability
3.2.0
3.2.0
9.2.0
selectedBackgroundImage :String

DEPRECATED SINCE 10.0.0

This property has been deprecated in favor of backgroundSelectedImage.

Background image to render when the item is selected.

Must be a local resource. On Android, clicking on ListItem's sub-views will not trigger this unless these views have 'touchEnabled' set to false.


# selectedColor

Availability
6.0.0
9.2.0
selectedColor :String | Titanium.UI.Color

Color to use for the item title when the item is selected, as a color name or hex triplet.

This property is only used on iOS.

For information about color values, see the "Colors" section of Titanium.UI.


# selectedSubtitleColor

Availability
6.1.0
9.2.0
selectedSubtitleColor :String | Titanium.UI.Color

Color to use for the item subtitle when the item is selected, as a color name or hex triplet.

This property is only used on iOS and if the ListDataItem template property or ListView defaultItemTemplate property is either: LIST_ITEM_TEMPLATE_SUBTITLE, LIST_ITEM_TEMPLATE_CONTACTS or LIST_ITEM_TEMPLATE_SETTINGS.

For information about color values, see the "Colors" section of Titanium.UI.


# selectionStyle

Availability
10.1.0
5.4.0
9.2.0
selectionStyle :Number

Selection style constant to control the selection color.

Specify one of the constants from <Titanium.UI.SELECTION_STYLE_*>.


# subtitle

Availability
3.1.0
9.2.0
subtitle :String

Subtitle to set in the text area of the item.

This subtitle only appears if the ListDataItem template property or ListView defaultItemTemplate property is set to either: LIST_ITEM_TEMPLATE_CONTACTS, LIST_ITEM_TEMPLATE_SETTINGS or LIST_ITEM_TEMPLATE_SUBTITLE.


# subtitleColor

Availability
6.1.0
9.2.0
subtitleColor :String | Titanium.UI.Color

Default text color of the subtitle, as a color name or hex triplet.

This property is only used on iOS and if the ListDataItem template property or ListView defaultItemTemplate property is either: LIST_ITEM_TEMPLATE_SUBTITLE, LIST_ITEM_TEMPLATE_CONTACTS or LIST_ITEM_TEMPLATE_SETTINGS.


# title

Availability
3.1.0
3.1.0
9.2.0
title :String

Title to set in the text area of the item.

This title only appears for the built-in templates.