Styling the ListView and its items (HTML)

  • Article

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

You can customize a ListView in many ways. You can style the ListView itself, the items it contains, or the templates that make up those items.

Using the Windows Library for JavaScript CSS classes

Like other Windows Library for JavaScript controls, the ListView provides a set of classes that you can override to customize its look and feel. The next sections describe how to use these classes to customize the ListView.

Styling the ListView itself

Before we cover how to style items in the ListView, let's go over how to style the ListView itself. Here are the primary classes you use to style the ListView:

  • win-listview: styles the entire ListView.
  • win-viewport: styles the viewport. This is where the scrollbar is displayed if it's needed.
  • win-surface: styles the scrollable area of the ListView. When the surface is bigger than the viewport, the viewport displays scrollbars.

Here's an example of a typical ListView that contains grouped items.

A ListView that contains grouped items.

The next illustration shows the same ListView with its win-listview, win-viewport, and win-surface parts highlighted:

The primary components of a ListView

General styling recommendations

Always assign an ID to your ListView and include that ID at the beginning of your CSS selector, as in this example:

#myListView .win-listview {
    background-image: url('../images/icecream.png'); 
    border: 2px solid red;
}

The ListView control has many default styles. If you attempt to override one of the styles and don't see any effect, it might be that your CSS selector isn't specific enough to override the default styles.

Styling the entire ListView control

If you want to add a fixed background image to the ListView control that shows behind the items inside, or if you want to apply a border to the entire control, override the win-listview class. This example gives the ListView an image background and a red border.

#myListView .win-listview {
    background-image: url('../images/icecream.png'); 
    border: 2px solid red;
}

Here's what the ListView looks like now:

A ListView with a border and a background image

Styling margins on the ListView

Use the win-surface class to apply margins to the ListView. Don't apply margins to the div element that hosts the ListView, because it won't get styled properly. Use win-surface instead. If you add a margin to win-surface, be sure to adjust the height of the ListView accordingly. You set the height by styling the div element that hosts the ListView.

Don't add margins or padding to win-surface when using a list layout.

By default, group headers have a 70px left-margin. If you override win-surface when displaying groups, we recommend you make the left margin 70px + whatever additional margin you want.

Styling the viewport based on its scrolling direction

You can use to the win-horizontal and win-vertical classes to apply styles to the ListView when it scrolls horizontally or vertically. This example adds a left margin to the viewport when the ListView can scroll horizontally.

#myListView .win-listview .win-viewport.win-horizontal {
    margin-left: 10px;  
}

The next example removes the left margin when the ListView can scroll vertically. It's common to give the ListView a vertical orientation when the view state is snapped.


#myListView .win-listview .win-viewport.win-vertical {
    margin-left: 0px; 
}

Styling the entire scrollable area

To style the scrollable portion of the ListView, override the win-surface class. This example applies to the ListView a background image that scrolls when the user scrolls through items.


#myListView .win-listview .win-surface {
    background-image: url('../images/icecream.png'); 
}

A ListView that has a styled surface

Styling the loading progress indicator

The ListView displays a progress indicator while loading items. You can style this indicator by overriding the win-progress class. This example hides the progress indicator.

#myListView .win-listview .win-progress{
    display: none;
}

Styling items and groups

The ListView contains groups and items.

  • Each group is contained in a group header, represented by the win-groupheader class.
  • Each item is contained in an item container, represented by the win-container class.

The group header and container components of a ListView

Styling an item

There are two ways to style items in your ListView. You can apply styles to the item template, or you can override the win-container class. There's one thing that you must always do in your template, and that's set the size of your items. If you don't set the size of your items, you might not get the layout you want.

To set the size of your items:

  • If you're using a WinJS.Binding.Template, set the size of the WinJS.Binding.Template element's child, as shown in this example:

    <!-- The WinJS.Binding.Template element. -->
<div id="templateExample" data-win-control="WinJS.Binding.Template">

    <!-- This is the root element. Be sure to set its width and height. -->
    <div style="width: 120px; height: 125px;">


        <img src="#" data-win-bind="alt: title; src: picture"
            style="width: 60px; height: 60px;" />
        <div>
            <h4 data-win-bind="innerText: title">
            </h4>

            <h6 data-win-bind="innerText: text">
            </h6>
        </div>
    </div>
</div>

  • If you're using a templating function, set the width and height of whatever DOM element your function returns.

Styling the item container

To style the item's container, override the win-container class. This example adds a margin to each item's container.

#myListView .win-listview .win-container{
    margin: 2px;
}

There are only two properties you can style on win-container: margin and background.

To make a transparent item, set the background color to transparent. This example makes a transparent item:

#myListView .win-container:not(.footprint):not(.hover)
{
    background-color: transparent;
}

Styling margins and padding on items

To add spacing between items, set a margin on the win-container class. We recommend against adding padding to items to create space between them; use a margin instead. All items in the same ListView must have the same margin.

Don't change the margin or padding on win-container after the ListView has started displaying items.

Styling the group header

To style the group header, override the win-groupheader class. This example adds a gray background to the group headers.

#myListView .win-listview .win-groupheader {                        
        background-color: #bfbfbf;           
}

A ListView that has styled group headers

Styling item interactions

Styling an item in the hover state

When the user moves the pointer over an item, the item enters the hover state. To change the style for an item in the hover state, use the hover pseudo-class. This example changes the background and the outline of a hovered item.

#myListView .win-container:hover {
    background-color: red; 
    outline: orange solid 5px;
}

A ListView with an item in the hovered state

Styling items that have focus

To style an item that has focus, use the win-focus class as a part of your style selector when styling the item container. To style the focus outline, use the win-focusedoutline class. This example changes the focused outline to a red, dashed line.

#myListView .focusExample.win-listview .win-focusedoutline {
    outline: red dashed 2px;
                     
}

Styling selected items

By default, selected items show a selection border. If you want your selected items to have the "filled" look, attach the win-selectionstylefilled CSS class to your ListView.

To further customize the appearance of selected items, you can override these classes:

  • win-selectionborder

    Styles the border around a selected item.

  • win-selectionbackground

    Styles the background of selected items.

  • win-selectionhint

    Styles the selection hint, a second checkmark that appears behind the selected item. Swiping the item makes the selection hint visible.

  • win-selectioncheckmark

    The checkmark on a selected item.

  • win-selectioncheckmarkbackground

    The background of the checkmark on a selected item.

You can also add the win-selected class as part of your style selector to customize other components, such as the item container, when an item is selected.