Contact Us or call 1-877-932-8228


Whether it is a list of blog entries, products to purchase, or site navigation items, lists play an important role in web content. A listview in jQuery Mobile is coded as a simple unordered list (a <ul> element) with attribute data-role="listview". By default, jQuery Mobile stretches each item, button-like, to fill the screen; adds appropriate padding; and adds a right-arrow icon at right. Unordered lists of links without the data-role="listview" attribute still work of course, but don't get the styling:

lists with and without listview data-role

Open WidgetsUI/Demos/lists/index.html in a mobile browser and in a file editor to view the code. The unordered list is in the first (#home) page:

<ul data-role="listview">
	<li><a href="#about">About Us</a></li>
	<li><a href="#proprietors">Proprietors</a></li>
	<li><a href="#history">History</a></li>

Note that we use the data-add-back-btn="true" attribute on each of the non-home pages' headers: this automatically adds a button to the upper left of the header of the page:

<div data-role="page" id="about">
			<div data-role="header" data-add-back-btn="true">
				<h2>N&amp;B: About Us</h2>
			<div class="ui-content" role="main">
				<p>About us paratus validus foras at praesent usitas probo sino esse vicis sagaciter ratis feugait loquor.</p>
			<div data-role="footer">
				<h3>123 Fake St. Anywhere USA</h3>

See the jQuery Mobile docs for details on how to customize the back button.

You can, of course, use ordered lists (ol, instead of ul) to display items with numbers at left. Lists of items without links display much like vertically stacked buttons; the text for these nonlinked lists is slightly smaller than on the link-ful lists, to save space. Check out WidgetsUI/Demos/lists/ordered.html to view this:

Other Lists

Nested Lists

Please note that nested listviews were deprecated in jQuery Mobile 1.3 and dropped from version 1.4. There is, however, a JavaScript plugin available at that, when added to the page after the jQuery Mobile script, will render nested listviews as per previous versions.

Nesting child ul or ol list items inside a list allows you to create nested lists. Clicking (tapping) a list item that contains a child list generates a new page populated with the title of the parent in the header and the list of child elements. Lists can be nested multiple levels deep.

Open WidgetsUI/Demos/lists/nested.html in a mobile browser and in a file editor to view the code. The left screenshot shows the parent list; the right shows the page automatically added by jQuery Mobile to display the nested list:

nested lists

Here's the code:

<ul data-role="listview">
	<li><a href="#about">About</a>
			<li><a href="#about">About Us</a></li>
			<li><a href="#history">History</a></li>
			<li><a href="#proprietors">Proprietors</a></li>
	<li><a href="#privacypolicy">Privacy Policy</a></li>

The "About Us", "History", and "Proprietors" items are nested inside the "About" item - tapping "About" brings the user to a virtual page displaying the nested list, from which the user can tap a link to get to a page. Note that we include a script tag in the head of the page, linking to, which we downloaded from the link given above.

Split Button Lists

Some content dictates more than one action per list item - a user might be asked, for instance, to edit or delete a given item from a content-management admin screen. jQuery Mobile's split button list addresses this situation: adding a second link inside the list generates a vertical divider line with two clickable regions.

Open WidgetsUI/Demos/lists/split-button.html in a mobile browser and in a file editor to view the code:

split-button lists

This page lists the two owners of Nan & Bob's. Clicking the name of the owner brings the user to a detail page; clicking the icon at right opens a mailto: link to send an email. Note the use of attribute data-split-icon="info" on the ul to specify the icon to use. You can also add attribute data-icon to each individual list item to add a specific icon to each, instead of adding the same icon to all list items.

<ul data-role="listview" data-split-icon="info">
	<li><a href="#nan">Nan</a><a href="">Contact</a></li>
	<li><a href="#bob">Bob</a><a href="">Contact</a></li>


Longer lists are more useful with subheaders/dividers - a company directory, for instance, might show a nonclickable list item labeled "A" at the start of all of the "A" names, etc. Add a li item with data-role="list-divider" to add a divider item to your list:

list divider items

Open WidgetsUI/Demos/lists/dividers.html in a mobile browser and in a file editor to view the code:

<ul data-role="listview">
	<li data-role="list-divider">About Us</li>
	<li><a href="#about">General</a></li>
	<li><a href="#proprietors">Proprietors</a></li>
	<li><a href="#history">History</a></li>
	<li data-role="list-divider">Contact Info</li>
	<li><a href="#contact">Contact</a></li>
	<li><a href="#directions">Directions</a></li>

Search Filters for Lists

A great way to offer users easy access to longer lists is with jQuery Mobile's built-in list search filter. Simply add the data-filter="true" attribute to the list ul, and voila: jQuery Mobile filters the list to match the user's typing:

list filtering

Open WidgetsUI/Demos/lists/filter.html in a mobile browser and in a file editor to view the code:

<ul data-role="listview" data-filter="true">
	<li><a href="#book"><em>Cry, the Beloved Country</em>, Alan Paton</a></li>
	<li><a href="#book"><em>The Kite Runner</em>, Khaled Hosseini</a></li>
	<li><a href="#book"><em>The Time Traveler's Wife</em>, Audrey Niffenegger</a></li>
	<li><a href="#book"><em>Things Fall Apart</em>, Chinua Achebe</a></li>
	<li><a href="#book"><em>The Trojan Women</em>, Euripides</a></li>
	<li><a href="#book"><em>Twelfth Night</em>, William Shakespeare</a></li>

The filter works on ordered (ol) lists, too.

Note that we've added a custom CSS rule in the head of the document - setting white-space: normal for a tags inside of li tags forces the text to wrap rather than being cut off.

Further Reading on Lists

There's even more you can do with lists: formatting text, adding list bubbles (to display, for example, a count of comments for each blog post in a list), controlling icons and thumbnail images, and more. See the jQuery Mobile docs for more information.