CINXE.COM

<!doctype html> <html class="no-js" lang="en-US"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>jQuery Core 3.0 Upgrade Guide | jQuery</title> <meta name="author" content="OpenJS Foundation - openjsf.org"> <meta name="description" content="jQuery: The Write Less, Do More, JavaScript Library"> <meta name="viewport" content="width=device-width"> <link rel="shortcut icon" href="https://jquery.com/wp-content/themes/jquery.com/i/favicon.ico"> <link rel="stylesheet" href="https://jquery.com/wp-content/themes/jquery/lib/typesense-minibar/typesense-minibar.css?v=c5fa9b9a"> <link rel="stylesheet" href="https://jquery.com/wp-content/themes/jquery/css/base.css?v=9fa813cf"> <link rel="stylesheet" href="https://jquery.com/wp-content/themes/jquery.com/style.css?v=828507a9"> <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script> <script src="https://jquery.com/wp-content/themes/jquery/js/main.js?v=10baaffd"></script> <script defer type="module" src="https://jquery.com/wp-content/themes/jquery/lib/typesense-minibar/typesense-minibar.js?v=830f1ee1"></script> <meta name='robots' content='max-image-preview:large' /> <link rel="https://api.w.org/" href="https://jquery.com/wp-json/" /><link rel="alternate" title="JSON" type="application/json" href="https://jquery.com/wp-json/wp/v2/pages/16" /><meta name="generator" content="WordPress 6.7.2" /> <link rel="canonical" href="https://jquery.com/upgrade-guide/3.0/" /> <link rel="alternate" title="oEmbed (JSON)" type="application/json+oembed" href="https://jquery.com/wp-json/oembed/1.0/embed?url=https%3A%2F%2Fjquery.com%2Fupgrade-guide%2F3.0%2F" /> <link rel="alternate" title="oEmbed (XML)" type="text/xml+oembed" href="https://jquery.com/wp-json/oembed/1.0/embed?url=https%3A%2F%2Fjquery.com%2Fupgrade-guide%2F3.0%2F&format=xml" /> <link rel="me" href="https://social.lfx.dev/@jquery"> </head> <body class="jquery page-template-default page page-id-16 page-child parent-pageid-12 page-slug-30 single-author singular"> <header> <section id="global-nav"> <nav> <div class="constrain"> <ul class="projects"> <li class="project jquery"><a href="https://jquery.com/" title="jQuery">jQuery</a></li> <li class="project jquery-ui"><a href="https://jqueryui.com/" title="jQuery UI">jQuery UI</a></li> <li class="project jquery-mobile"><a href="https://jquerymobile.com/" title="jQuery Mobile">jQuery Mobile</a></li> <li class="project sizzlejs"><a href="https://sizzlejs.com/" title="Sizzle">Sizzle</a></li> <li class="project qunitjs"><a href="https://qunitjs.com/" title="QUnit">QUnit</a></li> </ul> <ul class="links"> <li><a href="https://plugins.jquery.com/">Plugins</a></li> <li class="dropdown"><a href="https://contribute.jquery.org/">Contribute</a> <ul> <li><a href="https://cla.openjsf.org/">CLA</a></li> <li><a href="https://contribute.jquery.org/style-guide/">Style Guides</a></li> <li><a href="https://contribute.jquery.org/triage/">Bug Triage</a></li> <li><a href="https://contribute.jquery.org/code/">Code</a></li> <li><a href="https://contribute.jquery.org/documentation/">Documentation</a></li> <li><a href="https://contribute.jquery.org/web-sites/">Web Sites</a></li> </ul> </li> <li class="dropdown"><a href="https://events.jquery.org/">Events</a> <ul class="wide"> </ul> </li> <li class="dropdown"><a href="https://jquery.com/support/">Support</a> <ul> <li><a href="https://learn.jquery.com/">Learning Center</a></li> <li><a href="https://jquery.com/support/">Chat</a></li> <li><a href="https://stackoverflow.com/tags/jquery/info">Stack Overflow</a></li> <li><a href="https://contribute.jquery.org/bug-reports/">Report a bug</a></li> </ul> </li> <li class="dropdown"><a href="https://openjsf.org/">OpenJS Foundation</a> <ul> <li><a href="https://openjsf.org/join">Join</a></li> <li><a href="https://openjsf.org/members">Members</a></li> <li><a href="https://jquery.com/team">jQuery Team</a></li> <li><a href="https://openjsf.org/governance">Governance</a></li> <li><a href="https://code-of-conduct.openjsf.org/">Conduct</a></li> <li><a href="https://openjsf.org/projects">Projects</a></li> </ul> </li> </ul> </div> </nav> </section> </header> <div id="container"> <div id="logo-events" class="constrain clearfix"> <h2 class="logo"><a href="/" title="jQuery">jQuery</a></h2> <aside id="broadcast"></aside> </div> <nav id="main" class="constrain clearfix"> <div class="menu-top-container"> <button hidden id="menu-trigger" class="button menu-trigger" aria-expanded="false" aria-haspopup="menu">Navigation</button> <ul id="menu-top" class="menu" role="menu" aria-labelledby="menu-trigger"> <li class="menu-item"><a href="https://jquery.com/download/">Download</a></li> <li class="menu-item"><a href="https://api.jquery.com/">API Documentation</a></li> <li class="menu-item"><a href="https://blog.jquery.com/">Blog</a></li> <li class="menu-item"><a href="https://plugins.jquery.com/">Plugins</a></li> <li class="menu-item"><a href="https://jquery.com/browser-support/">Browser Support</a></li> <li class="menu-item"><a href="https://jquery.com/support/">Version Support</a></li> </ul> </div> <typesense-minibar data-origin="https://typesense.jquery.com" data-collection="jquery_com" data-key="Zh8mMgohXECel9wjPwqT7lekLSG3OCgz" data-foot="true" data-group="true" > <form role="search" class="searchform" action="https://jquery.com/" method="get"> <input type="search" name="s" aria-label="Search jQuery" value="" placeholder="Search" autocomplete="off"> <button type="submit" class="visuallyhidden"></button> </form> </typesense-minibar> </nav> <div id="content-wrapper" class="clearfix row"> <div class="content-full twelve columns"> <div id="content"> <h1 class="entry-title">jQuery Core 3.0 Upgrade Guide</h1> <hr> <ul> <li><a href="#overview">Overview</a></li> <li><a href="#browser-support">Browser Support</a></li> <li><a href="#jquery-migrate-plugin">jQuery Migrate Plugin</a></li> <li><a href="#summary-of-important-changes">Summary of Important Changes</a><ul> <li><a href="#ajax">Ajax</a><ul> <li><a href="#breaking-change-special-case-deferred-methods-removed-from-jquery-ajax">Breaking change: Special-case Deferred methods removed from jQuery.ajax</a></li> <li><a href="#breaking-change-cross-domain-script-requests-must-be-declared">Breaking change: Cross-domain script requests must be declared</a></li> <li><a href="#breaking-change-hash-in-a-url-is-preserved-in-a-jquery-ajax-call">Breaking change: Hash in a URL is preserved in a jQuery.ajax() call</a></li> <li><a href="#feature-new-signature-for-jquery-get-and-jquery-post">Feature: New signature for jQuery.get() AND jQuery.post()</a></li> </ul> </li> <li><a href="#attributes">Attributes</a><ul> <li><a href="#breaking-change-removeattr-no-longer-sets-properties-to-false">Breaking change: .removeAttr() no longer sets properties to false</a></li> <li><a href="#breaking-change-select-multiple-with-nothing-selected-returns-an-empty-array">Breaking change: select-multiple with nothing selected returns an empty array</a></li> <li><a href="#feature-svg-documents-support-class-operations">Feature: SVG documents support class operations</a></li> <li><a href="#deprecated-toggleclass-with-no-arguments-and-toggleclass-boolean">Deprecated: .toggleClass() with no arguments and .toggleClass( Boolean )</a></li> </ul> </li> <li><a href="#callbacks">Callbacks</a><ul> <li><a href="#feature-locking-a-callback-prevents-only-future-list-execution">Feature: Locking a Callback prevents only future list execution</a></li> </ul> </li> <li><a href="#core">Core</a><ul> <li><a href="#breaking-change-jquery-3-0-runs-in-strict-mode">Breaking change: jQuery 3.0 runs in Strict Mode</a></li> <li><a href="#breaking-change-document-ready-handlers-are-now-asynchronous">Breaking change: document-ready handlers are now asynchronous</a></li> <li><a href="#breaking-change-jquery-isnumeric-and-custom-tostring">Breaking change: jQuery.isNumeric() and custom .toString()</a></li> <li><a href="#breaking-change-deprecated-context-and-selector-properties-removed">Breaking change: Deprecated .context and .selector properties removed</a></li> <li><a href="#breaking-change-deprecated-size-removed">Breaking change: Deprecated .size() removed</a></li> <li><a href="#breaking-change-undocumented-internal-methods-no-longer-exposed">Breaking change: Undocumented internal methods no longer exposed</a></li> <li><a href="#breaking-change-return-values-on-empty-sets-are-undefined">Breaking change: Return values on empty sets are undefined</a></li> <li><a href="#feature-for-of-loops-can-be-used-on-jquery-collections">Feature: for...of loops can be used on jQuery collections</a></li> <li><a href="#feature-jquery-ready-promise-is-formally-supported">Feature: jQuery.ready promise is formally supported</a></li> <li><a href="#deprecated-jquery-unique-renamed-to-jquery-uniquesort">Deprecated: jQuery.unique(), renamed to jQuery.uniqueSort()</a></li> <li><a href="#deprecated-jquery-parsejson">Deprecated: jQuery.parseJSON()</a></li> <li><a href="#deprecated-document-ready-handlers-other-than-jquery-function">Deprecated: document-ready handlers other than jQuery(function)</a></li> </ul> </li> <li><a href="#data">Data</a><ul> <li><a href="#breaking-change-data-names-containing-dashes">Breaking change: .data() names containing dashes</a></li> </ul> </li> <li><a href="#deferred">Deferred</a><ul> <li><a href="#breaking-change-and-feature-jquery-deferred-is-now-promises-a-compatible">Breaking change and Feature: jQuery.Deferred is now Promises/A+ compatible</a><ul> <li><a href="#resolution">Resolution</a></li> <li><a href="#callback-exit">Callback exit</a></li> <li><a href="#callback-invocation">Callback invocation</a></li> <li><a href="#backwards-compatibility">Backwards compatibility</a></li> </ul> </li> <li><a href="#breaking-change-and-feature-jquery-when-arguments">Breaking change and Feature: jQuery.when() arguments</a></li> <li><a href="#breaking-change-jquery-when-progress-notifications">Breaking change: jQuery.when() progress notifications</a></li> </ul> </li> <li><a href="#dimensions">Dimensions</a><ul> <li><a href="#breaking-change-width-height-css-quot-width-quot-and-css-quot-height-quot-can-return-non-integer-values">Breaking change: .width(), .height(), .css("width"), and .css("height") can return non-integer values</a></li> <li><a href="#breaking-change-outerwidth-or-outerheight-on-window-includes-scrollbar-width-height">Breaking change: .outerWidth() or .outerHeight() on window includes scrollbar width/height</a></li> </ul> </li> <li><a href="#effects">Effects</a><ul> <li><a href="#breaking-change-show-hide-and-toggle-methods-now-respect-more-stylesheet-changes">Breaking change: .show(), .hide(), and .toggle() methods now respect more stylesheet changes</a></li> <li><a href="#feature-animations-now-use-requestanimationframe">Feature: Animations now use requestAnimationFrame</a></li> <li><a href="#deprecated-jquery-fx-interval">Deprecated: jQuery.fx.interval</a></li> <li><a href="#deprecated-additional-easing-function-parameters">Deprecated: Additional easing function parameters</a></li> </ul> </li> <li><a href="#event">Event</a><ul> <li><a href="#breaking-change-load-unload-and-error-removed">Breaking change: .load(), .unload(), and .error() removed</a></li> <li><a href="#breaking-change-on-quot-ready-quot-fn-removed">Breaking change: .on("ready", fn) removed</a></li> <li><a href="#breaking-change-event-pagex-and-event-pagey-normalization-removed">Breaking change: event.pageX and event.pageY normalization removed</a></li> <li><a href="#breaking-change-jquery-event-props-and-jquery-event-fixhooks-removed">Breaking change: jQuery.event.props and jQuery.event.fixHooks removed</a></li> <li><a href="#breaking-change-delegated-events-with-bad-selectors-throw-immediately">Breaking change: Delegated events with bad selectors throw immediately</a></li> <li><a href="#deprecated-bind-and-delegate">Deprecated: .bind() and .delegate()</a></li> </ul> </li> <li><a href="#manipulation">Manipulation</a><ul> <li><a href="#breaking-change-wrapall-function-only-calls-the-function-once">Breaking change: .wrapAll(function) only calls the function once</a></li> </ul> </li> <li><a href="#offset">Offset</a><ul> <li><a href="#breaking-change-invalid-input-to-the-offset-method">Breaking change: Invalid input to the .offset() method</a></li> </ul> </li> <li><a href="#selector">Selector</a><ul> <li><a href="#breaking-change-behavior-of-hidden-and-visible">Breaking change: Behavior of :hidden and :visible</a></li> <li><a href="#breaking-change-jquery-quot-quot-and-find-quot-quot-are-invalid-syntax">Breaking change: jQuery("#") and .find("#") are invalid syntax</a></li> <li><a href="#feature-new-method-jquery-escapeselector">Feature: New method jQuery.escapeSelector()</a></li> <li><a href="#deprecated-jquery-expr-quot-quot-and-jquery-expr-filters">Deprecated: jQuery.expr[":"] and jQuery.expr.filters</a></li> </ul> </li> <li><a href="#serialize">Serialize</a><ul> <li><a href="#breaking-change-jquery-param-no-longer-converts-20-to-a-plus-sign">Breaking change: jQuery.param() no longer converts %20 to a plus sign</a></li> </ul> </li> <li><a href="#traversing">Traversing</a><ul> <li><a href="#breaking-change-andself-removed-use-addback">Breaking change: .andSelf() removed, use .addBack()</a></li> </ul> </li> </ul> </li> </ul> <h2 class="toc-linked" id="overview"><a href="#overview" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Overview</h2><p>With the major version of 3.0, the jQuery Core team has taken the opportunity to make changes to clean up the API and fix bugs that may prove to be breaking changes for some code. This includes the removal of previously deprecated public APIs, changes to or removal of undocumented APIs, and changes to the documented or undocumented behavior of existing APIs for specific inputs.</p> <h2 class="toc-linked" id="browser-support"><a href="#browser-support" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Browser Support</h2><p>As of jQuery 3.0, the following browsers are supported:</p> <ul> <li>Internet Explorer: 9+</li> <li>Chrome, Edge, Firefox, Safari: Current and Current - 1</li> <li>Opera: Current</li> <li>Safari Mobile iOS: 7+</li> <li>Android 4.0+</li> </ul> <p>jQuery team policy is to only change browser support on major-version updates, so this list will apply until at least jQuery 4 arrives.</p> <h2 class="toc-linked" id="jquery-migrate-plugin"><a href="#jquery-migrate-plugin" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> jQuery Migrate Plugin</h2><p>As with the major changes made in jQuery 1.9/2.0, we have created a new version of the <a href="https://github.com/jquery/jquery-migrate/#README">jQuery Migrate Plugin</a> to simplify migration of older code to version 3.0. We strongly recommend that you use this plugin as an upgrading tool, it will give specific advice about most of the major changes that may affect your code.</p> <p><a href="https://github.com/jquery/jquery-migrate/#README">Version 3.0 of the jQuery Migrate Plugin</a> <em>does not</em> warn about or restore behaviors that were removed in previous major version changes such as jQuery 1.9/2.0. Use the following steps to upgrade from a version of jQuery older than 1.11.0 or 2.1.0 to this new version 3.0:</p> <ol> <li>Upgrade the version of jQuery on the page to the latest 1.x or 2.x version.</li> <li>Add the uncompressed <a href="https://github.com/jquery/jquery-migrate/tree/1.x-stable/#README">jQuery Migrate 1.x Plugin</a> to the page.</li> <li>Optional but recommended, update any plugins in use since later versions are usually the most compatible with recent versions of jQuery.</li> <li>Test the page and resolve any warnings that appear on the console, using the <a href="https://github.com/jquery/jquery-migrate/tree/1.x-stable/warnings.md">JQMIGRATE 1.x warning documentation</a> as a guide.</li> <li>Remove the jQuery Migrate 1.x plugin and ensure that the updated jQuery code on the page continues to work properly with only the latest jQuery 1.x/2.x in use.</li> <li>Upgrade the version of jQuery on the page to the latest 3.x version and add the uncompressed <a href="https://github.com/jquery/jquery-migrate/#README">jQuery Migrate 3.x plugin</a> to the page.</li> <li>Test the page and resolve any warnings that appear on the console, using the <a href="https://github.com/jquery/jquery-migrate/blob/master/warnings.md">JQMIGRATE 3.x warning documentation</a> as a guide. Report any bugs in third-party plugins to the plugin author.</li> <li>Remove the jQuery Migrate 3.x plugin and ensure that the page continues to work properly with only the latest jQuery 3.x in use.</li> </ol> <p><strong>Running both Migrate 1.x and Migrate 3.x simultaneously on the same page is not supported.</strong></p> <p>The uncompressed development version of the Migrate plugin includes console log output to warn when specific deprecated and/or removed features are being used. This makes it valuable as a migration debugging tool for finding and remediating issues in existing jQuery code and plugins. </p> <p>The compressed version of the Migrate plugin does not generate any warnings, although it does issue a solitary console message that it has been installed to simplify debugging. Migrate can be used on production sites when jQuery 3.0 or higher is desired but older incompatible jQuery code or plugins must also be used. Ideally this is only used as a short-term solution, since restoring old behavior may cause conflicts with new jQuery code that expects the new behavior.</p> <h2 class="toc-linked" id="summary-of-important-changes"><a href="#summary-of-important-changes" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Summary of Important Changes</h2><p>With a library as widely used as jQuery, it is often difficult for the team to know which changes may impact developers the most before a release occurs. Despite the length of this list, we believe that the majority are edge cases. Many jQuery projects should be able to run version 3.0 with only minor changes if any.</p> <p>Changes are listed by their component category, and prefixed with a description to help you understand its impact:</p> <ul> <li><strong>Breaking change:</strong> This change <em>may</em> affect existing code, since it changes the API surface in some way. Most of the time the impacts are only for specific edge cases as noted.</li> <li><strong>Feature:</strong> The change is an API addition and should not affect existing code in most cases. However, there is the possibility that new features can interact negatively with existing code.</li> <li><strong>Deprecated:</strong> This feature or API is still present in jQuery 3.0, but its use is discouraged. It may be removed in a future major-version update.</li> </ul> <p>Remember that the jQuery Migrate plugin described above can detect and warn about many of these changes so that they can be fixed in your code. </p> <p>For a complete and detailed list of all code changes, see the 3.0 milestone in the <a href="https://github.com/jquery/jquery/issues?q=is%3Aopen+is%3Aissue+milestone%3A3.0.0">jQuery Core issue tracker</a> or the <a href="https://github.com/jquery/jquery/compare/2.2-stable...master">version diff</a>.</p> <h3 class="toc-linked" id="ajax"><a href="#ajax" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Ajax</h3><h4 class="toc-linked" id="breaking-change-special-case-deferred-methods-removed-from-jquery-ajax"><a href="#breaking-change-special-case-deferred-methods-removed-from-jquery-ajax" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Special-case Deferred methods removed from jQuery.ajax</h4><p>The <code>jqXHR</code> object returned from <code>jQuery.ajax()</code> is a jQuery <code>Deferred</code> and has historically had three extra methods with names matching the arguments object of <code>success</code>, <code>error</code>, and <code>complete</code>. This often confused people who did not realize that the returned object should be treated like a <code>Deferred</code>. As of jQuery 3.0 these methods have been removed. As replacements, use the <code>Deferred</code> standard methods of <code>done</code>, <code>fail</code>, and <code>always</code>, or use the new <code>then</code> and <code>catch</code> methods for Promises/A+ compliance.</p> <p>Note that this does not have any impact at all on the ajax callbacks of the same name passed through the <code>options</code> object, which continue to exist and are not deprecated. This only affects the jqXHR methods.</p> <p><a href="https://github.com/jquery/jquery/issues/2084">https://github.com/jquery/jquery/issues/2084</a></p> <h4 class="toc-linked" id="breaking-change-cross-domain-script-requests-must-be-declared"><a href="#breaking-change-cross-domain-script-requests-must-be-declared" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Cross-domain script requests must be declared</h4><p>When making a request via <code>jQuery.ajax()</code> or <code>jQuery.get()</code> for a script on a domain other than the one that hosts the document, you must now explicitly specify <code>dataType: "script"</code> in the options. This prevents the possibility of an attack where the remote site delivers non-script content but later decides to serve a script that has malicious intent. Since <code>jQuery.getScript()</code> explicitly sets <code>dataType: "script"</code> it is unaffected by this change.</p> <h4 class="toc-linked" id="breaking-change-hash-in-a-url-is-preserved-in-a-jquery-ajax-call"><a href="#breaking-change-hash-in-a-url-is-preserved-in-a-jquery-ajax-call" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Hash in a URL is preserved in a <code>jQuery.ajax()</code> call</h4><p>The <code>jQuery.ajax()</code> method no longer strips off the hash in the URL if it is provided, and sends the full URL to the transport (xhr, script, jsonp, or custom transport). If the server at the other end of the connection cannot deal with a hash on a URL, strip it off before sending the request.</p> <p><a href="https://github.com/jquery/jquery/issues/1732">https://github.com/jquery/jquery/issues/1732</a></p> <h4 class="toc-linked" id="feature-new-signature-for-jquery-get-and-jquery-post"><a href="#feature-new-signature-for-jquery-get-and-jquery-post" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Feature: New signature for jQuery.get() AND jQuery.post()</h4><p>jQuery 3 adds a new signature for the <code>jQuery.get()</code> and the <code>jQuery.post()</code> functions by adding a <code>settings</code> parameter. It's an object that can possess many properties and its the same object that you can provide to <a href="https://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings"><code>jQuery.ajax()</code></a>.</p> <p><a href="https://github.com/jquery/jquery/issues/1986">https://github.com/jquery/jquery/issues/1986</a></p> <h3 class="toc-linked" id="attributes"><a href="#attributes" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Attributes</h3><h4 class="toc-linked" id="breaking-change-removeattr-no-longer-sets-properties-to-false"><a href="#breaking-change-removeattr-no-longer-sets-properties-to-false" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>.removeAttr()</code> no longer sets properties to false</h4><p>Prior to jQuery 3.0, using <code>.removeAttr()</code> on a boolean attribute such as <code>checked</code>, <code>selected</code>, or <code>readonly</code> would also set the corresponding named <em>property</em> to <code>false</code>. This behavior was required for ancient versions of Internet Explorer but is not correct for modern browsers because the attribute represents the initial value and the property represents the current (dynamic) value.</p> <p>It is almost always a mistake to use <code>.removeAttr( "checked" )</code> on a DOM element. The only time it might be useful is if the DOM is later going to be serialized back to an HTML string. In all other cases, <code>.prop( "checked", false )</code> should be used instead.</p> <p><a href="https://github.com/jquery/jquery/issues/1759">https://github.com/jquery/jquery/issues/1759</a><br><a href="https://github.com/jquery/jquery/issues/2913">https://github.com/jquery/jquery/issues/2913</a> </p> <h4 class="toc-linked" id="breaking-change-select-multiple-with-nothing-selected-returns-an-empty-array"><a href="#breaking-change-select-multiple-with-nothing-selected-returns-an-empty-array" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: select-multiple with nothing selected returns an empty array</h4><p>Before jQuery 3.0, calling <code>.val()</code> on a <code><select multiple></code> element with no elements selected returned <code>null</code>. This was inconvenient since if at least one value was selected the return value would be an array. Also, if all options are disabled jQuery already returned an empty array. To improve consistency, the nothing-selected case now returns an empty array.</p> <p><a href="https://github.com/jquery/jquery/issues/2562">https://github.com/jquery/jquery/issues/2562</a></p> <h4 class="toc-linked" id="feature-svg-documents-support-class-operations"><a href="#feature-svg-documents-support-class-operations" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Feature: SVG documents support class operations</h4><p>SVG has never been fully supported by jQuery and this hasn't changed in jQuery 3. Nonetheless, many jQuery methods work with SVG documents as well. As of jQuery 3 the methods that manipulate class names, such as <code>.addClass()</code> and <code>.hasClass()</code>, support SVG.</p> <p><a href="https://github.com/jquery/jquery/issues/2199">https://github.com/jquery/jquery/issues/2199</a></p> <h4 class="toc-linked" id="deprecated-toggleclass-with-no-arguments-and-toggleclass-boolean"><a href="#deprecated-toggleclass-with-no-arguments-and-toggleclass-boolean" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: <code>.toggleClass()</code> with no arguments and <code>.toggleClass( Boolean )</code></h4><p>Although a signature for these two cases was documented, its actual behavior was never fully defined. This undefined behavior is now deprecated so it will not be documented. You may find you were accidentally using the functionality because <code>.toggleClass( undefined )</code> behaves the same as a call with no arguments, even though it was invalid input.</p> <h3 class="toc-linked" id="callbacks"><a href="#callbacks" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Callbacks</h3><h4 class="toc-linked" id="feature-locking-a-callback-prevents-only-future-list-execution"><a href="#feature-locking-a-callback-prevents-only-future-list-execution" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Feature: Locking a Callback prevents only future list execution</h4><p>If a Callback object has a handler function that calls the <code>.lock()</code> method after being <code>.fire()</code>d, it only prevents future execution of the callback list and does not immediately abort execution of the current list. To stop the current execution, use the <code>stopOnFalse</code> option. </p> <p><a href="https://github.com/jquery/jquery/issues/1990">https://github.com/jquery/jquery/issues/1990</a></p> <h3 class="toc-linked" id="core"><a href="#core" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Core</h3><h4 class="toc-linked" id="breaking-change-jquery-3-0-runs-in-strict-mode"><a href="#breaking-change-jquery-3-0-runs-in-strict-mode" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: jQuery 3.0 runs in Strict Mode</h4><p>Now that most of the browsers supported by jQuery 3.0 have <code>"use strict"</code>, jQuery is being built with this directive. Your code is not required to run in Strict Mode, so most existing code should not require any changes. The one case we encountered three years ago was that ASP.NET 4.0 used <code>arguments.caller.callee</code> to attempt tracing through call stacks in its <code>__doPostBack()</code> method. If you are still using a version of ASP.NET that still does this, keep using jQuery 2.x or earlier. Modern browsers support stack traces via <code>error.stack</code> so it should not ever be necessary to examine <code>arguments.caller.callee</code>.</p> <p><a href="https://github.com/jquery/jquery/pull/3061">https://github.com/jquery/jquery/pull/3061</a><br><a href="https://bugs.jquery.com/ticket/13335">https://bugs.jquery.com/ticket/13335</a> </p> <h4 class="toc-linked" id="breaking-change-document-ready-handlers-are-now-asynchronous"><a href="#breaking-change-document-ready-handlers-are-now-asynchronous" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: document-ready handlers are now asynchronous</h4><p>The document-ready processing in jQuery has been powered by the <code>jQuery.Deferred</code> implementation since jQuery 1.6. As part of jQuery 3.0's alignment with the Promises/A+ standard, document-ready handlers are called asynchronously even if the document is currently ready at the point where the handler is added. This provides a consistent code execution order that is independent of whether the document is ready or not. For example, consider this code:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code>$(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>)</span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-built_in">console</span>.log(<span class="hljs-string">"ready"</span>);</code></div></div><div class="container"><div class="line"><code>});</code></div></div><div class="container"><div class="line"><code><span class="hljs-built_in">console</span>.log(<span class="hljs-string">"outside ready"</span>);</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p>In jQuery 3.0 this will always log "outside ready" followed by "ready" regardless of whether the document is ready at the point of execution. Earlier versions may log the messages in either order.</p> <p>Since handlers now execute independently of each other, an exception or failure in one document-ready handler no longer prevents other document-ready handlers from running.</p> <p>In custom builds where the <code>deferred</code> module is excluded, an alternative implementation of the document-ready code is used. This implementation supports the <code>jQuery.ready</code> promise but is not a <code>jQuery.Deferred</code> object so it should only be used through <code>jQuery.when()</code>.</p> <p><a href="https://github.com/jquery/jquery/issues/1823">https://github.com/jquery/jquery/issues/1823</a><br><a href="https://github.com/jquery/jquery/pull/2891">https://github.com/jquery/jquery/pull/2891</a></p> <h4 class="toc-linked" id="breaking-change-jquery-isnumeric-and-custom-tostring"><a href="#breaking-change-jquery-isnumeric-and-custom-tostring" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: jQuery.isNumeric() and custom <code>.toString()</code></h4><p>The <code>jQuery.isNumeric()</code> method is intended to be used with primitive numbers and strings that can be coerced to finite numbers. In particular, it no longer tries to obtain numbers from objects that have a <code>.toString()</code> method. Users needing specialized checks for other numerics should create their own validation functions.</p> <p><a href="https://github.com/jquery/jquery/issues/2662">https://github.com/jquery/jquery/issues/2662</a></p> <h4 class="toc-linked" id="breaking-change-deprecated-context-and-selector-properties-removed"><a href="#breaking-change-deprecated-context-and-selector-properties-removed" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Deprecated <code>.context</code> and <code>.selector</code> properties removed</h4><p>These properties were deprecated in jQuery 1.9, as they were only used for the obsolete <code>.live()</code> method and have never accurately represented the context or selector for the current collection.</p> <p><a href="https://github.com/jquery/jquery/issues/1908">https://github.com/jquery/jquery/issues/1908</a></p> <h4 class="toc-linked" id="breaking-change-deprecated-size-removed"><a href="#breaking-change-deprecated-size-removed" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Deprecated <code>.size()</code> removed</h4><p><code>.size()</code> is deprecated as of jQuery 1.8 and removed in jQuery 3.0 in favor of the <code>.length</code> property.</p> <h4 class="toc-linked" id="breaking-change-undocumented-internal-methods-no-longer-exposed"><a href="#breaking-change-undocumented-internal-methods-no-longer-exposed" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Undocumented internal methods no longer exposed</h4><p>Version 3.0 removes several methods from view that were intended to be private and were never documented:</p> <ul> <li>jQuery.swap</li> <li>jQuery.buildFragment</li> <li>jQuery.domManip</li> </ul> <p><a href="https://github.com/jquery/jquery/issues/2224">https://github.com/jquery/jquery/issues/2224</a><br><a href="https://github.com/jquery/jquery/issues/2225">https://github.com/jquery/jquery/issues/2225</a> </p> <h4 class="toc-linked" id="breaking-change-return-values-on-empty-sets-are-undefined"><a href="#breaking-change-return-values-on-empty-sets-are-undefined" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Return values on empty sets are <code>undefined</code></h4><p>With few exceptions, any value-returning jQuery methods should return <code>undefined</code> on an empty jQuery collection in keeping with our <a href="https://github.com/jquery/jquery/wiki/API-design-guidelines">API guidelines</a>. The following APIs were changed to conform to this rule:</p> <ul> <li>Dimensional methods: <code>.width()</code>, <code>.height()</code>, <code>.innerWidth()</code>, <code>.innerHeight()</code>, <code>.outerWidth()</code>, and <code>.outerHeight()</code></li> <li>Offset methods: <code>.offsetTop()</code> and <code>.offsetLeft()</code></li> </ul> <p>Previously, these methods returned <code>null</code> instead of <code>undefined</code> for an empty collection.</p> <p><a href="https://github.com/jquery/jquery/issues/2319">https://github.com/jquery/jquery/issues/2319</a></p> <h4 class="toc-linked" id="feature-for-of-loops-can-be-used-on-jquery-collections"><a href="#feature-for-of-loops-can-be-used-on-jquery-collections" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Feature: <code>for...of</code> loops can be used on jQuery collections</h4><p>jQuery 3.0 supports the <code>for...of</code> loop introduced in ES2015. It allows looping over iterable objects including <code>Array</code>, <code>Map</code>, and <code>Set</code>. When using this loop, the value obtained is a DOM element of the jQuery collection, one at a time. Note that you will need to be using an environment that supports ES2015 or a transpiler such as Babel to use <code>for...of</code>. Here is an example:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> <div class="line n5">5</div> <div class="line n6">6</div> <div class="line n7">7</div> <div class="line n8">8</div> <div class="line n9">9</div> <div class="line n10">10</div> <div class="line n11">11</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code><span class="hljs-keyword">var</span> elems = $(<span class="hljs-string">".someclass"</span>);</code></div></div><div class="container"><div class="line"><code> </code></div></div><div class="container"><div class="line"><code><span class="hljs-comment">// Classic jQuery way</span></code></div></div><div class="container"><div class="line"><code>$.each(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">i, elem</span>) </span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// work with elem (or "this" object)</span></code></div></div><div class="container"><div class="line"><code>});</code></div></div><div class="container"><div class="line"><code> </code></div></div><div class="container"><div class="line"><code><span class="hljs-comment">// Prettier ES2015 way</span></code></div></div><div class="container"><div class="line"><code><span class="hljs-keyword">for</span> ( <span class="hljs-keyword">let</span> elem <span class="hljs-keyword">of</span> elems ) {</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// work with elem</span></code></div></div><div class="container"><div class="line"><code>}</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p><a href="https://github.com/jquery/jquery/issues/1693">https://github.com/jquery/jquery/issues/1693</a></p> <h4 class="toc-linked" id="feature-jquery-ready-promise-is-formally-supported"><a href="#feature-jquery-ready-promise-is-formally-supported" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Feature: <code>jQuery.ready</code> promise is formally supported</h4><p><code>jQuery.ready</code> has been consumable as a promise-like object ("thenable" in Promise terms) since jQuery version 1.8. As of jQuery 3.0 this object is documented as supported via <code>jQuery.when</code> or the native <code>Promise.resolve()</code>. No code should make assumptions about whether this object is a jQuery <code>Deferred</code> or some other type of promise object such as a native Promise. Typical usage might look like this:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> <div class="line n5">5</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code>$.when( $.ready, $.getScript(<span class="hljs-string">"optional.js"</span>) ).then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// the document is ready and optional.js has loaded/run</span></code></div></div><div class="container"><div class="line"><code>}).catch( <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// an error occurred</span></code></div></div><div class="container"><div class="line"><code>});</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p><a href="https://github.com/jquery/api.jquery.com/pull/530">https://github.com/jquery/api.jquery.com/pull/530</a></p> <h4 class="toc-linked" id="deprecated-jquery-unique-renamed-to-jquery-uniquesort"><a href="#deprecated-jquery-unique-renamed-to-jquery-uniquesort" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: <code>jQuery.unique()</code>, renamed to <code>jQuery.uniqueSort()</code></h4><p>The <code>jQuery.unique()</code> method has been renamed to <code>jQuery.uniqueSort()</code> to make its behavior easier to understand. There is no change to functionality here, only a rename.</p> <h4 class="toc-linked" id="deprecated-jquery-parsejson"><a href="#deprecated-jquery-parsejson" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: <code>jQuery.parseJSON()</code></h4><p>Since all the browsers supported by jQuery 3.0 support the native <code>JSON.parse()</code> method, we are deprecating <code>jQuery.parseJSON()</code>. </p> <p><a href="https://github.com/jquery/jquery/issues/2800">https://github.com/jquery/jquery/issues/2800</a></p> <h4 class="toc-linked" id="deprecated-document-ready-handlers-other-than-jquery-function"><a href="#deprecated-document-ready-handlers-other-than-jquery-function" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: document-ready handlers other than <code>jQuery(function)</code></h4><p>Due to historical compatibility issues there are a multitude of ways to set a document ready handler. All of the following are equivalent and call the function <code>fn</code> when the document is ready:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code>$(fn);</code></div></div><div class="container"><div class="line"><code>$().ready(fn);</code></div></div><div class="container"><div class="line"><code>$(<span class="hljs-built_in">document</span>).ready(fn);</code></div></div><div class="container"><div class="line"><code>$(<span class="hljs-string">"selector"</span>).ready(fn);</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p>As of jQuery 3.0 the recommended way to add a ready handler is the first method, <code>$(fn)</code>. As noted in the Event section, the <code>$(document).on("ready", fn)</code> event form has slightly different semantics and was removed in jQuery 3.0.</p> <h3 class="toc-linked" id="data"><a href="#data" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Data</h3><h4 class="toc-linked" id="breaking-change-data-names-containing-dashes"><a href="#breaking-change-data-names-containing-dashes" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: .data() names containing dashes</h4><p>As of jQuery 3.0, all data names are stored in jQuery's internal data object in camelCase (e.g., <code>clickCount</code>), rather than kebab-case (e.g. <code>click-count</code>). This is consistent with the way that standard DOM turns dashed names into camel case for JavaScript names in CSS and data properties.</p> <p>In general, kebab case still works in jQuery 3.0 when setting or getting a specific data item, e.g. <code>.data("right-aligned")</code>, but if you retrieve the internal data object it will now have the data item in camel case (<code>rightAligned</code>). The main difference in 3.0 is when you use kebab case names directly on the data object instead of using the <code>.data()</code> API to get or set them.</p> <p>For example:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> <div class="line n5">5</div> <div class="line n6">6</div> <div class="line n7">7</div> <div class="line n8">8</div> <div class="line n9">9</div> <div class="line n10">10</div> <div class="line n11">11</div> <div class="line n12">12</div> <div class="line n13">13</div> <div class="line n14">14</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code><span class="hljs-keyword">var</span> $div = $(<span class="hljs-string">"<div />"</span>);</code></div></div><div class="container"><div class="line"><code>$div.data(<span class="hljs-string">"clickCount"</span>, <span class="hljs-number">2</span>);</code></div></div><div class="container"><div class="line"><code>$div.data(<span class="hljs-string">"clickCount"</span>); <span class="hljs-comment">// 2</span></code></div></div><div class="container"><div class="line"><code>$div.data(<span class="hljs-string">"click-count"</span>, <span class="hljs-number">3</span>);</code></div></div><div class="container"><div class="line"><code>$div.data(<span class="hljs-string">"clickCount"</span>); <span class="hljs-comment">// 3</span></code></div></div><div class="container"><div class="line"><code>$div.data(<span class="hljs-string">"click-count"</span>); <span class="hljs-comment">// 3</span></code></div></div><div class="container"><div class="line"><code> </code></div></div><div class="container"><div class="line"><code><span class="hljs-keyword">var</span> allData = $div.data();</code></div></div><div class="container"><div class="line"><code>allData.clickCount; <span class="hljs-comment">// 3</span></code></div></div><div class="container"><div class="line"><code>allData[<span class="hljs-string">"click-count"</span>]; <span class="hljs-comment">// undefined</span></code></div></div><div class="container"><div class="line"><code>allData[<span class="hljs-string">"click-count"</span>] = <span class="hljs-number">14</span>;</code></div></div><div class="container"><div class="line"><code>$div.data(<span class="hljs-string">"click-count"</span>); <span class="hljs-comment">// 3, NOT 14 as it would be in jQuery 2.x</span></code></div></div><div class="container"><div class="line"><code>allData.clickCount; <span class="hljs-comment">// 3</span></code></div></div><div class="container"><div class="line"><code>allData[<span class="hljs-string">"click-count"</span>]; <span class="hljs-comment">// 14</span></code></div></div></pre> </td> </tr> </tbody> </table> </div> <p><a href="https://github.com/jquery/jquery/issues/2070">https://github.com/jquery/jquery/issues/2070</a><br><a href="https://github.com/jquery/jquery/issues/2257">https://github.com/jquery/jquery/issues/2257</a><br><a href="https://github.com/jquery/jquery/issues/1751">https://github.com/jquery/jquery/issues/1751</a> </p> <h3 class="toc-linked" id="deferred"><a href="#deferred" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deferred</h3><h4 class="toc-linked" id="breaking-change-and-feature-jquery-deferred-is-now-promises-a-compatible"><a href="#breaking-change-and-feature-jquery-deferred-is-now-promises-a-compatible" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change and Feature: jQuery.Deferred is now Promises/A+ compatible</h4><p>Deferreds have been updated for compatibility with Promises/A+ and ES2015 (a.k.a ES6) Promise, a change with significant consequences.</p> <p><a href="https://github.com/jquery/jquery/issues/1722">https://github.com/jquery/jquery/issues/1722</a><br><a href="https://github.com/jquery/jquery/issues/2102">https://github.com/jquery/jquery/issues/2102</a> </p> <h5 class="toc-linked" id="resolution"><a href="#resolution" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Resolution</h5><p><code>.resolve</code>, <code>.reject</code>, and <code>.notify</code> now set <code>undefined</code> context instead of using the promise of the Deferred object with which they are associated. To set an explicit context, use <code>.resolveWith</code>, <code>.rejectWith</code>, and <code>.notifyWith</code>.</p> <p><a href="https://github.com/jquery/jquery/issues/3060">https://github.com/jquery/jquery/issues/3060</a></p> <h5 class="toc-linked" id="callback-exit"><a href="#callback-exit" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Callback exit</h5><p>Major changes have been made to the <code>.then()</code> method. In particular, any exception thrown within a <code>.then()</code> callback is now caught and converted into a rejection value, and any non-thenable value returned from a <em>rejection</em> handler becomes a fulfillment value. We <strong>strongly recommend</strong> that you add a <code>.catch()</code> method (new in 3.0) to the end of your promise chain to avoid difficult debugging issues. The most likely place you may encounter this new behavior is when using the Deferreds that are produced by <code>jQuery.ajax()</code>, since the <code>jQXHR</code> object returned is a superset of <code>jQuery.Deferred</code>.</p> <p>In jQuery 1.x and 2.x, an uncaught exception inside a callback function halts code execution. The thrown exception bubbles up until it is caught inside a try/catch or reaches <code>window</code> and triggers <code>window.onerror</code>.</p> <p>For example, consider this code using the new standard Promises/A+ behavior:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> <div class="line n5">5</div> <div class="line n6">6</div> <div class="line n7">7</div> <div class="line n8">8</div> <div class="line n9">9</div> <div class="line n10">10</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code>$.ajax(<span class="hljs-string">"/status"</span>)</code></div></div><div class="container"><div class="line"><code> .then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{</code></div></div><div class="container"><div class="line"><code> whoops();</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// console shows "jQuery.Deferred exception: whoops is not a function"</span></code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// no further code executes in this function</span></code></div></div><div class="container"><div class="line"><code> })</code></div></div><div class="container"><div class="line"><code> .catch(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">arg</span>) </span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// this code executes after the error above</span></code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// arg is an Error object, "whoops is not a function"</span></code></div></div><div class="container"><div class="line"><code> });</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p>Compare that to the old-style Deferred methods:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> <div class="line n5">5</div> <div class="line n6">6</div> <div class="line n7">7</div> <div class="line n8">8</div> <div class="line n9">9</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code>$.ajax(<span class="hljs-string">"/status"</span>)</code></div></div><div class="container"><div class="line"><code> .done(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">data</span>) </span>{</code></div></div><div class="container"><div class="line"><code> whoops();</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// console shows: "whoops is not a function"</span></code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// no further code executes in this function</span></code></div></div><div class="container"><div class="line"><code> })</code></div></div><div class="container"><div class="line"><code> .fail(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">arg</span>) </span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// this code does not execute since the exception was not caught</span></code></div></div><div class="container"><div class="line"><code> });</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p>Note that jQuery logs a message to the console when it is inside a Deferred and a JavaScript exception occurs. These messages take the form <code>jQuery.Deferred exception: (error message)</code>. If you do not want any console output on these exceptions, set <code>jQuery.Deferred.exceptionHook</code> to <code>undefined</code>. If you need further help in finding errors reported this way, use the <a href="https://github.com/dmethvin/jquery-deferred-reporter">jquery-deferred-reporter plugin</a> during development to obtain stack traces.</p> <p><a href="https://github.com/jquery/jquery/issues/2736">https://github.com/jquery/jquery/issues/2736</a> </p> <h5 class="toc-linked" id="callback-invocation"><a href="#callback-invocation" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Callback invocation</h5><p>The Promises/A+ spec says that promises are always resolved with a <em>single value</em> and handlers are invoked without a <code>this</code> context, while jQuery Deferreds sometimes pass context and/or multiple values to their handlers. In most cases, though, the first argument is the most important of these values. If you mix other Promises/A+ implementations with jQuery's, you may only receive a single argument in your handler. To maintain full compatibility for existing code, use only jQuery Deferreds and switch to the older <code>.done()</code> and <code>.fail()</code> methods which retain all the backward-compatible behavior:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> <div class="line n4">4</div> <div class="line n5">5</div> <div class="line n6">6</div> <div class="line n7">7</div> <div class="line n8">8</div> <div class="line n9">9</div> <div class="line n10">10</div> <div class="line n11">11</div> <div class="line n12">12</div> <div class="line n13">13</div> <div class="line n14">14</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code><span class="hljs-comment">// Typical old uses of .then() that are not Promises/A+ compatible</span></code></div></div><div class="container"><div class="line"><code>$.ajax(<span class="hljs-string">"url"</span>).then(</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// success</span></code></div></div><div class="container"><div class="line"><code> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"> data, textStatus, jqXHR </span>) </span>{ <span class="hljs-comment">/* code */</span> },</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// error</span></code></div></div><div class="container"><div class="line"><code> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"> jqXHR, textStatus, errorThrown </span>) </span>{ <span class="hljs-comment">/* code */</span> }</code></div></div><div class="container"><div class="line"><code>);</code></div></div><div class="container"><div class="line"><code> </code></div></div><div class="container"><div class="line"><code><span class="hljs-comment">// Rewrite to this in order to maintain previous behavior</span></code></div></div><div class="container"><div class="line"><code>$.ajax(<span class="hljs-string">"url"</span>)</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// success</span></code></div></div><div class="container"><div class="line"><code> .done(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"> data, textStatus, jqXHR </span>) </span>{ <span class="hljs-comment">/* code */</span> })</code></div></div><div class="container"><div class="line"><code> <span class="hljs-comment">// error</span></code></div></div><div class="container"><div class="line"><code> .fail(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"> jqXHR, textStatus, errorThrown </span>) </span>{ <span class="hljs-comment">/* code */</span> });</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p>Another behavior change required for Promises/A+ compliance is that Deferred <code>.then()</code> callbacks are <em>always</em> called asynchronously. Previously, if a <code>.then()</code> callback was added to a Deferred that was already resolved or rejected, the callback would run immediately and synchronously.</p> <h5 class="toc-linked" id="backwards-compatibility"><a href="#backwards-compatibility" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Backwards compatibility</h5><p>Deferred methods such as <code>.done()</code>, <code>.fail()</code>, and <code>.pipe()</code> retain their old behavior and so are not Promises/A+ compliant. If you require synchronous resolution, do not want exceptions converted to rejection values or rejection callback returns converted to fulfillment values, or want thrown errors to bubble out of the function where they occur, you can use these methods instead of <code>.then()</code> and <code>.catch()</code>.</p> <h4 class="toc-linked" id="breaking-change-and-feature-jquery-when-arguments"><a href="#breaking-change-and-feature-jquery-when-arguments" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change and Feature: jQuery.when() arguments</h4><p><code>jQuery.when</code> now interprets any input argument with a <code>then</code> method as a Promise-compatible "<a href="https://promisesaplus.com/#point-7">thenable</a>". This allows a much broader range of inputs, including native ES6 Promises and Bluebird promises.</p> <p>Further, a more clear distinction is now recognized between multi-argument calls to <code>jQuery.when</code> and single- or no-argument calls. Multi-argument calls behave similarly to <code>Promise.all</code>, aggregating fulfillment values into a fulfillment array (with jQuery-specific enhancements of also aggregating fulfillment contexts and supporting multi-valued fulfillments), or alternatively rejecting with the first rejection value. Single- and no-argument calls behave similarly to <code>Promise.resolve</code>, returning a Deferred that resolves identically to thenable or Promise-like input, or fulfills with its non-Promise input (as appropriate). As of jQuery 3.0, both of these return a new Deferred (previous versions did not create a new Deferred when called with a single Deferred input).</p> <p><a href="https://github.com/jquery/jquery/issues/2018">https://github.com/jquery/jquery/issues/2018</a><br><a href="https://github.com/jquery/jquery/issues/2546">https://github.com/jquery/jquery/issues/2546</a><br><a href="https://github.com/jquery/jquery/issues/3029">https://github.com/jquery/jquery/issues/3029</a> </p> <h4 class="toc-linked" id="breaking-change-jquery-when-progress-notifications"><a href="#breaking-change-jquery-when-progress-notifications" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: jQuery.when() progress notifications</h4><p>As of jQuery 3.0, the <code>jQuery.when()</code> method no longer passes along progress notifications from input Deferreds to the output Deferred. Progress messages are not part of the Promises/A+ specification, and the behavior of progress notifications in <code>jQuery.when()</code> were not previously documented in the jQuery API.</p> <p><a href="https://github.com/jquery/jquery/issues/2710">https://github.com/jquery/jquery/issues/2710</a> </p> <h3 class="toc-linked" id="dimensions"><a href="#dimensions" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Dimensions</h3><h4 class="toc-linked" id="breaking-change-width-height-css-quot-width-quot-and-css-quot-height-quot-can-return-non-integer-values"><a href="#breaking-change-width-height-css-quot-width-quot-and-css-quot-height-quot-can-return-non-integer-values" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: .width(), .height(), .css("width"), and .css("height") can return non-integer values</h4><p>Before version 3.0, jQuery used the DOM <code>offsetWidth</code> and <code>offsetHeight</code> properties to determine the dimensions of an element, and these properties always return integers. With jQuery 3.0 we get more precise values via the DOM <code>getBoundingClientRect</code> API, and these may not be integers. If your code always expects integers for dimensions, it may need to be adjusted to deal with this extra precision.</p> <p><a href="https://github.com/jquery/jquery/issues/1724">https://github.com/jquery/jquery/issues/1724</a></p> <h4 class="toc-linked" id="breaking-change-outerwidth-or-outerheight-on-window-includes-scrollbar-width-height"><a href="#breaking-change-outerwidth-or-outerheight-on-window-includes-scrollbar-width-height" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>.outerWidth()</code> or <code>.outerHeight()</code> on <code>window</code> includes scrollbar width/height</h4><p>Calls to <code>$(window).width()</code> return the "content width" which excludes any scrollbars that the browser has added if the content exceeds the height of the element. This is different from the width that CSS uses for media queries, which includes the width of the scrollbars. In order to provide a measure that is equivalent to the CSS media query concept of width, the <code>$(window).outerWidth()</code> method now returns the width including scrollbar width. This is equivalent to the DOM property <code>window.innerWidth</code>. The same applies for <code>.outerHeight()</code>.</p> <p><a href="https://github.com/jquery/jquery/issues/1729">https://github.com/jquery/jquery/issues/1729</a></p> <h3 class="toc-linked" id="effects"><a href="#effects" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Effects</h3><h4 class="toc-linked" id="breaking-change-show-hide-and-toggle-methods-now-respect-more-stylesheet-changes"><a href="#breaking-change-show-hide-and-toggle-methods-now-respect-more-stylesheet-changes" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: .show(), .hide(), and .toggle() methods now respect more stylesheet changes</h4><p>The code that jQuery uses to show and hide elements has been updated to focus on inline rather than computed styles, respecting stylesheet <code>display</code> values whenever possible for increased compatibility with responsive design techniques (in which active stylesheet rules can dynamically change upon device reorientation/window resize/etc.). As a result, disconnected elements are no longer considered hidden unless they have inline <code>display: none</code>, and therefore <code>.toggle()</code> will no longer differentiate them from connected elements as of jQuery 3.0.</p> <p>Further, while <code>.show()</code> and similar calls will continue to force visibility of elements that are hidden by stylesheet rules, supporting this functionality slows down all show/hide operations and its use is not recommended. The determination of which display value to set in such cases has also been simplified, defaulting to "block" when body-level rules hide elements by type.</p> <p>Any code expecting hidden elements to be reshown with their previous <em>computed</em> display styles, or disconnected elements to treated as hidden, should be reviewed. The team created a <a href="https://docs.google.com/spreadsheets/d/1UaISjcS3UMxVJ7eSBIXtK-jqF8Grl67w640peCqlkoc/edit">table</a> of all the possibilities related to the display state and show/hide actions in order to minimize the setting of non-empty inline styles.</p> <h4 class="toc-linked" id="feature-animations-now-use-requestanimationframe"><a href="#feature-animations-now-use-requestanimationframe" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Feature: Animations now use requestAnimationFrame</h4><p>On platforms that support the <code>requestAnimationFrame</code> API, which is pretty much everywhere but IE9, jQuery will now use that API when performing animations. This should result in animations that are smoother and use less CPU time—and save battery as well on mobile devices. </p> <p>jQuery tried using requestAnimationFrame a few years back but there were serious compatibility issues with existing code so we had to back it out. We think we’ve beaten most of those issues by suspending animations while a browser tab is out of view. Still, any code that depends on animations to always run in nearly real-time is making an unrealistic assumption.</p> <h4 class="toc-linked" id="deprecated-jquery-fx-interval"><a href="#deprecated-jquery-fx-interval" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: jQuery.fx.interval</h4><p>Now that <code>requestAnimationFrame</code> is being used for animations, the <code>jQuery.fx.interval</code> property is ignored on most browsers. It is still present in jQuery 3.0 and used in browsers such as IE9, but will be removed in a future major-point release.</p> <h4 class="toc-linked" id="deprecated-additional-easing-function-parameters"><a href="#deprecated-additional-easing-function-parameters" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: Additional easing function parameters</h4><p>The easing functions called by <code>.animate()</code> are passed single argument, the percentage of completion. Some older code assumes that it is passed additional arguments derived from the percentage. These other arguments may not be present in a future major version update.</p> <p>Example of an old easing method:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code>$.easing.easeInOutSine = <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">x, t, b, c, d</span>) </span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-keyword">return</span> -c/<span class="hljs-number">2</span> * (<span class="hljs-built_in">Math</span>.cos(<span class="hljs-built_in">Math</span>.PI*t/d) - <span class="hljs-number">1</span>) + b;</code></div></div><div class="container"><div class="line"><code>};</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p>The same easing method rewritten:</p> <div class="syntaxhighlighter javascript"> <table> <tbody> <tr> <td class="gutter"> <div class="line n1">1</div> <div class="line n2">2</div> <div class="line n3">3</div> </td> <td class="code"> <pre><div class="container"><div class="line"><code>$.easing.easeInOutSine = <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">x</span>) </span>{</code></div></div><div class="container"><div class="line"><code> <span class="hljs-keyword">return</span> -<span class="hljs-number">0.5</span>*(<span class="hljs-built_in">Math</span>.cos(<span class="hljs-built_in">Math</span>.PI*x) - <span class="hljs-number">1</span>);</code></div></div><div class="container"><div class="line"><code>};</code></div></div></pre> </td> </tr> </tbody> </table> </div> <p><a href="https://github.com/jquery/api.jquery.com/issues/912">https://github.com/jquery/api.jquery.com/issues/912</a> </p> <h3 class="toc-linked" id="event"><a href="#event" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Event</h3><h4 class="toc-linked" id="breaking-change-load-unload-and-error-removed"><a href="#breaking-change-load-unload-and-error-removed" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: .load(), .unload(), and .error() removed</h4><p>These methods are shortcuts for event operations, but had several API limitations. The event <code>.load()</code> method conflicted with the ajax <code>.load()</code> method. The <code>.error()</code> method could not be used with <code>window.onerror</code> because of the way the DOM method is defined. If you need to attach events by these names, use the <code>.on()</code> method, e.g. change <code>$("img").load(fn)</code> to <code>$("img").on("load", fn)</code>.</p> <p><a href="https://github.com/jquery/jquery/issues/2286">https://github.com/jquery/jquery/issues/2286</a></p> <h4 class="toc-linked" id="breaking-change-on-quot-ready-quot-fn-removed"><a href="#breaking-change-on-quot-ready-quot-fn-removed" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>.on("ready", fn)</code> removed</h4><p>jQuery no longer supports a synthetic event named <code>"ready"</code> that can be used with the event functions. This event was error-prone and deprecated in jQuery 1.8 because it would only call the callback if it was attached before the document was ready. Replace any uses with <code>$(fn)</code> instead, which works reliably.</p> <p><a href="https://github.com/jquery/jquery/issues/2264">https://github.com/jquery/jquery/issues/2264</a></p> <h4 class="toc-linked" id="breaking-change-event-pagex-and-event-pagey-normalization-removed"><a href="#breaking-change-event-pagex-and-event-pagey-normalization-removed" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>event.pageX</code> and <code>event.pageY</code> normalization removed</h4><p>All the browsers officially supported by jQuery 3.0 provide the pageX and pageY properties in their events, so the jQuery code to calculate these values from other event properties has been removed. This change should not affect mainstream browsers, but there may be obscure environments where these properties are not present. If you find one, please open a ticket.</p> <p><a href="https://github.com/jquery/jquery/issues/3092">https://github.com/jquery/jquery/issues/3092</a></p> <h4 class="toc-linked" id="breaking-change-jquery-event-props-and-jquery-event-fixhooks-removed"><a href="#breaking-change-jquery-event-props-and-jquery-event-fixhooks-removed" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>jQuery.event.props</code> and <code>jQuery.event.fixHooks</code> removed</h4><p>jQuery's event handling performance increased thanks to a reorganization of event property management. The main improvement is that jQuery now only calculates or copies a property on the first access, rather than calculating and copying them up front. This is a really big win with properties that may force layout that the event handler may not even need. The most common use we know of was to add properties for pointer events, which is no longer necessary because those events are supported already in jQuery 3.0. The jQuery Migrate plugin provides support for these properties if you still need them. The related but undocumented <code>mouseHooks</code> and <code>keyHooks</code> lists were removed as well. The team is interested in understanding other use cases before defining new APIs, so feel free to open a ticket.</p> <p><a href="https://github.com/jquery/jquery/issues/3103">https://github.com/jquery/jquery/issues/3103</a><br><a href="https://github.com/jquery/jquery/issues/1746">https://github.com/jquery/jquery/issues/1746</a><br><a href="https://learn.jquery.com/events/event-extensions/">https://learn.jquery.com/events/event-extensions/</a> </p> <h4 class="toc-linked" id="breaking-change-delegated-events-with-bad-selectors-throw-immediately"><a href="#breaking-change-delegated-events-with-bad-selectors-throw-immediately" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Delegated events with bad selectors throw <em>immediately</em></h4><p>Before jQuery 3.0, the selector used in a delegated event wasn't used until the first time that event occurred on the element. This sometimes led to hard-to-debug cases where the error was far removed from the time and code where the mistake was made. Now the selector is tested when the event is attached and throws an error if it is not valid. The only reason this is considered a breaking change is that code might use an invalid selector when attaching an event that never occurs, and that case previously would have never thrown an error.</p> <p><a href="https://github.com/jquery/jquery/issues/3071">https://github.com/jquery/jquery/issues/3071</a></p> <h4 class="toc-linked" id="deprecated-bind-and-delegate"><a href="#deprecated-bind-and-delegate" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: .bind() and .delegate()</h4><p>Five years ago in jQuery 1.7 we introduced the <code>.on()</code> method for attaching event handlers. The older <code>.bind()</code>, <code>.unbind()</code>, <code>.delegate()</code> and <code>.undelegate()</code> methods are being deprecated as of 3.0, but are still present. The API documentation explains how to rewrite the calls using the <code>.on()</code> and <code>.off()</code> methods.</p> <h3 class="toc-linked" id="manipulation"><a href="#manipulation" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Manipulation</h3><h4 class="toc-linked" id="breaking-change-wrapall-function-only-calls-the-function-once"><a href="#breaking-change-wrapall-function-only-calls-the-function-once" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>.wrapAll(function)</code> only calls the function once</h4><p>In previous versions, the <code>.wrapAll()</code> method acted like <code>.wrap()</code> when a function was passed. This has been corrected; now and <code>.wrapAll(function)</code> calls its function once, using the string result of the function call to wrap the entire collection.</p> <p><a href="https://github.com/jquery/jquery/issues/1843">https://github.com/jquery/jquery/issues/1843</a></p> <h3 class="toc-linked" id="offset"><a href="#offset" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Offset</h3><h4 class="toc-linked" id="breaking-change-invalid-input-to-the-offset-method"><a href="#breaking-change-invalid-input-to-the-offset-method" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Invalid input to the <code>.offset()</code> method</h4><p>When using the <code>.offset()</code> method, the first item in the jQuery collection must be a DOM element that has a DOM <code>getBoundingClientRect()</code> method. (All browsers supported by jQuery 3.0 have this API.) Any other input may result in jQuery throwing an error. Also note that the element must be visible and currently in a document (i.e., not disconnected).</p> <p><a href="https://github.com/jquery/jquery/issues/2115">https://github.com/jquery/jquery/issues/2115</a><br><a href="https://github.com/jquery/jquery/issues/2114">https://github.com/jquery/jquery/issues/2114</a> </p> <h3 class="toc-linked" id="selector"><a href="#selector" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Selector</h3><h4 class="toc-linked" id="breaking-change-behavior-of-hidden-and-visible"><a href="#breaking-change-behavior-of-hidden-and-visible" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: Behavior of <code>:hidden</code> and <code>:visible</code></h4><p>An element is considered now visible if it has a layout box returned from the DOM <code>getClientRects()</code> method, even if that box has a height and/or width of zero. This means that elements such as <code><br /></code> or an empty <code><span></code> element that don't have height are considered to be visible. </p> <p><a href="https://github.com/jquery/jquery/issues/2227">https://github.com/jquery/jquery/issues/2227</a><br><a href="https://github.com/jquery/jquery/issues/2604">https://github.com/jquery/jquery/issues/2604</a> </p> <h4 class="toc-linked" id="breaking-change-jquery-quot-quot-and-find-quot-quot-are-invalid-syntax"><a href="#breaking-change-jquery-quot-quot-and-find-quot-quot-are-invalid-syntax" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>jQuery("#")</code> and <code>.find("#")</code> are invalid syntax</h4><p>jQuery 3.0 throws a syntax error if a selector string consists of nothing but a hash-mark. In previous versions, <code>$("#")</code> returned an empty collection and <code>.find("#")</code> threw an error.</p> <p><a href="https://github.com/jquery/jquery/pull/1682">https://github.com/jquery/jquery/pull/1682</a></p> <h4 class="toc-linked" id="feature-new-method-jquery-escapeselector"><a href="#feature-new-method-jquery-escapeselector" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Feature: New method <code>jQuery.escapeSelector()</code></h4><p>The new <code>jQuery.escapeSelector( selector )</code> method takes a selector string and escapes any character that has a special meaning in a CSS selector. It is essentially a shim for the <a href="https://drafts.csswg.org/cssom/#the-css.escape%28%29-method">CSS Working Group's <code>CSS.escape()</code> method</a> that runs on all of jQuery's supported browsers. This method is useful for situations where a class name or an ID contains characters that have a special meaning in CSS, such as the dot or the semicolon.</p> <p>For example, if an element on the page has an id of "abc.def" it cannot be selected with <code>$( "#abc.def" )</code> because the selector is parsed as "an element with id 'abc' that also has a class 'def'. However, it <em>can</em> be selected with <code>$( "#" + $.escapeSelector( "abc.def" ) )</code>.</p> <p><a href="https://github.com/jquery/jquery/issues/1761">https://github.com/jquery/jquery/issues/1761</a> </p> <h4 class="toc-linked" id="deprecated-jquery-expr-quot-quot-and-jquery-expr-filters"><a href="#deprecated-jquery-expr-quot-quot-and-jquery-expr-filters" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Deprecated: <code>jQuery.expr[":"]</code> and <code>jQuery.expr.filters</code></h4><p>These two names for defining custom selectors through jQuery's Sizzle selection engine are the same as <code>jQuery.expr.pseudos</code>, so we are deprecating the redundant names. </p> <h3 class="toc-linked" id="serialize"><a href="#serialize" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Serialize</h3><h4 class="toc-linked" id="breaking-change-jquery-param-no-longer-converts-20-to-a-plus-sign"><a href="#breaking-change-jquery-param-no-longer-converts-20-to-a-plus-sign" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: jQuery.param() no longer converts %20 to a plus sign</h4><p>In forms that are POST-ed via <code>jQuery.ajax()</code>, the <a href="https://url.spec.whatwg.org/#concept-urlencoded-byte-serializer">specification</a> for <code>application/x-www-form-urlencoded</code> encoding says that any occurrence of a space should be converted to the <code>+</code> character. Previously, jQuery implemented this by doing the conversion in <code>jQuery.param()</code>. Now, that conversion has been moved into <code>jQuery.ajax()</code>. Data encoded via <code>jQuery.param()</code> will convert spaces to <code>%20</code>, which makes it directly compatible with the use of the native JavaScript <code>encodeURIComponent()</code> and <code>decodeURIComponent()</code> methods.</p> <p><a href="https://github.com/jquery/jquery/issues/2658">https://github.com/jquery/jquery/issues/2658</a></p> <h3 class="toc-linked" id="traversing"><a href="#traversing" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Traversing</h3><h4 class="toc-linked" id="breaking-change-andself-removed-use-addback"><a href="#breaking-change-andself-removed-use-addback" class="icon-link toc-link"><span class="visuallyhidden">link</span></a> Breaking change: <code>.andSelf()</code> removed, use <code>.addBack()</code></h4><p>The <code>.andSelf()</code> method was deprecated in jQuery 1.8 and now removed in 3.0 in favor of the <code>.addBack()</code> method, which does a better job of explaining what it does and also accepts an optional selector to filter what is added back.</p> </div> </div> </div> </div> <footer class="clearfix simple"> <div class="constrain"> <div class="row"> <div class="six columns centered"> <h3><span>Books</span></h3> <ul class="books"> <li> <a href="https://www.packtpub.com/web-development/learning-jquery-fourth-edition"> <img src="https://jquery.com/wp-content/themes/jquery/content/books/learning-jquery-4th-ed.jpg" alt="Learning jQuery 4th Edition by Karl Swedberg and Jonathan Chaffer" width="92" height="114" loading="lazy"> Learning jQuery Fourth Edition <cite>Karl Swedberg and Jonathan Chaffer</cite> </a> </li> <li> <a href="https://www.manning.com/books/jquery-in-action-third-edition"> <img src="https://jquery.com/wp-content/themes/jquery/content/books/jquery-in-action.jpg" alt="jQuery in Action by Bear Bibeault, Yehuda Katz, and Aurelio De Rosa" width="92" height="114" loading="lazy"> jQuery in Action <cite>Bear Bibeault, Yehuda Katz, and Aurelio De Rosa</cite> </a> </li> <li> <a href="https://www.syncfusion.com/ebooks/jquery"> <img src="https://jquery.com/wp-content/themes/jquery/content/books/jquery-succinctly.jpg" alt="jQuery Succinctly by Cody Lindley" width="92" height="114" loading="lazy"> jQuery Succinctly <cite>Cody Lindley</cite> </a> </li> </ul> </div> </div> <div id="legal" class="legal"> <ul class="footer-site-links"> <li><a class="icon-pencil" href="https://learn.jquery.com/">Learning Center</a></li> <li><a class="icon-comments" href="https://jquery.com/support/">Chat</a></li> <li><a class="icon-twitter" href="https://twitter.com/jquery">Twitter</a></li> <li><a class="icon-github" href="https://github.com/jquery">GitHub</a></li> </ul> <p class="copyright"> Copyright 2025 <a href="https://openjsf.org/">OpenJS Foundation</a> and jQuery contributors. All rights reserved. See <a href="https://jquery.com/license/">jQuery License</a> for more information. The <a href="https://openjsf.org/">OpenJS Foundation</a> has registered trademarks and uses trademarks. For a list of trademarks of the <a href="https://openjsf.org/">OpenJS Foundation</a>, please see our <a href="https://trademark-policy.openjsf.org/">Trademark Policy</a> and <a href="https://trademark-list.openjsf.org/">Trademark List</a>. Trademarks and logos not indicated on the <a href="https://trademark-list.openjsf.org/">list of OpenJS Foundation trademarks</a> are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them. OpenJS Foundation <a href="https://terms-of-use.openjsf.org/">Terms of Use</a>, <a href="https://privacy-policy.openjsf.org/">Privacy</a>, and <a href="https://www.linuxfoundation.org/cookies">Cookie</a> Policies also apply. </p> <p><a href="https://www.digitalocean.com" class="do-link">Web hosting by Digital Ocean</a> | <a href="https://www.fastly.com/">CDN by Fastly</a> | <a href="https://wordpress.org/" class="wp-link">Powered by WordPress</a></p> </div> </div> </footer> </body> </html>