Help me improve this page!

jQuery Upgrade Guide for Incompatible Changes

This document is an attempt to list all breaking changes between jQuery versions so that it's easy for you to search through your code and upgrade it to be compatible with the newer versions.

I'm surprised why the jQuery team hasn't themselves produced such an overview - and I couldn't find anybody else having made it either, so here it is. I will much appreciate any help and input you can give to make this better and even more accurate.

From 1.5 to 1.6

References: [1] [2]



Previous version New Version Search for this regular expression in your code
.data() now creates camel-case named objects when the attribute contains a hyphen (-) data-max-value="15" becomes {max-value: 15}and must be read using .date('max-value') data-max-value="15" becomes {maxValue: 15}and must be read using .date('maxValue') \.data\(['"][^'"]*-
.attr() can no longer be used to read properties like readonly="readonly",disabled="disabled" , checked="checked", selected="selected", and multiple="multiple" .attr('checked') returns true if checkbox is checked.

.attr('checked') returns empty string or 'checked' because it returns the actual attribute value from the HTML element and not the propertychecked from the DOM.

Need to use .prop('checked') or
.is(':checked'). Can also use the direct property in DOM: $('selector')[0].checked

For writing you should do .prop('checked', true) and .prop('checked', false)

Click here for running example.


More loose:


From 1.6 to 1.7

References: [1]

Change Previous version New Version
event.layerX and event.layerY properties removed   On platforms that still support these properties, they are available through event.originalEvent.layerX and event.originalEvent.layerY.
jQuery.isNaN() removed   Use jQuery.isNumeric() instead.
jQuery.event.proxy() removed   Use jQuery.proxy instead.
From now on you should use .on() and .off() instead of .bind() and .unbind() as they are the new preferred methods - but .bind() and .unbind() still works and their deprecation has not been announced.    

From 1.7 to 1.8

References: [1]

Change Previous version New Version
.data('events') removed  

Use $._data(element, 'events') instead.

Note that this is not a supported public interface; the actual data structures may change incompatibly from version to version.

Deferred.isResolved() and Deferred.isRejected() removed   Use Deferred.state() instead.
.closest() no longer takes an Array as the first argument .closest(Array) returned an Array. .closest(Array)can no longer be used. But other regular functionality of .closest() still works. See documentation.
$.curCSS removed   Use jQuery.css() instead.
$.attrFn removed   No replacement - do something else..


From 1.8 to 1.9

References: [1] [Migration plug-in]

Change Previous version New Version
.toggle(function, function, ...) to run the given set of functions when the element is clicked can no longer be used. But the method is still used to change the visibility of an element.

.toggle(function, function, function) was valid.

No longer possible.

Click here for the only proper use of .toggle()

jQuery.browser() removed  

If needed use a library such as Modernizr instead.

.live() removed  

Use .on() instead. But note that it attaches the event handlers to the matched elements at the time it is executed - instead of attaching the event handlers to the document element which caused the events to be also executed on future elements matching the selector. So - if you are not dynamically adding elements that are matching the given selector (or those dynamic elements don't need these event handlers attached) you don't have to worry about this distinction.

To exactly match $("").live("click", fn), for example, you can write $(document).on("click", "", fn).

.die() removed  

Use .off() instead. See notes above for .live()

To exactly match $("").live("click", fn), for example, you can write $(document).on("click", "", fn).

jQuery.sub() removed   No replacement - do something else.
.add() return values might have changed .add() would not sort nodes in document order if either the context or the input set started with a disconnected node (not in a document). Now, nodes are always returned in document order and disconnected nodes are placed at the end of the set.
.andSelf() deprecated although still works   Use .addBack() instead. It is an easy search-and-replace to change this - therefore I mentioned it here even though it's not actually a breaking change yet.
.after(), .before(), and .replaceWith() return values might have changed Methods would attempt to add or change nodes in the current jQuery set if the first node in the set was not connected to a document, and in those cases return a new jQuery set rather than the original set.

Methods now correctly always return the original unmodified set when used with disconnected nodes/elements.

See also official upgrade guide.

.appendTo(), .insertBefore(), .insertAfter(), and .replaceAll() return values might have changed Methods would return the old set only if there was a single target element.

Methods always return a new set, making them consistently usable with chaining and the .end() method.

See also official upgrade guide.

AJAX events (ajaxStart, ajaxStop, ajaxSend, ajaxComplete, ajaxError, and ajaxSuccess) should be attached to document You could trigger these events on any element.

Now they are only triggered on the document element.

For example, if the code currently looks like this:

$('#status').ajaxStart(function() { $(this).text('Ajax started'); });

Change it to this so that it listens on the document element instead:

$(document).ajaxStart(function() { $('#status').text('Ajax started'); });

jQuery(htmlString) behaviour change The argument in jQuery(myString) would be considered an HTML string (as opposed to a selector string) if it had HTML tags anywhere within the string.

Now the string is only considered to be an HTML string if it starts with a less-than character (<). Otherwise it will be interpreted as a selector.

To parse HTML strings you should now use .parseHTML()

When returning new sets of nodes connected nodes are now always placed at the beginning of the set in document order, and disconnected nodes are placed behind them.    
HTML-accepting methods containing Javascript Any HTML-accepting method (e.g., $(), .append(), or .wrap()) executed any scripts in the HTML and removed them from the document to prevent them from being executed again. This still broke in situations where a script might be removed and reinserted into the document using methods such as .wrap().

Scripts inserted into a document are executed, but left in the document and tagged as already executed so they won't be executed again even if they are removed and reinserted.

It is very poor practice to mix executable Javascript into HTML markup though.

Pseudo-event 'hover' is removed .on('hover', function(){});

.on('mouseenter mouseleave', function(){});

'hover' was just a synonym for 'mouseenter mouseleave'.

The pass argument in .attr(elem, name, value, pass) is no longer supported    

Other minor behaviour changes:


From 1.9 to 1.10

References: [1]

Yeah - no breaking changes!

From 1.x to 2.x

References: [1]

Yeah - no breaking changes - except that IE 6, 7, 8 is no longer supported!