How to build a list-based app with jQuery Mobile

Published by | Saturday, August 11th, 2012

In this tutorial, I’ll show you how easy it is to create a list-based app with the jQuery Mobile framework in just a few minutes, and hopefully encourage you to give it a try.

jQuery Mobile is an excellent way to create web applications for mobile devices, but it suffers from a bit of a PR problem. When I first learned about the framework, I put it on my list of technologies I should investigate, but I figured that because it’s based on jQuery, I’d have to be a jQuery expert before I could use jQuery Mobile. I found that nothing could be further from the truth.

All that is needed to use the framework is some basic HTML knowledge. In addition, because the framework is built on top of jQuery, you get all of the functionality of jQuery in a way that is easily accessible.

What is the jQuery Mobile Framework?

jQuery Mobile is a framework for developing web applications for touch-optimized devices. A framework gives you a structure or methodology for doing something—in this case, for developing web applications.

Although you can use HTML and JavaScript to develop mobile-optimized sites, you’ll quickly run into some serious problems: Different devices and browsers treat your code differently, so you have to write a bunch of JavaScript to overcome device orientation and other issues. You also have to create styles for different items like list views, dialogs, toolbars, and so on. jQuery Mobile does all of that for you. It creates a code base that handles differences between devices with support for a large range of devices.

A quick example: a list-based app

So let’s get started with a quick example. I’m going to build a list-based app that will show a selection of photos. I’ll start with some super basic starter code for a normal page:

<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8" />

This is pretty standard HTML code. Let’s add a header section to our body:

<div id="header">
  <h1>My Photos</h1>

And of course, we’ll need a footer. I’m going to add a navigation with fake links to some other potential pages:

      <li><a href="#">Home</a></li>
      <li><a href="#">Photos</a></li>
      <li><a href="#">Info</a></li>

Now we need some content. To keep things short for this article, I’m going to add just two photos to the mix, but you can add as many as you like. Since this is a list-based app, I’ll put the photos inside a list.

      <a href="#">
      <h1>Miniature Doberman Pincher</h1>
      <img src="images/doggie_tn.jpg" alt="Min Pin" />
      <p>This is what happens when a
      friend brings a dog to the studio.</p>
      <a href="#">
      <h1>Gummy Bears</h1>
      <img src="images/gummies_tn.jpg" alt="Gummy Bears" />
      <p>Three different poster boards...mirror for reflection,
      black for background white for highlights</p>

We encased our list inside an <article> tag, and inside each list item we have a link, which will eventually take us to a large version of our image and then a headline, a thumbnail, and a short description.

HTML site before adding jQuery Mobile.

So far this is just a regular HTML page. Let's now add the jQuery library. Since the app is based on jQuery Mobile, we’ll need to add that library too, as well as some styles that the library needs. The easiest and recommended way to do this is to copy three lines of code from the jQuery Mobile Download page.

<link rel="stylesheet" href="" />
<script src=""></script>
<script src=""></script>

You can put this code in between the <head> tags in your document (not to be confused with the <header> tags). These three lines tie in the CSS, the jQuery Mobile library, and the jQuery library. If you preview the page now, you’ll be able to see some slight differences in the look of the page. The background will be gray, and the fonts will be different. Not too exciting, but it means the library is already working. Here comes the exciting part.

Formatting a list view

Modifying our list so that it gets mobile device functionality is super easy: we just need to modify our <ul> tag to read like this:

<ul data-role="listview">

Your page should look something like this:

Mobile page with a formatted list view made using jQuery Mobile.

From someone who has written the CSS necessary to make a list look like this photo, this library has already saved me a ton of time.

jQuery Mobile uses the data-role tag to assign roles to regular HTML elements on a page. The reason it can do this is because of a really cool feature in HTML5: the ability to add a data-whatever attribute to any tag and store information that you can use to style elements and create interactivity.

Making the list searchable

For an even more impressive example of what the library can do, try modifying your <ul> tag like this to make your list searchable:

<ul data-role="listview"  data-filter="true">

You should see a search box appear on top of your list. Start typing the word gummy into the search box and you’ll see that the list only displays one item (the one with the text gummy bears in the title). jQuery Mobile does all of that for you automatically.

jQuery Mobile list view screen with a searchable list field.

Formatting Headers and Footers

Let’s add some of the other tags that tell jQuery Mobile to format things in a more mobile-friendly fashion.

Content in jQuery Mobile is normally placed inside a data-role="content" section. We can add that to our <article> tag.

