Lodash _.differenceBy() method
What you’ll learn
- How
_.differenceBy(array, ...values, iteratee)excludes items when their projected value matches any projected exclusion. - Using a function, a property path string, or other Lodash iteratee shorthand.
- How this differs from plain
_.differenceand when to reach for_.differenceWith. - Try each example in the editor (
?tryit=1,2,3) with Lodash from a CDN.
Prerequisites
Read _.difference() first; optional skim of Lodash iteratee docs (functions vs property paths).
- You are comfortable with
mapand the idea of comparing a derived field instead of whole objects. - You can run snippets in Node or open the Try-it labs in a browser.
Overview
_.differenceBy is _.difference with an extra iteratee applied to each element before membership is tested. Values from the first array are kept only when their projected value is not found among the projected values from all exclusion arguments.
Match on a key
Typical for deduping records by id, SKU, or email without hand-rolling maps and sets.
Numeric buckets
Pass Math.floor (or similar) so floats that round the same way are treated as equal.
Non-destructive
Original arrays and objects are untouched; the result is a new array of references from the first array.
Syntax
_.differenceBy(array, [values], iteratee)- array: source collection whose elements may be kept or dropped.
- values: zero or more arrays (flattened one level) whose elements contribute to the exclusion set after projection.
- iteratee: function, property path string, or other iteratee shorthand; applied to every compared element.
- Returns: a new array of values from
arraywhose projected value is absent from the projected exclusions.
Compare with Math.floor
Numbers that are not strictly equal can still collide after projection, matching the classic Lodash demo.
import differenceBy from "lodash/differenceBy";
differenceBy([2.1, 1.2], [2.3], Math.floor);
// [1.2]Property path shorthand
A string iteratee picks a field for comparison, so different object instances can still exclude each other.
import differenceBy from "lodash/differenceBy";
differenceBy([{ x: 1 }, { x: 2 }], [{ x: 2 }], "x");
// [{ x: 1 }]Several exclusion lists
Every later array is flattened one level, projected with the same iteratee, and unioned before filtering the first array.
import differenceBy from "lodash/differenceBy";
differenceBy(
[{ id: 1 }, { id: 2 }, { id: 3 }],
[{ id: 2 }],
[{ id: 3 }],
"id"
);
// [{ id: 1 }]📋 differenceBy vs difference vs differenceWith
| Method | Equality rule | Reach for it when |
|---|---|---|
_.difference | SameValueZero on raw elements | Primitives or you already normalized references |
_.differenceBy | SameValueZero on iteratee(value) | One key, path, or projection defines sameness |
_.differenceWith | Custom comparator (a, b) => boolean | Ranges, tolerances, or multi-field rules |
Pitfalls to avoid
Forgetting exclusions are projected too
Objects in later arrays must carry enough shape for the iteratee (for example the same id field) or their projected value may be undefined and fail to match.
Many-to-one projections
If two distinct items map to the same key, excluding that key removes both from consideration even if only one appeared in an exclusion list.
Still not deep equality
You compared one field, not the whole object. Different rows that share an id cannot be told apart after projection.
❓ FAQ
Summary
- Purpose:
_.differenceBy(array, ...values, iteratee)filters the first array using projected SameValueZero membership against projected exclusions. - Safety: inputs are not mutated.
- Next: Lodash _.differenceWith(), _.differenceWith(), or the array methods hub.
The last argument is passed through Lodash’s iteratee shorthand: a string like "user.id" behaves like _.property("user.id"), so nested keys are supported the same way as in _.map or _.sortBy.
About the author
6 people found this page helpful