From c2306500a1bb4f9d9e9548750f92555c7097fa10 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Mon, 23 Feb 2026 10:34:51 -0500 Subject: [PATCH 1/7] Upgrade: update jQuery 4.0 upgrade guide now that 4.0 is released Fixes gh-258 --- pages/upgrade-guide/4.0.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/pages/upgrade-guide/4.0.md b/pages/upgrade-guide/4.0.md index 724dc24..6ebf8d5 100644 --- a/pages/upgrade-guide/4.0.md +++ b/pages/upgrade-guide/4.0.md @@ -3,9 +3,6 @@ "toc": true } -> [!NOTE] -> jQuery 4.0 is not yet released. This is a draft of the jQuery 4.0 upgrade guide. jQuery 4.0 is currently in development and this guide will be updated as changes are finalized. The jQuery team welcomes feedback on this guide and the changes in jQuery 4.0. - ## Overview With the major version of 4.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. 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. @@ -35,22 +32,32 @@ A new version of the [jQuery Migrate Plugin](https://github.com/jquery/jquery-mi [Version 4.0 of the jQuery Migrate Plugin](https://github.com/jquery/jquery-migrate/#README) *does not* warn about or restore behaviors that were removed in previous major version changes such as jQuery 1.0, 2.0, or 3.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 4.0: -### Start here if currently using jQuery <1.9 +### Start here if currently using jQuery 1.x or 2.x 1. Upgrade the version of jQuery on the page to the latest 1.x or 2.x version. -1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable/#README) to the page. +1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable/) to the page. 1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery. -1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 1.x warning documentation](https://github.com/jquery/jquery-migrate/tree/1.x-stable/warnings.md) as a guide. -1. 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. +1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 1.x warning documentation](https://github.com/jquery/jquery-migrate/tree/1.x-stable/warnings.md) as a guide. +1. Remove the jQuery Migrate 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. + +### Start here if currently using the latest jQuery 1.x or 2.x version -### Start here if currently using jQuery >=1.9 +1. Upgrade the version of jQuery on the page to the latest 3.x version. +1. Add the uncompressed [jQuery Migrate 3.x Plugin](https://github.com/jquery/jquery-migrate/tree/3.x-stable/) to the page. +1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery. +1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 3.x warning documentation](https://github.com/jquery/jquery-migrate/tree/3.x-stable/warnings.md) as a guide. +1. Remove the jQuery Migrate plugin and ensure that the updated jQuery code on the page continues to work properly with only the latest jQuery 3.x in use. + +### Start here if currently using jQuery 3.x 1. Upgrade the version of jQuery on the page to the latest 4.x version. -1. Add the uncompressed [jQuery Migrate 3.6.0 plugin](https://github.com/jquery/jquery-migrate/#README) to the page. jQuery Migrate 4.x will also work with the caveat that it will only support the same browsers as jQuery 4.x, but it is not yet released. +1. Add the uncompressed [jQuery Migrate 4.x plugin](https://github.com/jquery/jquery-migrate/) to the page. 1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery. 1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 4.x warning documentation](https://github.com/jquery/jquery-migrate/blob/master/warnings.md) as a guide. Report any bugs in third-party plugins to the plugin authors. +1. Remove the jQuery Migrate plugin and ensure that the updated jQuery code on the page continues to work properly with only the latest jQuery 4.x in use. -**Note:** Once jQuery 4.x is released, the jQuery Migrate 3.x plugin will be in maintenance mode and will only receive updates for critical bugs. This guide will be updated to reflect that change. +> [!Note] +> jQuery Migrate 1.x, 2.x, and 3.x are in maintenance mode and will only receive updates for critical bugs. jQuery Migrate 3.x can be used to migrate to the latest jQuery 3.x if support for older browsers is needed. **Running multiple version of jQuery Migrate simultaneously is not supported.** @@ -66,11 +73,11 @@ Changes are listed by their component category, and prefixed with a description * **Breaking change:** This change *may* 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. * **Feature:** 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. -* **Deprecated:** 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. +* **Deprecated:** This feature or API is still present in jQuery 4.0, but its use is discouraged. It may be removed in a future major-version update. 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. -For a complete and detailed list of all code changes, see the 3.0 milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0) or the [version diff](https://github.com/jquery/jquery/compare/3.7.1...4.0.0). +For a complete and detailed list of all code changes, see the milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0) or the [version diff](https://github.com/jquery/jquery/compare/3.7.1...4.0.0). ### Ajax @@ -175,10 +182,12 @@ jQuery's source code has been converted to use ES modules instead of AMD modules #### Breaking change: `px` no longer automatically added to most unitless values -jQuery 4.0 switches strategies when it comes to setting CSS properties that require units. Previously, jQuery would automatically add `px` to unitless values, with some exceptions. This behavior has been removed in jQuery 4.0. +jQuery 4.0 switches strategies when it comes to setting CSS properties that require units. Previously, jQuery would automatically add `px` to unitless values, with some exceptions. The old stragey did not properly handle new CSS properties that had been added to the CSS spec since jQuery's release and the "exceptions" list was growing fast. That behavior has been removed in jQuery 4.0. Instead, jQuery will now only add `px` to a limited set of properties that are known to require it. This change may affect existing code that relies on the old behavior. +We encourage all users to explicitly specify units for CSS properties that require them, as this is the standard way of working with CSS and will help avoid any issues with future versions of jQuery. If the old behavior is still needed, see [the docs](https://api.jquery.com/css/#css-propertyName-value) for the current list of properties to which jQuery will automatically add `px`. + #### Breaking change: Remove opacity CSS hook `.css( "opacity" )` will now return an empty string for detached elements in standard-compliant browsers and "1" in IE. That behavior is shared by most other CSS properties, but may affect existing code relying on a return value of "1". From 76c3b457af0ea8f463f105521ab4f284d92e0115 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Thu, 12 Mar 2026 11:23:52 -0400 Subject: [PATCH 2/7] fixup! apply suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Gołębiowski-Owczarek --- pages/upgrade-guide/4.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/upgrade-guide/4.0.md b/pages/upgrade-guide/4.0.md index 6ebf8d5..6cd3998 100644 --- a/pages/upgrade-guide/4.0.md +++ b/pages/upgrade-guide/4.0.md @@ -35,7 +35,7 @@ A new version of the [jQuery Migrate Plugin](https://github.com/jquery/jquery-mi ### Start here if currently using jQuery 1.x or 2.x 1. Upgrade the version of jQuery on the page to the latest 1.x or 2.x version. -1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable/) to the page. +1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable) to the page. 1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery. 1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 1.x warning documentation](https://github.com/jquery/jquery-migrate/tree/1.x-stable/warnings.md) as a guide. 1. Remove the jQuery Migrate 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. @@ -43,7 +43,7 @@ A new version of the [jQuery Migrate Plugin](https://github.com/jquery/jquery-mi ### Start here if currently using the latest jQuery 1.x or 2.x version 1. Upgrade the version of jQuery on the page to the latest 3.x version. -1. Add the uncompressed [jQuery Migrate 3.x Plugin](https://github.com/jquery/jquery-migrate/tree/3.x-stable/) to the page. +1. Add the uncompressed [jQuery Migrate 3.x Plugin](https://github.com/jquery/jquery-migrate/tree/3.x-stable) to the page. 1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery. 1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 3.x warning documentation](https://github.com/jquery/jquery-migrate/tree/3.x-stable/warnings.md) as a guide. 1. Remove the jQuery Migrate plugin and ensure that the updated jQuery code on the page continues to work properly with only the latest jQuery 3.x in use. From 5ab676a642de62928eb420ccf077c404e8f90304 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Thu, 12 Mar 2026 11:24:45 -0400 Subject: [PATCH 3/7] fixup! address feedback --- pages/upgrade-guide/4.0.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pages/upgrade-guide/4.0.md b/pages/upgrade-guide/4.0.md index 6cd3998..3c56e3e 100644 --- a/pages/upgrade-guide/4.0.md +++ b/pages/upgrade-guide/4.0.md @@ -57,7 +57,7 @@ A new version of the [jQuery Migrate Plugin](https://github.com/jquery/jquery-mi 1. Remove the jQuery Migrate plugin and ensure that the updated jQuery code on the page continues to work properly with only the latest jQuery 4.x in use. > [!Note] -> jQuery Migrate 1.x, 2.x, and 3.x are in maintenance mode and will only receive updates for critical bugs. jQuery Migrate 3.x can be used to migrate to the latest jQuery 3.x if support for older browsers is needed. +> jQuery Migrate 1.x and 3.x are in maintenance mode and will only receive updates for critical bugs. jQuery Migrate 3.x can be used to migrate to the latest jQuery 3.x if support for older browsers is needed. **Running multiple version of jQuery Migrate simultaneously is not supported.** @@ -77,7 +77,9 @@ Changes are listed by their component category, and prefixed with a description 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. -For a complete and detailed list of all code changes, see the milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0) or the [version diff](https://github.com/jquery/jquery/compare/3.7.1...4.0.0). +For a complete and detailed list of all code changes, see the milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0) or the [GitHub changelog](https://github.com/jquery/jquery/compare/3.7.1...4.0.0). + +jQuery 4.0.0 is compatible with jQuery UI 1.13.3 or older. ### Ajax From 76d15f84efa5c35ff8ba427955777b2b98cfb385 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Fri, 13 Mar 2026 10:19:49 -0400 Subject: [PATCH 4/7] fixup! remove changelog link; just link milestone --- pages/upgrade-guide/4.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/upgrade-guide/4.0.md b/pages/upgrade-guide/4.0.md index 3c56e3e..b92f675 100644 --- a/pages/upgrade-guide/4.0.md +++ b/pages/upgrade-guide/4.0.md @@ -77,7 +77,7 @@ Changes are listed by their component category, and prefixed with a description 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. -For a complete and detailed list of all code changes, see the milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0) or the [GitHub changelog](https://github.com/jquery/jquery/compare/3.7.1...4.0.0). +For a complete and detailed list of all code changes, see the milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0). jQuery 4.0.0 is compatible with jQuery UI 1.13.3 or older. From 113d27051e47b821df26d9c183ef636f9277d3a8 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Fri, 13 Mar 2026 11:04:31 -0400 Subject: [PATCH 5/7] fixup! add note about the new factory entry point Fixes gh-262 --- pages/upgrade-guide/4.0.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/pages/upgrade-guide/4.0.md b/pages/upgrade-guide/4.0.md index b92f675..1c30c76 100644 --- a/pages/upgrade-guide/4.0.md +++ b/pages/upgrade-guide/4.0.md @@ -176,6 +176,20 @@ The slim build of jQuery 4.0 no longer includes the `callbacks`, `deferred`, and jQuery exports multiple builds that can be used in different environments. This includes the default build as both a universal module (UMD) and an ESM module, the slim build in UMD and ESM, and a factory build for running jQuery with DOM emulators like JSDOM. The `exports` field in `package.json` is used to specify which build is used in different environments. This change should not affect existing code in most cases, but it is an important fix to ensure that jQuery can be used in a wider range of environments. +##### Potentially breaking change: Node.js without a DOM window requires the factory entry point + +In jQuery 3.x, `require("jquery")` in a Node.js environment without a global `document` (e.g., when using JSDOM) returned a factory function that accepted a `window` argument. In jQuery 4.0, the CommonJS wrapper no longer does this. Instead, use the dedicated factory entry point: + +```js +// jQuery 3.x +const jQuery = require( "jquery" )( window ); + +// jQuery 4.0 +const jQuery = require( "jquery/factory" )( window ); +``` + +A `jquery/factory-slim` entry point is also available. Alternatively, if you attach the JSDOM window to `globalThis` before importing jQuery, `require("jquery")` will continue to work. + #### Potentially breaking change: jQuery's source is no longer written using AMD modules jQuery's source code has been converted to use ES modules instead of AMD modules. While this has several advantages, some users may have been importing jQuery's source directly using AMD loaders such as RequireJS. This change may affect those users, but it is expected that most users will be able to continue using jQuery without any issues. The main jQuery file is still built as a UMD module, so it can be used in both AMD and non-AMD environments. From 94511e7d183aa085abc29cd4f226ad0552ffc404 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Fri, 13 Mar 2026 11:07:30 -0400 Subject: [PATCH 6/7] fixup! newer --- pages/upgrade-guide/4.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/upgrade-guide/4.0.md b/pages/upgrade-guide/4.0.md index 1c30c76..c6fa5a1 100644 --- a/pages/upgrade-guide/4.0.md +++ b/pages/upgrade-guide/4.0.md @@ -79,7 +79,7 @@ Remember that the jQuery Migrate plugin described above can detect and warn abou For a complete and detailed list of all code changes, see the milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0). -jQuery 4.0.0 is compatible with jQuery UI 1.13.3 or older. +jQuery 4.0.0 is compatible with jQuery UI 1.13.3 or newer. ### Ajax From bb95b27c5ed3feeec97ab31aa0b19e46c71a7d22 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Fri, 13 Mar 2026 11:36:30 -0400 Subject: [PATCH 7/7] fixup! da window --- pages/upgrade-guide/4.0.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/pages/upgrade-guide/4.0.md b/pages/upgrade-guide/4.0.md index c6fa5a1..2983cf1 100644 --- a/pages/upgrade-guide/4.0.md +++ b/pages/upgrade-guide/4.0.md @@ -178,7 +178,9 @@ jQuery exports multiple builds that can be used in different environments. This ##### Potentially breaking change: Node.js without a DOM window requires the factory entry point -In jQuery 3.x, `require("jquery")` in a Node.js environment without a global `document` (e.g., when using JSDOM) returned a factory function that accepted a `window` argument. In jQuery 4.0, the CommonJS wrapper no longer does this. Instead, use the dedicated factory entry point: +Wherever jQuery is used, it requires a `window` with a proper `document`, which does not exist by default in Node.js and related environments. Tools like JSDOM can be used to create a fake `window` and `document` in Node.js, but the way jQuery can be imported in these environments has changed in jQuery 4.0. + +In jQuery 3.x, `require("jquery")` in a Node.js environment without a global `window` returned a factory function that accepted a `window` argument. In jQuery 4.0, the CommonJS wrapper no longer does this. Instead, use the dedicated factory entry point: ```js // jQuery 3.x @@ -188,7 +190,9 @@ const jQuery = require( "jquery" )( window ); const jQuery = require( "jquery/factory" )( window ); ``` -A `jquery/factory-slim` entry point is also available. Alternatively, if you attach the JSDOM window to `globalThis` before importing jQuery, `require("jquery")` will continue to work. +A `jquery/factory-slim` entry point is also available. + +Alternatively, if you attach the JSDOM `window` to `globalThis` before importing or requiring jQuery, it will work without the factory entry point. #### Potentially breaking change: jQuery's source is no longer written using AMD modules