<article data-role="content">

Let’s also fix up the header. We’ll use data-role="header" in the <header> tag.

<header data-role="header">

Next, we'll fix the footer. Modify the <footer> tag like this:

<footer data-role="footer" data-position="fixed">

Not perfect yet, but this shows a big improvement. Our header looks like a mobile device header, our search bar and list are nicely formatted. Notice that I’ve added the data-position=“fixed” attribute to the footer. That places the footer at the bottom on mobile devices. Our footer looks good, but the links could look better. Let’s make them look like buttons on a mobile device.

Modify the <nav> tag in the footer to read like this:

  <nav data-role="navbar">

jQuery Mobile list view page with search field and formatted headers and footers.

Our application is looking great; however, we could really use some icons on the navbar links. jQuery Mobile lets us easily add icons by adding a data-icon attribute to links by modifying our list items like this:

<li><a href="home" data-icon="home">Home</a></li>
<li><a href="Photos" data-icon="grid">Photos</a></li>
<li><a href="Info" data-icon="info">Info</a></li>

jQuery Mobile list page with added icons on the header and footer.

With just a few attribute tags, we’ve added mobile functionality to a page that would have taken hours to write and style otherwise.

Multiple Pages

So far, we’ve built a single page app. If you want to create an app with multiple pages, you have to wrap each page with a tag, use the data-role=“page”, and add an id so that we can link to that page.

Before the <header> tag add the following line of code:

<div data-role="page" id="photos">

And don’t forget to close it underneath the <footer> tag:

</div><!-- Page Photos -->

I always add a comment because when working on a large jQuery Mobile project, I use a lot of <div> tags and it’s nice to know what the closing tags belong to.

Now that we have a page, let’s add a page for each of our photos:

<div data-role="page" id="dog">
  <header data-role="header">
    <h1>Min Pin</h1>
    <a href="#photos" data-icon="grid" data-iconpos="notext">Photos</a>
  <img src="images/doggie.jpg" class="fullscreen" alt="Min Pin" />
</div><!-- Page Dog -->

<div data-role="page" id="gummies">
  <header data-role="header">
    <h1>Gummy Bears</h1>
    <a href="#photos" data-icon="grid" data-iconpos="notext">Photos</a>
  <img src="images/gummies.jpg" class="fullscreen" alt="Gummy Bears" />
</div><!-- Page Gummy Bears --> 

The code is pretty similar to the photo list page with some important changes. First, there is no footer on these pages, since they will just display the photos. Second, we added a header with a link back to the home page—note the data-iconpos attribute on that link. You can control the position of the icons on buttons with this attribute, or you can turn the buttons off altogether using notext as a value. The button on the header is linked to our photos page.

I’ve also added a class of fullscreen to my photos. This is not a jQuery Mobile class, but something I’ve added manually because I want the photos to display full screen, so eventually I’ll add some CSS for that further down. First though, we need to link the items in our list view page to our new pages. Modify the list like this:

  <a href="#dog">
  <h1>Miniature Doberman Pincher</h1>
  <img src="images/doggie_tn.jpg" alt="Min Pin" />
  <p>This is what happens when a
  friend brings a dog to the studio.</p>
  <a href="#gummies">
  <h1>Gummy Bears</h1>
  <img src="images/gummies_tn.jpg" alt="Gummy Bears" />
  <p>Three different poster boards...mirror for reflection,
  black for background white for highlights</p>

Our app is almost done. Now, right before the closing </head> tag at the top of our document, let’s add the style to make sure our photos fit.

  img.fullscreen {
    max-height: 100%;
    max-width: 100%;

jQuery Mobile list app modified to show fullscreen images.

Our app is now ready. You can take a look at the finished jQuery Mobile app here.


Interested in more?
• All web + interactive courses on
• All courses from Ray Villalobos on

Suggested courses to watch next:
• jQuery Mobile Web Applications
• jQuery Mobile Essential Training
• Mobile Web Design & Development Fundamentals
• HTML5: Structure, Syntax, and Semantics

Share this:Share on Facebook2Tweet about this on Twitter12Share on Google+0Pin on Pinterest0Share on LinkedIn0 - start learning today

Tags: , ,

3 Responses to “How to build a list-based app with jQuery Mobile”

  1. altair says:

    Sir hats-off to you for your knowledge.

  2. Tim says:

    I previewed the class but I really appreciate this shorter bite-sized primer. Thank you Ray.

  3. raju says:

    img not set full screen why

Leave a Reply