Guidelines and checklist for ListView controls (Windows Store apps)

Follow these guidelines for adding ListView controls to your Windows Store app.

Is this the right control?

Use the ListView control to present a collection of data as a series of items to users of your apps. For example, use a ListView to present a list of emails, items in a shopping cart, a list of images in the pictures library, and search results.

Use a ListView when you want to:

• Present data in groups
• Let users select one or more items
• Customize how your data is loaded
• Provide better keyboarding and selection
• Dynamically edit your list of items and get built-in animations
• Customize your items with templates or give your items their own events
• Have items with different sizes

Don't use a ListView as a general purpose layout control. To create a grid or table-like layout, use the CSS layout, such as grid layout or flexible box ("flexbox") layout. (For more info about CSS layouts, see Choosing a CSS3 layout for your app.)

It is appropriate to put buttons inside of ListView items, but don’t use a ListView to create command toolbars, such as toolbar of buttons for cut, copy, and paste commands. Instead, use several button controls laid out side-by-side.

Using the right interaction pattern

ListView controls in Windows are used in four different ways: to display a content library, to display master/detail data, as a picker, or to display static data. When you use the ListView in one of these ways, users expect it follow one of these interaction patterns:

• Content library pattern

  Use this pattern when displaying a collection, or library, of content. It is typically used when presenting media such as pictures and videos.

  

  In a content library, the primary user action is to tap on an item to invoke an action. Most content libraries support the selection of items using a new touch gesture called the cross-slide.

  To make your ListView follow the content library pattern, configure it like this:

  • selectionMode: Set to "single" or "multi".

  • tapBehavior: Set to "invokeOnly".

  • swipeBehavior: Set to one of these values:

    • "none" if the selectionMode is "none".
    • "select" if the selectionMode is "single" or "multi".
• Master/detail pattern (also known as split view pattern)

  When using the a master/detail pattern, you use the ListView the master pane. The master pane shows a list of items that the user can select. You use another control as the details pane, which shows additional info for the selected item. When the user selects an item in the master pane, it is displayed in the details pane.

  

  To make your ListView behave like the master pane in the master/detail pattern, configure it like this:

  • selectionMode: "single" or "multi". Use "single" for single-select.

  • tapBehavior: "directSelect"

  • swipeBehavior: "none" for single, "select" for multi.

  You can chain several ListView controls together to create complex master/detail hierarchies.

• Picker pattern

  Use the picker pattern when the primary user action is selection and the ability to invoke an item on tap is not important.

  

  In this interaction pattern, tap is used for selection in addition to cross-slide. To make a picker-style interaction ListView, use these values:

  • selectionMode: "single" or "multi", depends on what you want in your app.

  • tapBehavior: "toggleSelect"

  • swipeBehavior: "select"

• Static pattern

  Use this pattern when you want to use the ListView solely as a way to present content, and most types of interactivity are disabled. This pattern is useful for collections of items that are read-only and can't be activated or navigated into. Static mode uses the following values:

  • selectionMode: "none"

  • tapBehavior: "none"

  • swipeBehavior: "none"

General guidelines

Here are some general guidelines to follow when using the ListView.

• Items in the same ListView should have the same behavior

  If one item in a ListView performs an action when the user taps it, all items in the ListView should perform an action when the user taps them.

• If your list is divided into groups, use a SemanticZoom

  The SemanticZoom control makes it easier for users to navigate through lists that are divided into groups.

  The zoomed-in view uses a grid layout and displays group headers and individual items.

  

  The zoomed out view just displays the group headers:

  

• Suppress selection checkmarks in single-selection scenarios

  When the selectionMode is set to "single", don't display selection checkmarks.

  For example, in a master/detail view, suppress the checkmark in the master view when it's in the single selection mode. For an example, see the HTML ListView customizing interactivity sample.

Guidelines for list and grid layouts

The Windows Library for JavaScript provides two types of layouts for the ListView: a list layout and a grid layout. (You can also create your own custom layouts.)

List layout

The list layout displays a single-column, uses a top-to-bottom reading order, and always pans or scrolls vertically. The list layout doesn't display group info, such as group headers or group boundaries.

The list layout is good for the master view in a master/detail view. It's also a good choice when your app is in a snapped view or whenever you want to conserve space. It works well in portrait orientations and when you don't need to organize items into groups.

For example, in common email applications, you’ll often see a list of folders on the side of the screen. The list of folders is a good candidate for using a ListView that has a list layout.

Grid layout

The grid layout always pans horizontally, and items are laid out following a top-to-bottom, then left-to-right reading order.

The grid layout is better suited for displaying content libraries. Grid layouts generally take up more space that list layouts.

Grid layout supports item grouping. There are two main situations where grouping is beneficial: when the collection of items is large, and when the items are naturally grouped (such as a collection of songs grouped into various albums). Providing groups organizes the collection, enabling users to better find their way around.

Guidelines for interactive group headers

When using interactive group headers in a ListView, register for the Ctrl + Alt + G key press and use it to navigate the user into the group for the currently focused item.

Managing the ListView layout when going to a snapped view

In Windows 8, apps can be snapped to either side of the screen, which limits their width to 320px. Likewise, when unsnapped, the width of the app is much greater, allowing more and more content to be shown.

• If your ListView uses a grid layout, switch it to a list layout when your app is snapped.

• If your ListView contains groups, display the groups when you switch to a list layout. When the user taps a group, update the ListView to display the items in the group and provide a back button that lets the user go back to the group display. You can use the SemanticZoom control to provide this functionality.

• One way of saving space when your app is snapped to is to change how the items in the ListView are displayed. You can use Media Queries to update your CSS automatically or you can switch to a different itemTemplate when the app enters the snapped view. If you update your CSS styling, you must call the ListView control's forceLayout method for it to display the changes correctly.
• Just before your app snaps, store the ListView control's indexOfFirstVisible value, and then restore it when the app unsnaps so that the user doesn't lose their position in the list.

For more info about snapped views, see Guidelines for snapped and fill views.

Related topics

Quickstart: adding a ListView

Guidelines for snapped and fill views

HTML ListView customizing interactivity sample

Build date: 11/29/2012