Listview Widget

Basic linked lists

A listview is coded as a simple unordered list containing linked list items with a data-role="listview" attribute. jQuery Mobile will apply all the necessary styles to transform the list into a mobile-friendly listview with right arrow indicator that fills the full width of the browser window. When you tap on the list item, the framework will trigger a click on the first link inside the list item, issue an Ajax request for the URL in the link, create the new page in the DOM, then kick off a page transition. View the data- attribute reference to see all the possible attributes you can add to listviews.

Here is the HTML markup for a basic linked list.

<ul data-role="listview">
  <li><a href="acura.html">Acura</a></li>
  <li><a href="audi.html">Audi</a></li>
  <li><a href="bmw.html">BMW</a></li>
</ul>

• ui-listview: Outermost container for listview widget
  • ui-listview-item-static: Simplest list item of listview when there are no anchor tags nested inside an item
  • ui-listview-item-divider: List item element which is a divider
  • ui-listview-item-has-alternate: List item element which has more than one anchor elements
    • ui-listview-item-button: First anchor element
    • ui-listview-item-split-button: Last anchor element
      • ui-listview-item-split-icon: Icon of last anchor element
  • ui-listview-item: List item element which has only one anchor elements. If the listview item has count bubble, it will additionally have ui-listview-item-has-count class.
    • ui-listview-item-button: Anchor element of the list item
    • ui-listview-item-icon: Icon for the list item
    • ui-listview-item-count-bubble: Count bubble for list item if present

Style note on non-inset lists: all standard, non-inset lists have a -1em (16px) margin to negate the 1em padding on the content area to make lists extend to the edges of the screen. If you add other widgets above or below a list, the negative margin may make these elements overlap so you'll need to add additional spacing in your custom CSS.

Numbered lists

Lists can also be created from ordered lists (ol) which is useful when presenting items that are in a sequence such as search results or a movie queue. When the enhanced markup is applied to the listview, jQuery Mobile will try to first use CSS to add numbers to the list and, if not supported, will fall back to injecting numbers with JavaScript.

Read-only lists

Listviews can also be used to display a non-interactive list of items, usually as an inset list. This list is built from an unordered or ordered list that don't have linked list items. The framework styles static list items identically to list items containing links, but static items receive the body background color (ui-body-a) rather than the button background color (ui-btn-a).

Split button lists

In cases where there is more than one possible action per list item, a split button can be used to offer two independently clickable items - the list item and a small arrow icon in the far right. To make a split list item, simply add a second link inside the li and the framework will add a vertical divider line, style the link as an icon-only arrow button, and set the title attribute of the link to the text of the link for accessibility.

You can set the icon for the right split icon by specifying a data-split-icon attribute on the listview with an icon name you want. The default icon is "carat-r" but can be configured with the splitIcon listview option. By adding a data-icon attribute to the list item, you can set individual icons for each split. The theme swatch color of the split button defaults to "b" (blue in the default theme) but can be set by specifying a swatch letter with the data-split-theme attribute at the listview level or for individual splits with the data-theme attribute at the link level.

List dividers

List items can be turned into dividers to organize and group the list items. This is done by adding the data-role="list-divider" to any list item. These items are styled with the bar swatch "b" by default (blue in the default theme) but you can specify a theme for dividers by adding the data-divider-theme attribute to the list element (ul or ol) and specifying a theme swatch letter.

Autodividers

A listview can be configured to automatically generate dividers for its items. This is done by adding a data-autodividers="true" attribute to any listview.

By default, the text used to create dividers is the uppercased first letter of the item's text. Alternatively you can specify divider text by setting the autodividersSelector option on the listview programmatically. For example, to add a custom selector to the element with id="mylistview":

$( "#mylistview" ).listview({
  autodividers: true,
 
  // the selector function is passed a <li> element from the listview;
  // it should return the appropriate divider text for that <li>
  // element as a string
  autodividersSelector: function ( li ) {
    var out = /* generate a string based on the content of li */;
    return out;
  }
});

Note that if you are using formatted list items that contain a floating element (for example ui-li-aside), this element precedes its siblings regardless of the order in your HTML markup. This results in the first character of the floating element being used as divider text. Therefore it is recommended to specify the divider text in this case.

If new list items are added to the list or removed from it, the dividers are not automatically updated: you should call refresh() on the listview to redraw the autodividers.

Hiding dividers

The listview hidedividers extension provides the option hideDividers. When set to true, and you call .listview( "refresh" ) after hiding a list item by adding the class ui-screen-hidden to it, the extension will hide those dividers that are followed immediately by another divider.

Search filter

As of jQuery Mobile 1.4.0 this functionality has been transferred to the filterable widget, which provides a more generic solution.

Note: Features such as automatic text input generation and special handling of listview dividers are deprecated as of 1.4.0. The documentation for filterable describes the migration path for listviews.

Filter reveal

The filter reveal feature makes is easy to build a simple autocomplete with local data. When a filterable list has the data-filter-reveal="true" attribute, it will auto-hide all the list items when the search field is blank. The data-filter-placeholder attribute can be added to specify the placeholder text for the filter. If you need to search against a long list of values, we provide a way to create a filter with a remote data source.

Remote autocomplete with listview filter

To use the filter as an autocomplete that taps into remote data sources, you can use the filterablebeforefilter event to dynamically populate a listview as a user types a search query. This is useful when you have a very large data set like cities, zip codes, or products that can't be loaded up-front locally. Use the view source button to see the JavaScript that powers this demo.

If you have a small list of items, you can use the listview filter reveal option to make an autocomplete with local listview data.

Cities worldwide

After you enter at least three characters the autocomplete function will show all possible matches.

Text formatting & counts

The framework includes text formatting conventions for common list patterns like header/descriptions, secondary information and counts through semantic HTML markup.

• To add a count indicator to the right of the list item, wrap the number in an element with a class of ui-li-count
• To add text hierarchy, use headings to increase font emphasis and use paragraphs to reduce emphasis.
• Supplemental information can be added to the right of each list item by wrapping content in an element with a class of ui-li-aside

Thumbnails & icons

To add thumbnails to the left of a list item, simply add an image inside a list item as the first child element. The framework will scale the image to 80 pixels square. To use standard 16x16 pixel icons in list items, add the class of ui-li-icon to the image element.

Inset lists

If lists are embedded in a page with other types of content, an inset list packages the list into a block that sits inside the content area with a bit of margin and rounded corners (theme controlled). By adding the data-inset="true" attribute to the list (ul or ol), applies the inset appearance.

Calling the listview plugin

You can directly call the listview plugin on any selector, just like any jQuery plugin:

$( "#mylist" ).listview();

Updating lists

If you add items to a listview, you'll need to call the refresh() method on it to update the styles. For example:

$( "#mylist" ).listview( "refresh" );

Note that the refresh() method only affects new nodes appended to a list. This is done for performance reasons. Any list items already enhanced will be ignored by the refresh process. This means that if you change the contents or attributes on an already enhanced list item, these won't be reflected. If you want a list item to be updated, replace it with fresh markup before calling refresh.

If you initially want to hide a list item you can do this by adding a class of ui-screen-hidden to the li element. Using this class ensures the corner styling is applied correctly as well as border-bottom on the last visible item.