This guide will assist in upgrading from jQuery Mobile 1.4.x to jQuery Mobile 1.5.x. All changes are listed below, organized by component, along with how to upgrade your code to work with jQuery Mobile 1.5.

1.5 maintains full compatibility with the 1.4 API by default.
This is accomplished by rebuilding the 1.4 API on top of the 1.5 API. The
default behavior for all 1.5 releases will be to simultaneously use the 1.4
and 1.5 APIs, deferring to the 1.4 API if there is a conflict. If you would like
to load just the 1.5 API without the 1.4 API, you can set the $.mobileBackcompat
flag to false.

1

2

3

<scriptsrc="jquery.js"></script>

<script>$.mobileBackCompat = false;</script>

<scriptsrc="jquery-mobile.js"></script>

This will prevent the initialization of the back-compat layer, allowing you to
use the 1.5 API in cases where there is a conflict with the 1.4 API.

The API redesigns deprecate a lot of functionality, which will be removed in 1.6.
You don't have to wait for the 1.6 release in order to find out if your code
will work when the 1.4 APIs are removed. You can use the $.mobileBackCompat flag
to test this with any 1.5 release.

In addition to just disabling the backcompat layer all of the backcompat code is isolated in backcompat modules for each component and can be excluded by doing a custom build.

If you find a regression from the 1.4 API, please report it in the
bug tracker. Even though the 1.4 API is
deprecated, it's important for 1.5 releases not to regress so that users are
encouraged to upgrade even if they're not ready to use the new APIs.

Independent of changes to specific components, this release removes support for IE8 and Android 2.3, improves support for AMD, and improves the modularity of the library. The minimal jQuery version supported is now 1.9.x.

It is important to note that no workarounds for IE8 or Android 2.3 were removed in this release however these browsers are no longer tested other than to ensure the library parses. No new workarounds or bug fixes will be added for these browsers.

The following changes from jQuery UI 1.12 also affect jQuery Mobile as these components are a part of jQuery Mobile

(#7053) jQuery UI used to hardcode classes like .ui-corner-all in widgets. We removed the hardcoding and added the ability to customize the style-related classes based on the functional classes. For the dialog, droppable and tooltip widgets, we replaced options that were doing just that.

This also replaces the wrapperClass option in any widgets which had it. You can now use the classes option in the same way.

jQuery Mobile had many boolean options on its widgets that simply toggled a class on the widget to change the display. corners and shadow are great examples of this.

Because of the changes to our markup structure, it is now very easy to do this in your markup or by using the classes option. Thus, all of these options are now deprecated. To toggle these effects simply use the classes option as demonstrated above.

In 1.4 we switched from using a span element for icons to using a :before or :after pseudo element so that icons could be added with just a class. We were very excited about this at the time but have since realized this causes many problems too. It is less performant, creates an awkward api, can't be target with JavaScript. So after careful consideration with the jQuery UI team, the Mobile team, a lot of reasearch, and the creation of a whole new project (The CSS Chassis Project), we have decided it is best to switch back to using spans for icons so that we dont have to worry about this any more :-). We understand the pain this causes in the upgrade process and apologize, but we felt this was the best approach moving forward for jQuery Mobile.

In addition to the change back to spans we have rethought the way icons are positioned in an effort to both simplify our markup and css and at the same time make it more flexible. Icons are also now no longer absolutely positioned. Icons are now placed inline in the text content of whereever you would like them to be. This means you can now add as many icons to an element as you want and place them anywhere you would like. This makes icons much more flexible in your designs.

To help you with some common positions that are a little more complicated than just inline we have also added a few icon helper classes. ui-widget-icon-block will make your icon centered and display block. This is useful for top an bottom icons. Since icons are now inline elements by default they will right, center, or left justify with your text content. To help with positioning an icon all the way left or right independant of the text we have also added the classes ui-widget-icon-floatbegining and ui-widget-icon-floatend.

You can see examples of the new and old markup for icons in the Button section below.

In 1.4 auto-enhancment was handled by a combination of a widget registry in the same file as the page widget, a custom method in the helpers module, and an extension to the base widget factory.

We did a complete rethink of how auto-enhancment with jQuery should work and the new module is FAST. Depending on the number of elements needing methods called its actually faster than directly calling each
as the selection from the DOM is done only once per call. To make this possible and to expand past just widgets we have decided to make two major changes.

First we have deprecated the ability to set a custom name space for data-attributes. jQuery mobile will now always use the ui name space on all data-attributes.

Old API:

1

<divdata-role="page">

New API:

1

<divdata-ui-role="page">

The second change is all widgets roles will now follow the pattern data-ui-role="method" where method can be any valid jQuery method. So things like all inputs with a type of text being automatically enhanced will no longer happen. You will need to add data-ui-role="textinput" to the input.

In 1.4 and prior versions to promote progressive enhancement we had certain input types "auto-degrade". A search to a text and a range to a number for example. The reason for this was to avoid the native html 5 control rendering so we can use the custom widget. There was one major problem with this which was that you can't just change the type attribute on an input in Internet Explorer. This means we needed to actually create a new element and replace it. This is a very destructive process because any data which was previously set or event listeners will be lost as the element has been replaced.

Starting in jQuery Mobile 1.5 this behivor is deprecated. You will now need to use the proper input type for the widget you are initalizeing. The only widgets which are affected by this change are textinput with a type of search and slider.

In 1.4 $.mobile.keepNative allowed you to set a selector which you could add to avoid auto-enhancment. Now that all auto initialization is explicit this option is no longer needed and will be deprecated. There is no replacment for this option other than to just not add a data-ui-role to elements you don't want enhanced.

As part of our efforts to share code and merge with jQuery UI the Button widget is now shared by jQuery UI and Mobile and the base widget lives in the jQuery UI Repository. jQuery Mobile adds a layer on top of the jQuery UI Button adding additional functionality and implementing the 1.4 API. As part of this all of the ui-btn* classes have been changed to ui-button* for consistency. You will see this change reflected in all of the examples below.

Mentntioned in the icon section above icons are no longer absolutely positioned this means that in a full width button the icon will sit next to the text instead of flush left or right by default. To acheive a flush left or right icon simply add ui-widget-icon-floatend or ui-widget-icon-floatend to the icon using the classes option.