WinJS.UI.ListView object

Displays data items in a customizable list or grid.

Syntax

<div data-win-control="WinJS.UI.ListView"></div>

var object = new WinJS.UI.ListView(parentObject, options);

Members

The ListView object has these types of members:

• Constructors
• Events
• Methods
• Properties

Constructors

The ListView object has these constructors.

Events

The ListView object has these events.

Methods

The ListView object has these methods.

Properties

The ListView object has these properties.

Remarks

The ListView can accept data from several different types of sources, such as Really Simple Syndication (RSS) feeds or lists of images. To learn how to create your first ListView, see the Add a ListView Quickstart.

Items in a ListView control can contain other controls, but they can't contain a FlipView or another ListView.

Asynchronous function issue

ListView can be used in an asynchronous environment except when using embedded components that only support synchronous functionality (such as Repeater).

Styling the ListView

CSS classes

To customize the ListView, you can define your own styles for these Cascading Style Sheets (CSS) classes (defined by the Windows Library for JavaScript style sheets):

Note  

• Windows 8.1 In previous versions of Windows, ListView items can be styled using the CSS selector .win-container .win-item. Starting with Windows 8.1, another element contains items within the ListView, and so CSS selectors to style items need to be written as .win-container .win-itembox .win-item.
• Windows 8.1 In Windows 8.1, the win-groupheader CSS class introduces noticeable margins in an app. Use win-groupleader instead.

Note  Some of these classes (such as win-item) are used by multiple WinJS controls. To apply a style to just the ListView, add .win-listview to the style selector. For more info, see Styling the ListView and its items.

Setting the ListView control's height

The ListView does not dynamically adjust its height to fit your content. For a ListView to render, you must specify an absolute value for its height. The WinJS style sheets set the ListView control's height to 400 pixels.

This example overrides the default style for ListView controls and sets their height to 500 pixels.

.win-listview 
{
    height: 500px; 
}

The win-listview class is a class defined by the WinJS that you can use to style the ListView. The example you just saw changes the height of every ListView to 500 pixels. To change just one ListView, add the ID of the ListView control's hosting div element to the selector. This example changes the height of the ListView with the ID "basicListView".

#basicListView.win-listview 
{
    height: 500px; 
}

Maximum number of items

The ListView doesn't support more than 1.5 million pixels worth of items.

Detaching the ListView from the DOM

Don't use a ListView control after you've detached it from the DOM. When you detach a ListView from the DOM, it starts releasing resources to free up memory and won't work properly anymore.

Using a ListView in a PageControl

When you use a ListView inside a PageControl, add this code to your PageControl object's ready method to ensure that the ListView gets the correct reading order:

element.setAttribute("dir", window.getComputedStyle(this._element, null).direction);

Examples

This example creates an item template and a ListView.

<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template">
    <div style="width: 282px; height: 70px; padding: 5px; overflow: hidden; display: -ms-grid;">

        <!-- Displays the "picture" field. -->
        <img data-win-bind="alt: title; src: picture"
            src="#"
            style="width: 60px; height: 60px; margin: 5px; -ms-grid-column: 1;" />
        <div style="margin: 5px; -ms-grid-column: 2">

            <!-- Displays the "title" field. -->
            <h4 data-win-bind="innerText: title"></h4>

            <!-- Displays the "text" field. -->
            <h6 data-win-bind="innerText: text"></h6>
        </div>
    </div>
</div>

<div id="basicListView" data-win-control="WinJS.UI.ListView"
    data-win-options="{itemDataSource : DataExample.itemList.dataSource, 
    itemTemplate: select('#mediumListIconTextTemplate'),
    layout : {type: WinJS.UI.GridLayout}}">
</div>

The next example defines the data for the ListView in a separate JavaScript file. For the ListView to access the data, add a reference to the JavaScript file to the HTML page that contains the ListView.

// data.js
(function () {
    "use strict";

    var dataArray = [
    { title: "Basic banana", text: "Low-fat frozen yogurt", picture: "images/60banana.png" },
    { title: "Banana blast", text: "Ice cream", picture: "images/60banana.png" },
    { title: "Brilliant banana", text: "Frozen custard", picture: "images/60banana.png" },
    { title: "Orange surprise", text: "Sherbet", picture: "images/60orange.png" },
    { title: "Original orange", text: "Sherbet", picture: "images/60orange.png" },
    { title: "Vanilla", text: "Ice cream", picture: "images/60vanilla.png" },
    { title: "Very vanilla", text: "Frozen custard", picture: "images/60vanilla.png" },
    { title: "Marvelous mint", text: "Gelato", picture: "images/60mint.png" },
    { title: "Succulent strawberry", text: "Sorbet", picture: "images/60strawberry.png" }
    ];

    var itemList = new WinJS.Binding.List(dataArray);

    // Create a namespace to make the data publicly
    // accessible. 
    var publicMembers =
        {
            itemList: itemList
        };
    WinJS.Namespace.define("DataExample", publicMembers);

})();

For a full walkthrough of the code and more info about creating your first ListView, see Quickstart: Add a ListView.

Requirements

See also

Quickstart: Add a ListView

Styling the ListView and its items

HTML ListView essentials sample (Windows)

HTML ListView item templates sample (Windows)

HTML ListView grouping and SemanticZoom sample (Windows)