jQuery jQuery.uniqueSort() Method

What You’ll Learn

The jQuery.uniqueSort() utility removes duplicate DOM node references from an array and sorts the remaining elements into document order. This tutorial covers syntax, identity-based deduplication, five worked examples based on the official jQuery API demo, comparisons with $.merge(), and when jQuery.unique() was renamed.

Introduction

When you combine DOM results from multiple jQuery selectors, the same element can appear more than once in your working array. jQuery provides jQuery.uniqueSort() (also written $.uniqueSort()) to clean that list: it strips duplicate node references and orders what remains according to where each element sits in the document.

This is a specialized utility. The jQuery API notes that you will probably never need it directly — jQuery calls it internally — but understanding it helps when you debug selector pipelines or manually merge node arrays before batch DOM updates.

Understanding the jQuery.uniqueSort() Method

jQuery.uniqueSort(array) accepts a native array (or array-like object) whose items are DOM elements. It modifies that array in place, removes entries that point to the same node object twice, and sorts survivors into document order. The return value is the same array reference, now shorter and ordered.

Duplicate detection is strict: only the exact same node counts as a duplicate. Two separate <div> elements with matching classes or ids remain distinct entries. This method does not deduplicate strings, numbers, or plain objects.

📝 Syntax

General form of jQuery.uniqueSort:

jQuery.uniqueSort( array )
// or
$.uniqueSort( array )

Parameters

• array — a native array or array-like object containing DOM elements. This collection is modified in place.

Return value

• Returns the same array reference, now deduplicated and sorted in document order.

Minimal workflow

var nodes = $("div").get();
nodes = nodes.concat($(".highlight").get());
nodes = $.uniqueSort(nodes);

Examples Gallery

Each example uses DOM elements and $.uniqueSort(). Open DevTools or use the Try-it links to run them interactively. Example 1 follows the official jQuery API demo pattern.

// uniqueSort() must take a native array
var divs = $("div").get();

// Add elements matched by .dup (they are divs too)
divs = divs.concat($(".dup").get());

console.log("Pre-uniqueSort:", divs.length);

divs = $.uniqueSort(divs);

console.log("Post-uniqueSort:", divs.length);

Pre-uniqueSort: 8
Post-uniqueSort: 6

var target = document.getElementById("panel");
var nodes = [target, target, target];

console.log("Before:", nodes.length);

$.uniqueSort(nodes);

console.log("After:", nodes.length);
console.log(nodes[0] === target); // true

Before: 3
After: 1
true

var items = $("li.item").get();

console.log("Before:", items.length);

$.uniqueSort(items);

console.log("After:", items.length);
// Still 3 — three distinct node objects in the DOM

Before: 3
After: 3

var nodes = [
  document.querySelector("#third"),
  document.querySelector("#first"),
  document.querySelector("#second")
];

$.uniqueSort(nodes);

console.log(
  nodes.map(function (el) { return el.id; }).join(" → ")
);
// "first → second → third"

first → second → third

var nodes = $("nav a").get();
$.merge(nodes, $(".footer-link").get());

console.log("Merged length:", nodes.length);

$.uniqueSort(nodes);

console.log("Unique length:", nodes.length);

$(nodes).addClass("tracked");

Merged length: 5
Unique length: 4

🚀 Common Use Cases

• Combined selectors — dedupe after merging results from multiple jQuery queries.
• Internal jQuery pipelines — understand how jQuery keeps DOM result sets clean.
• Batch DOM updates — ensure each element is processed once after manual array assembly.
• Plugin development — normalize node lists passed between callbacks in legacy jQuery plugins.
• Document-order guarantees — rely on sorted output before iterating for layout-sensitive work.
• Debugging overlap — inspect array length before/after when selectors unexpectedly double-count nodes.

📝 Notes

• Added in jQuery 1.12 and 2.2; renamed from jQuery.unique() in jQuery 3.0.
• Since jQuery 1.4, results are always sorted in document order.
• Only works on arrays of DOM elements — not strings, numbers, or generic objects.
• Modifies the input array in place; clone first if you need the original list preserved.
• Convert jQuery collections with .get() or .toArray() before calling.
• Chiefly an internal jQuery helper — most application code never calls it directly.

💡 Best Practices