Lodash _.unionBy() method
What you’ll learn
- How
_.unionBy(...arrays, iteratee)merges collections while treating projected keys as uniqueness fingerprints. - Why the iteratee always trails the arrays you union.
- When plain _.union() or keyed _.intersectionBy() replaces this helper.
- Try each example in the editor (
?tryit=1,2,3) with Lodash from a CDN.
Prerequisites
Comfort with _.union() plus Lodash iteratees ("id", Math.floor, paths) keeps examples approachable.
- You know duplicate detection usually compares projections, not whole object graphs.
- You can open Try-it labs or run snippets locally.
Overview
_.unionBy generalizes union for relational merges—combining API payloads keyed by stable ids without bespoke reduce loops.
Keyed dedupe
Collisions compare iteratee outputs instead of referential slots.
First wins
Earlier arrays keep authority—document that choice when fresher data arrives later.
Immutable inputs
Suppliers remain untouched for reconciliation or retries.
Syntax
_.unionBy(...arrays, iteratee)- arrays: two or more collections merged in order before uniqueness runs.
- iteratee: invoked per element to derive the comparison key (function, property name, path, etc.).
- Returns: deduped array honoring first occurrence per projected key.
Objects merged by id
Later rows sharing an id vanish—the earliest record carries forward unchanged.
import unionBy from "lodash/unionBy";
unionBy(
[{ id: 1, label: "primary" }],
[{ id: 2, role: "backup" }, { id: 1, label: "stale" }],
"id"
);
// → [{ id: 1, label: "primary" }, { id: 2, role: "backup" }]Numeric buckets with Math.floor
Decimals collapse to integer buckets—another duplicate 2.x after the first representative is skipped.
import unionBy from "lodash/unionBy";
unionBy([2.1], [1.2, 2.3], Math.floor);
// → [2.1, 1.2]Three lists, one iteratee
Stack several sources—the iteratee still anchors the tail slot.
import unionBy from "lodash/unionBy";
unionBy([{ k: "a" }], [{ k: "b" }], [{ k: "a", extra: 1 }], "k");
// → [{ k: "a" }, { k: "b" }]📋 _.unionBy vs _.union, _.uniqBy, _.intersectionBy
| API | Inputs | Use case |
|---|---|---|
_.unionBy(...arrays, iteratee) | Multiple arrays | Dedupe merges using projected keys |
_.union(...arrays) | Multiple arrays | Whole-value SameValueZero uniqueness |
_.uniqBy(array, iteratee) | Single array | No cross-array merge—local dedupe only |
_.intersectionBy(...arrays, iteratee) | Multiple arrays | Keep overlap, not union coverage |
Pitfalls to avoid
Iteratee placement
Accidentally passing another array where the iteratee belongs merges nonsense keys.
Freshness policy
First occurrence wins—flip argument order or reverse upstream sorting when newer rows must dominate.
Custom equality
Projections cannot express arbitrary comparators—reach for unionWith when pairwise logic is required.
❓ FAQ
Summary
- Purpose:
_.unionBy(...arrays, iteratee)unions arrays while treating iteratee outputs as uniqueness keys. - Ordering: earlier arguments supply authoritative rows when keys collide.
- Next: Lodash _.unionWith(), _.union() (previous), or the array methods hub.
After mastering projections, _.unionWith() (custom comparator) completes the trio alongside plain union—pick the narrowest tool that still expresses your equality rule.
About the author
6 people found this page helpful