Ramda’s R.differenceWith() answers a set question with a comparator you choose: which unique items are in the first list but not in the second, according to pred? You pass a two-argument predicate, then two lists. You get back a new array: every value from list1 that has no pred match in list2, with leftover duplicates collapsed by that same predicate. R.difference always uses R.equals. differenceWith lets you pick R.eqBy, R.eqProps, a custom x.a === y.a, or R.equals itself. Need items in either list but not both, with a custom test? That is R.symmetricDifferenceWith. Lodash _.differenceWith is a similar subtract-with-comparator; Ramda puts the predicate first so leftovers curry toward the lists.
The official samples are the whole idea. Match on .a and {a: 3} drops even when the objects are different identities. Pass R.equals and [1, 2, 3, 3, 3] minus [] collapses to [1, 2, 3]. Previous helper is R.difference. Next helper is R.eqBy.
Syntax
Call R.differenceWith. Start with this line.
Ramda
R.differenceWith(pred, list1, list2)
Call
What it does
R.differenceWith(pred, list1, list2)
Primary signature.
R.differenceWith(...)
Call the relation helper.
Prefer import { differenceWith } from "ramda" when you want a named import.
Library declarations
Ramda
R.differenceWith(pred, list1, list2)
Parameters
Parameter
Description
pred
Required. Function. A two-argument predicate. Truthy means the two elements are treated as equal (for membership and leftover uniqueness).
list1
Required. Array. The list whose unique leftover items you want. Not mutated. Walked in order.
list2
Required. Array. The list of values to exclude. Membership uses pred, not a hard-coded R.equals.
Return Value
Return Value
Description
Array
A new array: the set of elements in list1 not contained in list2, with equality and duplication determined by pred. Empty leftover → [].
Ramda Examples
📚 Getting Started
The official Ramda samples: a custom .a comparator, then R.equals with an empty second list and set collapse.
Example 1 — Official cmp on .a
Predicate compares the a property. {a: 3} in the first list is excluded because l2 has a record with the same a.
That is the docs sample from ramdajs.com. pred(item, other) is truthy when a matches. {a: 4} only lives in the second list, so it never appears in the leftover. Objects do not need to be the same identity.
Example 2 — Official R.equals Samples
An empty second list still uniq’s the first. Removing 1 also collapses the three 3s into one leftover 3.
Passing R.equals makes differenceWith behave like R.difference for these numbers, plus the docs show the set rule explicitly: three 3s become one. Previous helper is R.difference.
📈 Practical Patterns
Extra fields ignored by cmp vs full R.equals, then eqBy on user ids, then a curried leftover.
Example 3 — vs R.difference Extra Fields
{a: 1, n: 'x'} and {a: 1, n: 'y'} match under a .a comparator. They do not match under whole-value R.equals, so R.difference keeps both shapes.
That is the reason differenceWith exists. When extra keys should not keep a record alive, pass a predicate that ignores them. Full walkthrough of the R.equals cousin: R.difference.
Example 4 — R.eqBy(R.prop('id')) for User Ids
Users match on id even when name in the second list is a different string.
R.eqBy(fn) is a two-argument test: apply fn to both sides, then R.equals. R.eqProps('id') is the same idea for one object key. Pair that with differenceWith when the rest of the record is noise.
Example 5 — Curried Leftover minusById
Fill the predicate once. The leftover is a function of two lists. Arity 3 also lets you fill R.equals and the first list, then pass the second.
Because differenceWith is arity 3, filling one argument leaves a leftover of two. Lodash would write _.differenceWith(users, gone, (x, y) => x.id === y.id) with the comparator last.
Compatibility
Browser Support
R.differenceWith() is ordinary JavaScript once Ramda is loaded. Logos use the shared browser-image-sprite.png sprite from this project.
✓ Ramda 0.1.0+ · Any JS runtime
Ramda.js R.differenceWith()
Load Ramda 0.1.0 or later via CDN or npm, then call R.differenceWith with a predicate and two lists. No extra browser API is required.
100%With Ramda 0.1.0+
Google ChromeAll versions · Desktop & Mobile
Full support
Mozilla FirefoxAll versions · Desktop & Mobile
Full support
Apple SafariAll versions · macOS & iOS
Full support
Microsoft EdgeAll versions · Chromium & Legacy
Full support
Internet ExplorerIE 6+ · Legacy environments
Full support
OperaAll modern versions
Full support
R.differenceWith()Universal
Bottom line: Safe in any project that includes Ramda 0.1.0 or later. Use a CDN build such as ramda.min.js in the browser or install ramda from npm for Node. These labs use [email protected].
Frequently Asked Questions
R.differenceWith(pred, list1, list2) returns the set of all elements in the first list that are not contained in the second. Equality and duplication use the supplied two-argument predicate. Type: ((a, a) → Boolean) → [a] → [a] → [a]. Arity 3, curried. Added in v0.1.0.
With cmp = (x, y) => x.a === y.a, R.differenceWith(cmp, [{a:1},{a:2},{a:3}], [{a:3},{a:4}]) is [{a:1},{a:2}]. R.differenceWith(R.equals, [1,2,3,3,3], []) is [1,2,3]. R.differenceWith(R.equals, [1,2,3,3,3], [1]) is [2,3].
difference always uses R.equals. differenceWith lets you pick the comparator: a custom pair test, R.eqBy, R.eqProps, or R.equals itself. The result is still a set, deduped according to pred. Lodash _.differenceWith is similar but takes the comparator last and uses iteratee-style values.
Yes. An item is kept only when pred finds no match in list2 and no match already in the output. That is why [1,2,3,3,3] minus [] becomes [1,2,3], not five numbers.
No. Order of the two lists matters. differenceWith(pred, A, B) is not the same as differenceWith(pred, B, A) unless the leftover sets happen to match.
No. R.differenceWith is a stable Ramda relation helper from v0.1.0. It is not deprecated, experimental, or non-standard.