Skip to content
Tutorials Center
My learning

Topics

Lesson 40 of 56 ยท Plugins and Utilities

jQuery Mobile: Overview and Why It Faded

Understand jQuery Mobile: the single-page model, data-role attributes, how to load it, a small multi-page example, and why modern projects use responsive CSS instead.

You may meet jQuery Mobile in old company apps, in books and in search results. It was a framework from the jQuery project, released in the early 2010s, that turned plain HTML into a touch-friendly mobile site with buttons, lists, form controls and page transitions, using data-* attributes instead of JavaScript. When phones had small, inconsistent browsers, that was a big deal.

Today the project is retired and you should not start new work with it. This lesson is still worth reading because the ideas (a page model, declarative markup, progressive enhancement) are still around, and because you may have to maintain something built with it. We cover how it works, show a runnable demo, explain why it faded, and list what to use now.

What jQuery Mobile gave you

  • A page model: one HTML file holds several "pages", and the framework navigates between them with animated transitions, using AJAX to load further files.
  • Declarative widgets: you write data-role="button" or data-role="listview" and the framework enhances the markup after the page loads.
  • A theme system with swatches (data-theme="a", "b") and the ThemeRoller for Mobile.
  • Touch events: tap, taphold, swipe, swipeleft, swiperight, scrollstart, scrollstop, orientationchange, and virtual mouse events.
  • Form enhancements: sliders, flip switches, styled selects, collapsible blocks and grids.

It was built to be compatible with jQuery 1.x and 2.x. The last release, 1.4.5, is from 2014, and it does not work with jQuery 3 without patching. That alone makes it a poor fit for anything new.

Loading it

jQuery Mobile needs jQuery first, its own stylesheet and then its script. The viewport meta tag is essential:

HTML
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
<script src="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>

Note the old jQuery version: this is the main compatibility rule. Mixing jQuery Mobile with jQuery 3.x raises errors in older code paths.

The page model and data-role

Every screen is an element with data-role="page". Inside it, three roles describe the standard layout: header, content (also written role="main" with the ui-content class) and footer.

HTML
<div data-role="page" id="home">
  <div data-role="header"><h1>Home</h1></div>
  <div role="main" class="ui-content">
    <a href="#about" class="ui-btn">About</a>
  </div>
  <div data-role="footer"><h4>My app</h4></div>
</div>
<div data-role="page" id="about">...</div>

A link to #about shows the second page with a slide animation, without a reload. A link to another file (about.html) is fetched with AJAX and its data-role="page" element is inserted into the DOM. Useful attributes:

Attribute Effect
data-transition="slide" (fade, pop, flip, none) page transition
data-rel="back" acts as the Back button
data-ajax="false" load the link as a normal page request
data-role="button" / class ui-btn style a link as a button
data-role="listview" enhance a <ul> into a list with arrows
data-inset="true", data-filter="true" rounded list, built-in search box
data-role="collapsible" expand/collapse block
data-theme="a" pick a swatch

A runnable demo

Two pages and a listview

The framework hides every page except the active one, gives the list its mobile styling, and adds the filter box because of data-filter="true". The mobileinit handler runs before the framework starts, which is where you set $.mobile defaults.

Events you will see in old code

  • mobileinit: set global options. It must be bound before the jQuery Mobile script loads.
  • pagecreate, pageinit (older), pagebeforeshow, pageshow, pagehide: the page life cycle. Because pages are loaded with AJAX, $(document).ready fires only once, so initialisation code belongs in pagecreate or pageshow.
  • tap, taphold, swipeleft, swiperight: gestures. swipe handlers on a whole page often conflict with scrolling.
  • $.mobile.changePage() (deprecated) and $(":mobile-pagecontainer").pagecontainer("change", "#about"): navigate from code.

If you maintain old code and see weird "my script only runs on the first page" problems, the cause is almost always $(document).ready combined with AJAX navigation.

Why it faded

Several things happened at once:

  1. Responsive design won. CSS media queries, flexbox and grid let one stylesheet adapt to any screen, and frameworks such as Bootstrap shipped mobile-first CSS without hijacking navigation.
  2. Browsers caught up. Touch events, viewport, CSS transitions, the History API and the click event with no 300 ms delay made the framework's compatibility layers unnecessary.
  3. Single-page frameworks (React, Vue, Angular) took over client-side routing and component structure, with better performance than DOM enhancement after load.
  4. It was heavy. Enhancing a large DOM at load time was slow on the low-end phones it targeted, and its link-hijacking and data-* magic made debugging and SEO harder.
  5. Maintenance stopped. There has been no stable release since 1.4.5, and the jQuery team lists the project as no longer maintained.

What to use instead

You wanted Use now
Responsive layout and components Bootstrap, Tailwind or plain CSS grid
Page transitions the View Transitions API, or a router in a framework
Touch gestures Pointer Events, or a small library such as Hammer.js successors
A mobile app shell a Progressive Web App, React, Vue, or a native/hybrid toolkit
Page navigation without reload a router from your framework, or plain links with fast servers

If you must keep an old jQuery Mobile app alive, pin the exact versions (jQuery 1.x/2.x with jQuery Mobile 1.4.5), stop upgrading jQuery on that page, and plan a rebuild one page at a time. For help moving off old jQuery generally, see What Changed in jQuery 3 and jQuery to Modern JavaScript.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does data-role="page" mark in jQuery Mobile?

    Each element with data-role="page" is a screen. The framework displays the active one and animates between them.
  2. 2. Why does $(document).ready often fail to initialise later pages in a jQuery Mobile app?

    The document is never reloaded when navigating, so initialisation belongs in page life-cycle events.
  3. 3. Which version pairing is the supported one for jQuery Mobile 1.4.5?

    jQuery Mobile 1.4.5 was released in 2014 and targets jQuery 1.x and 2.x.
  4. 4. Which is the main reason responsive CSS replaced jQuery Mobile?

    Mobile-first CSS and modern browsers made DOM enhancement and link hijacking unnecessary.

Summary

  • jQuery Mobile enhanced data-role markup into touch-friendly pages with transitions, lists and form widgets.
  • It depends on old jQuery (1.x/2.x), uses AJAX navigation, and needs pagecreate/pageshow instead of ready.
  • It faded because of responsive CSS, better browsers, single-page frameworks, weight, and the end of maintenance.
  • For new work choose responsive CSS, Bootstrap or a modern framework; for old apps, pin versions and migrate gradually.

Next: a very popular table plugin in DataTables with jQuery.