Lodash _.unionWith() method

Beginner
⏱️ 6 min read
📚 Updated: May 2026
🎯 3 Code examples
🚀 3 Try-it labs
Lodash

What you’ll learn

  • How _.unionWith(...arrays, comparator) unions arrays using pairwise equality you define.
  • When to plug in _.isEqual versus a lightweight field comparison.
  • How this differs from _.union() (SameValueZero) and _.unionBy() (iteratee keys).
  • Try each example in the editor (?tryit=1, 2, 3) with Lodash from a CDN.

Prerequisites

Skim _.differenceWith() for the same comparator contract applied to subtraction instead of merging.

  • You can write pure binary predicates without hidden mutable state.
  • You can open Try-it labs or run snippets locally.

Overview

_.unionWith is the escape hatch when equality is contextual—timestamp tolerances, deep structural matches, or composite business keys too expressive for a simple iteratee.

Custom equality

Any comparator Lodash accepts elsewhere works here—no forced projections.

Deterministic winners

Earlier arguments keep their rows—plan merges when freshness matters.

Immutable sources

Inputs remain pristine for retries or alternate comparators.

Syntax

javascript
_.unionWith(...arrays, comparator)
  • arrays: collections merged sequentially before uniqueness runs.
  • comparator: invoked as (arrVal, othVal); truthy means treat the pair as duplicates.
  • Returns: new array containing first occurrences under your comparator.
1

Match rows by shared sku

Different object shapes still collide when the comparator narrows on a stable identifier.

javascript
import unionWith from "lodash/unionWith";

unionWith(
  [{ sku: "A1", qty: 5 }],
  [{ sku: "B2" }, { sku: "A1", note: "duplicate" }],
  (a, b) => a.sku === b.sku
);
// → [{ sku: "A1", qty: 5 }, { sku: "B2" }]
Try it Yourself
2

Deep structure with _.isEqual

Nested literals that fail reference equality still collapse when Lodash deems them deeply equivalent.

javascript
import unionWith from "lodash/unionWith";
import isEqual from "lodash/isEqual";

unionWith(
  [{ id: 7, meta: { tier: "gold" } }],
  [{ id: 9 }, { id: 7, meta: { tier: "gold" } }],
  isEqual
);
// → [{ id: 7, meta: { tier: "gold" } }, { id: 9 }]
Try it Yourself
3

Several arrays, one comparator

Variadic unions behave like union; only the terminal comparator differs.

javascript
import unionWith from "lodash/unionWith";

unionWith([{ x: 1 }], [{ x: 2 }], [{ x: 1, flag: true }], (a, b) => a.x === b.x);
// → [{ x: 1 }, { x: 2 }]
Try it Yourself

📋 _.unionWith vs union, unionBy, uniqWith

APIEquality signalBest when
_.unionWith(...arrays, comparator)Binary predicateCustom rules spanning multiple inputs
_.union(...arrays)SameValueZero on elementsPrimitives or reference-stable rows
_.unionBy(...arrays, iteratee)Projected keysSingle-field uniqueness suffices
_.uniqWith(array, comparator)Binary predicateOnly one array needs deduping

Pitfalls to avoid

Perf

Comparator cost

Rich predicates can dominate runtime on large merges—profile before shipping hot paths.

Logic

Asymmetry surprises

Odd comparators that are not symmetric cause confusing merges; keep predicates predictable.

Fresh

Stale winners

Remember first occurrence wins—swap argument order or sort upstream when newer payloads must replace older twins.

❓ FAQ

No. Lodash returns a new deduped array; sources remain unchanged.
Return a truthy value when the two arguments should be treated as duplicates for union purposes. Symmetric comparisons yield the least surprising merges.
Always last—after every array you wish to merge—just like other Lodash *With collection helpers.
The earliest element in combined argument order wins; later matches are skipped.
Use import unionWith from "lodash/unionWith" or require("lodash/unionWith") for tree-shaken bundles.

Summary

Did you know?

The comparator mirrors _.differenceWith(): return a truthy value when two candidates should count as the same logical element—even if their references differ.

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

6 people found this page helpful

Lodash _.unionBy() Lodash _.uniq()