Skip to content
Tutorials Center
My learning

Topics

Lesson 42 of 56 ยท Migration and Performance

What Changed in jQuery 3

See which jQuery APIs were removed or deprecated in version 3, how the slim build and the Migrate plugin work, and how to upgrade old 1.x and 2.x code safely.

You will meet old jQuery code sooner or later: a theme from 2013, a plugin that still calls .live(), a page that loads jQuery 1.11 because nobody dared to touch it. The library has been through three major versions, and each one removed things that earlier tutorials, books and Stack Overflow answers still teach. Knowing what went away, and what replaced it, lets you read that code and upgrade it without guessing.

This lesson walks through the removals and deprecations that matter most, shows how to detect them, introduces the slim build and the jQuery Migrate plugin, and ends with a practical upgrade routine. Everything here applies to the jQuery 3.7.1 build used throughout this course.

Three generations

jQuery 1.x Supports very old browsers, including IE 6 to 8.
jQuery 2.x Same API, but drops old IE for a smaller file.
jQuery 3.x Promises/A+ deferreds, async ready, cleaner API.

Version 1.9 removed the biggest batch of old methods.

1 / 2

What was removed

A removed method no longer exists on $.fn, so calling it throws TypeError: ... is not a function. The table lists the removals you will run into most often, grouped by the release that dropped them.

Removed in API Use instead
1.9 .live() and .die() .on() with a delegated selector
1.9 $.browser, $.browser.version Feature detection
1.9 .toggle(fn1, fn2) click toggling A state variable or .toggleClass()
3.0 .size() the .length property
3.0 .andSelf() .addBack()
3.0 .load(fn), .unload(fn), .error(fn) event shorthands .on("load", fn), .on("pagehide", fn), .on("error", fn)
3.0 jqXHR.success(), .error(), .complete() .done(), .fail(), .always()

Two details are easy to miss. First, .load() still exists in jQuery 3, but only as the AJAX method .load(url) that fetches HTML into an element; the old event shorthand .load(function) is what went away. Second, the unload event itself is discouraged by browsers today. Use pagehide or visibilitychange for cleanup work.

What is deprecated but still works

Deprecated APIs run without error, so they hide in code for years. They are the ones to replace while you have the chance, because a future major version may remove them.

  • .bind(), .unbind(), .delegate(), .undelegate() (3.0): .on() and .off() do everything they do, with one consistent signature. See Handling Events.
  • $.isArray() (3.2): use Array.isArray().
  • $.isFunction(), $.isNumeric(), $.isWindow(), $.type(), $.now(), $.camelCase(), $.nodeName() (3.3): use typeof, Number.isFinite(), Date.now() and plain comparisons.
  • $.trim() (3.5): use String.prototype.trim().
  • $.parseJSON() (3.0): use JSON.parse().
  • $.unique() (3.0): renamed $.uniqueSort() because it sorts in document order.
  • $.proxy() (3.3): use Function.prototype.bind() or an arrow function.

The utility functions lesson covers the helpers that remain worth using, such as $.extend() and $.each().

Which old APIs still exist in jQuery 3.7.1?

Behavior changes you can trip over

Some changes are not removals at all. The code still runs, but it behaves differently.

Deferreds follow Promises/A+. In jQuery 3, .then() callbacks run asynchronously and an exception thrown inside one turns the returned promise into a rejection instead of escaping. Older versions ran callbacks synchronously and let errors bubble out. The promises lesson shows the details.

$(document).ready() is always asynchronous. Even when the DOM is already ready, your callback runs after the current script finishes. Code that relied on a ready handler running immediately must be reordered. The Document Ready lesson explains this.

.width() and .height() return fractions. They no longer round to whole pixels, so values like 100.5 are possible on scaled screens.

Self-closing tags are no longer expanded (3.5). Older versions rewrote <div/> inside a larger HTML string into <div></div>. That rewriting was a security hole, so it was removed. Write full pairs such as <div></div> in HTML strings; $("<div/>") on its own, to create one empty element, still works.

Selectors and ids are stricter. $("#") and other malformed selectors throw. User-controlled ids should be escaped with $.escapeSelector().

The slim build

jQuery ships two builds. jquery.min.js is the full library; jquery.slim.min.js leaves out the AJAX module and the effects module (.animate(), .fadeIn(), .slideUp() and friends). It is smaller to download, and it is the build that Bootstrap 4 used.

Choose slim only when you are certain you never call $.ajax(), .load(), .show("slow") or any animation. A project that later needs one of them fails with a TypeError, so slim is a deliberate optimization, not a default. Note that slim does keep Deferreds and the .show() and .hide() methods (without animation).

The jQuery Migrate plugin

jQuery Migrate is an official companion script. You load it right after jQuery, and it restores many removed APIs and prints a warning to the console each time your code uses one. That makes it a diagnostic tool: it tells you which lines of your site need rewriting.

Migrate restores removed methods and reports them

Never ship Migrate to production permanently. It adds weight and keeps the legacy code alive. Use it during an upgrade, fix every warning, then remove it.

Upgrading from 1.x or 2.x

A calm upgrade follows the same steps almost every time.

  1. Add Migrate after the current jQuery version, with the unminified Migrate build while you debug, and open the console on every important page.
  2. Update jQuery itself to the 3.x release and reload. Anything that now throws is a removed API; Migrate will usually name it.
  3. Fix warnings in order of frequency. Replace .bind() with .on(), .size() with .length, .success() with .done(), and so on. A project-wide search for the names in the tables above finds most of them.
  4. Check your plugins. Old plugins are the usual blockers. See the plugins lesson for how to judge whether a plugin is still maintained.
  5. Remove Migrate and run the pages again. The console should be quiet.

If the jump from 1.x to 3.x feels too large, move to 1.12 or 2.2 first, because those releases already carry deprecation warnings under Migrate 1.4.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when you call .size() in jQuery 3.7.1 without any extra plugin?

    Removed methods no longer exist, so calling them throws a TypeError. .size() was removed in 3.0; use the .length property.
  2. 2. Which statement about .load() in jQuery 3 is correct?

    jQuery 3 removed the event shorthands load, unload and error. The AJAX method that loads HTML into an element is still there, and it is missing from the slim build.
  3. 3. What does the slim build leave out?

    jquery.slim.min.js excludes AJAX and effects such as .animate() and .fadeIn(). Selectors, events and Deferreds are still included.
  4. 4. What is the main purpose of the jQuery Migrate plugin?

    Migrate is a diagnostic aid. It logs a console warning whenever code uses a removed or deprecated API, so you know exactly what to rewrite.

Summary

  • jQuery 1.9 and 3.0 removed .live(), $.browser, .size(), .andSelf(), the load, unload and error event shorthands and jqXHR.success(), .error() and .complete().
  • .bind(), .delegate(), $.trim(), $.isArray(), $.parseJSON() and several $.is* helpers are deprecated: replace them with .on() and native JavaScript.
  • jQuery 3 changed behavior too: Promises/A+ deferreds, asynchronous ready handlers, fractional .width() and no more self-closing tag rewriting.
  • The slim build drops AJAX and effects; use it only when you never need them.
  • Load jQuery Migrate temporarily to find legacy calls, fix the warnings, then remove it.

Next, see how much of this library you can replace with the browser's own APIs: From jQuery to Modern JavaScript.