Barry's jQuery Mobile Demos: Lists


jQuery mobile also provides mobile device enhancements to the standard HTML lists <ol> and <ul> tags. The mobile view of lists is enacted when you add the attribute data-role="listview" to the tags. For example the following numbered list definition:

<ol data-role="listview">
  <li>List item 1</li>
  <li>List item 2</li>
  <li>List item 3</li>
  <li>List item 4</li>

Produces a list that appears as follows.

  1. List item 1
  2. List item 2
  3. List item 3
  4. List item 4

A more useful list is when each of the elements can be selected by a click or touch. This is produced when the elements are links. For example, making all the above list elements a null link, e.g. the first one would be:

<li><a href="">List item 1 </a></li>

The list appears as follows with all elements as selectable link elements. Note the arrow on far right of each selectable link.

  1. List item 1
  2. List item 2
  3. List item 3
  4. List item 4

We can adjust the appearance of the list by adding the attribute data-inset="true" to the definition. This adds more desirable rounded corners to the list block and a border around the list.

<ol data-role="listview" data-inset="true">

This makes the above list appear as follows.

  1. List item 1
  2. List item 2
  3. List item 3
  4. List item 4

List dividers

We can also add list dividers to our longer lists to better organise the elements. A list divider can be added with a list element tag with attribute data-role="list-divider". For example, to add a list divider to the above example list as the first element we would place the following list element tag at the start of the list.

<li data-role="list-divider">Divider 1</li>

The list would then appear as:

  1. Divider 1
  2. List item 1
  3. List item 2
  4. List item 3
  5. List item 4

We can also introduce alphabetic dividers automatically by introducing the data-autodividers="true" attribute to the list header, e.g.

<ol data-role="listview" data-inset="true" data-autodividers="true">
  <li><a href="#">Aadvark</a></li>
  <li><a href="#">Apple</a></li>
  <li><a href="#">Bear</a></li>
  <li><a href="#">Zebra</a></li>

This would appear as follows.

  1. Aadvark
  2. Apple
  3. Bear
  4. Zebra

Notice how the Alphabet dividers are only inserted where there is an appropriate list item. Notice also how, since this is a numbered list, the numberings restarts at each divider. You can remove the numbers altogether by making your list with the <ul> tag rather than the <ol> tag.

We can also adjust the appearance of our lists. The above lists all had the same icon for the selectable list elements. We can specify the icon for each list elements by using the data-icon attribute in the <li> tag. For example, the following codes a four element lists with three new different icons.

<ul data-role="listview" data-inset="true">
    <li><a href="#">Default icon</a></li>
    <li data-icon="bars"><a href="#">Bars icon</a></li>
    <li data-icon="cloud"><a href="#">Cloud icon</a></li>
    <li data-icon="clock"><a href="#">Clock icon</a></li>

This appears as follows.

Icons and count bubbles

We can also add icons and thumbnails to the left hand side of our list elements by inserting an <img> tag in the list text (<a> tag contents). For pure 16x16 pixel icons we add the class="ui-li-icon" to the <img> tag. For other image sizes we just add the standard <img> tag as the first element inside the <a> tag. This will cause jQuery Mobile to scale the image to 80x80 pixels.

Another option is to split the item contents from the right hand icon. This results in two section in the list element with a vertical divider between them. This is achieved by placing two links in the list item definition. The first is associated with the item contents and the second is associated with the jQuery Mobile icon displayed. The text in the second link is displays as a tool tip when the user hovers over the right hand side icon. For example the following code defines a split list element with text "Bars icon" displayed on the left.

<li data-icon="bars">
   <a href="#">Bars icon</a>
   <a href="#">Alt text</a>

This would appear as follows when the previous example had this item redefined and when the cursor hovered over the right hand icon.

We can also add count bubbles to list elements. These are added by defining a tag such as a <span> with the class="ui-li-count" attribute. The idea of a count bubble is to provide a numeric count of some feature of a jQuery Mobile application. To be useful, there will need to be some code developed to update the count bubble as required. As an example of a count bubble the following two element list has a count bubble on the first list element.

<ul data-role="listview" data-inset="true">
    <li data-icon="cloud">
       <a href="#">Files<span class="ui-li-count">99</span></a>
    <li data-icon="clock"><a href="#">Time</a></li>

This would appear as follows.

List search fields

The final feature of jQuery Mobile lists that we will see is the use of list filters. Filters are useful for searching lists and also any other element with multiple child elements. We will find the list search most useful on mobile devices. There are three things necessary for a search facility:

  1. An input field with data-type="search" attribute, embedded in a in a form with class="ui-filterable" attribute.
  2. A list (or other) element data-filter="true" attribute.
  3. The above input field tag from point 1 needs an id attribute that matches a data-input attribute in the searchable element from point 2.

This is best shown with an example. The following code defines a search field and a corresponding searchable list.

<p>This is list search field:</p>
<form class="ui-filterable">
   <input id="filter1" data-type="search"/>
<p>This is the searchable list:</p>
<ul data-role="listview" data-inset="true"
    data-filter="true" data-input="#filter1">
  <li><a href="#">Aadvark</a></li>
  <li><a href="#">Apple</a></li>
  <li><a href="#">Cat</a></li>
  <li><a href="#">Dog</a></li>

Initially this list will appear as follows.

This is list search field:

This is the searchable list:

As values are typed in the search field the items displayed in the list reduces to possible candidates. For example, type the letter 'd' the list above and the list will be reduced to two possible selections. Notice how the search process looks for the pattern anywhere in each list item and not from the start of the list item. Note also that we can place the search field anywhere we wish, including after the list we are searching. We can also place a hint in the search field using the placeholder attribute in the search input tag. For example the following definition:

<input id="filter1" data-type="search" placeholder="Search..."/>

Would place the hint "Search..." in the search field when the page is initialized and appear:

The final attribute of search that we will find useful is the ability to use alternate search text for a list item. This is text that is searched but not displayed in the list item. To do this we add a data-filtertext attribute to the <li> tag, e.g.

<li data-filtertext="fido"><a href="#">Dog</a></li>

The following list has the above definition for "Dog". Try typing "fido" in the search field.

A final point to note is that if you create lists dynamically with your JavaScript code, then you will have to prompt jQuery Mobile to recalculate the dividers and other automatic formatting. This is done with the listview() method. For example, if we had a list with id="myList" then we could "refresh" the list with the code: