jQuery $.uniqueSort() vs $.unique() Explained

This article breaks down the distinction between jQuery's $.uniqueSort() and $.unique() methods across modern versions of the library. It explains why the jQuery core team introduced $.uniqueSort() in jQuery 3.0, the rationale behind deprecating $.unique(), and how both functions operate identically on arrays of DOM elements while dispelling common misconceptions regarding their behavior on primitive data types.

The Core Difference: Deprecation and Clarity

The primary difference between $.uniqueSort() and $.unique() is naming and deprecation status. In jQuery 3.0, $.uniqueSort() was introduced as the official replacement for $.unique(). The older $.unique() method was officially deprecated, though it remains in the library as an alias pointing directly to $.uniqueSort() to preserve backward compatibility.

Functionally, both methods execute the exact same underlying logic in newer versions of jQuery. When you call $.unique(), jQuery simply forwards the call to $.uniqueSort().

Why jQuery Renamed the Method

The rename was driven by developer confusion over what the method actually does:

  1. Document Order Sorting: The original name $.unique() led developers to believe the function only removed duplicate entries. In reality, the method sorts the array in document order (the order in which elements appear in the DOM) in addition to stripping duplicates.
  2. DOM-Only Limitation: Many developers assumed $.unique() was a general-purpose deduplication function for JavaScript primitives, such as arrays of numbers or strings. It is not. It relies on internal DOM comparison algorithms (like Sizzle's sortOrder / compareDocumentPosition) and only functions reliably on arrays of DOM elements.

By renaming it to $.uniqueSort(), the jQuery team made the sorting behavior explicit and reduced the expectation that it acts as a generic array deduplication utility.

How Modern Usage Compares

Because $.unique() is merely an alias in jQuery 3.0 and newer, both functions behave identically when processing an array of DOM elements:

// Given a set of DOM elements with duplicates
var elements = [
  document.getElementById("item2"),
  document.getElementById("item1"),
  document.getElementById("item2")
];

// Using the modern method
var modernResult = $.uniqueSort(elements);
// Result: [element#item1, element#item2] sorted in DOM order

// Using the deprecated method
var legacyResult = $.unique(elements);
// Result: Exactly the same output, but triggers deprecation notices in migration tools

Primitive Array Handling

Neither $.unique() nor $.uniqueSort() works reliably for arrays of strings or numbers. Passing an array of primitives to either function can yield unpredictable order or fail to remove duplicates entirely.

For non-DOM arrays, modern JavaScript provides native alternatives:

// The proper way to deduplicate generic arrays in modern JavaScript
const numbers = [1, 2, 2, 3, 4, 4, 5];
const uniqueNumbers = [...new Set(numbers)];

Migration Recommendation

When maintaining legacy jQuery codebases or building new features using jQuery 3.0+, replace all occurrences of $.unique() with $.uniqueSort(). This eliminates deprecation warnings (especially when using the jQuery Migrate plugin) and ensures future compatibility should $.unique() be removed in a future major release.