Lodash _.union() method
What you’ll learn
- How
_.union(...arrays)concatenates many inputs then collapses duplicates. - Why output order follows first-seen slots as arguments are consumed.
- When specialized cousins such as
unionByor _.intersection() fit better. - Try each example in the editor (
?tryit=1,2,3) with Lodash from a CDN.
Prerequisites
Knowing how _.difference() subtracts one list from another clarifies how union differs from pure subtraction workflows.
- You understand primitive equality versus reference equality for objects.
- You can open Try-it labs or run snippets locally.
Overview
_.union is the ergonomic deduped concat—perfect when merging permission lists, unioning CSV ids, or layering fallback arrays.
Variadic merge
Pass two lists or ten—Lodash flattens arguments uniformly before uniq-ing.
Stable survivors
Earlier arrays dominate ordering—great when primary sources should win ties.
Non-destructive
Supplied arrays remain untouched for auditing pipelines.
Syntax
_.union(...arrays)- arrays: two or more arrays (array-like collections are coerced consistently with other Lodash array helpers).
- Returns: new array of unique values ordered by first appearance across the flattened arguments.
Two overlapping lists
Shared values appear once—position follows whichever array contributed the first copy.
import union from "lodash/union";
union([2, 3], [3, 4]);
// → [2, 3, 4]Argument order shapes results
Flipping inputs changes where duplicates anchor—the earlier array wins placement.
import union from "lodash/union";
union([3, 1], [1, 2]);
// → [3, 1, 2]More than two arrays
Spread any arity—Lodash still dedupes globally across the combined sequence.
import union from "lodash/union";
union([10], [20], [10, 30], [30]);
// → [10, 20, 30]📋 _.union vs concat + uniq vs intersection
| API | Outcome | Mental model |
|---|---|---|
_.union(...arrays) | Deduped multiset merge | Combine buckets; duplicates collapse globally |
a.concat(b); _.uniq(...) | Similar output possible | Union bundles flatten + uniq for fewer imports |
_.intersection(...arrays) | Only shared elements | Opposite goal—keep overlap instead of coverage |
_.xor(...arrays) | Symmetric difference flavor | Use when you need toggling membership logic |
Pitfalls to avoid
Reference equality
Distinct object literals never dedupe—compare ids via unionBy when merging rows.
Source precedence
Shuffle inputs accidentally and priority-sensitive merges reorder unexpectedly.
Nested arrays
Union flattens one level when composing arguments—nested grids may need explicit spreads.
❓ FAQ
Summary
- Purpose:
_.union(...arrays)merges arrays then removes duplicates with SameValueZero rules. - Ordering: earliest appearances—in argument order—determine final sequencing.
- Next: Lodash _.unionBy(), _.takeWhile() (previous), or the array methods hub.
When duplicates differ only after an iteratee—say merging user rows by email—use _.unionBy(); raw union compares elements directly with SameValueZero.
About the author
6 people found this page helpful