Lodash _.difference() method
What you’ll learn
- How
_.difference(array, ...values)builds a new array without values that appear in any later argument. - How exclusion lists from multiple arrays are merged before filtering the first array.
- Equality rules (SameValueZero) and when to prefer
differenceBy/differenceWith. - Try each example in the editor (
?tryit=1,2,3) with Lodash from a CDN.
Prerequisites
Comfort with arrays and filter; optional prior reads _.concat() and the array methods hub.
- You understand that comparing objects with
===uses identity, not deep equality. - You can run snippets in Node or open the Try-it labs in a browser.
Overview
_.difference keeps only values from the first array that are not found in the combined elements of every following argument. Order and duplicates from the first array are preserved unless they match an excluded value.
Non-destructive
All inputs stay unchanged; you always get a fresh array instance.
Subtract sets
Typical for “IDs still allowed” after removing blocked IDs, completed tasks, or merged branches.
Shallow equality
Primitives use SameValueZero; objects match only when references are the same.
Syntax
_.difference(array, [values])- array: source collection to filter (array-like values are coerced).
- values: zero or more arrays (or array-like values); each is flattened one level and unioned into the exclusion set.
- Returns: a new array of values from
arraynot present in that exclusion set.
Basic exclusion
Elements from the first array that also appear in the second are removed; remaining order follows the first array.
import difference from "lodash/difference";
difference([2, 1], [2, 3]);
// [1]Several exclusion arrays
Every later argument contributes values to exclude. The result is everything left in the first array after removing that combined set.
import difference from "lodash/difference";
difference([1, 2, 3, 4, 5], [5, 2], [4]);
// [1, 3]Duplicates and order preserved
difference is not uniq: if a value appears twice in the first array and is not excluded, both copies remain in order.
import difference from "lodash/difference";
difference([1, 2, 1, 2], [2]);
// [1, 1]📋 _.difference vs _.without
| API | Best when | Note |
|---|---|---|
_.difference(a, b, c) | Exclusions already live in one or more arrays you can pass through | Later arguments are flattened one level, then unioned |
_.without(a, v1, v2) | You have a short list of literal values to drop | Variadic values, not “array of exclusions” as a single rest spread of nested arrays |
Pitfalls to avoid
Expecting deep equality
Two different object literals with the same keys are still two references. They will not cancel each other in difference.
Shallow flatten on exclusions
Later arguments are flattened only one level before building the exclusion set. Deeply nested lists of IDs may need flatten, flatMap, or a dedicated pipeline before calling difference.
Symmetric difference
difference is directional: only the first array is filtered. For symmetric set math across all inputs, see _.xor.
❓ FAQ
Summary
- Purpose:
_.difference(array, ...values)returns values fromarrayabsent from the union of flattened later arguments. - Safety: inputs are not mutated.
- Next: Lodash _.differenceBy(), _.differenceBy(), or the array methods hub.
_.difference uses SameValueZero equality (like _.indexOf), so NaN can match NaN. For custom equality (for example deep object compares), use _.differenceWith or map first with _.differenceBy.
About the author
6 people found this page helpful