Ramda.js R.differenceWith() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Relation

Definition

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)
CallWhat 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

ParameterDescription
predRequired. Function. A two-argument predicate. Truthy means the two elements are treated as equal (for membership and leftover uniqueness).
list1Required. Array. The list whose unique leftover items you want. Not mutated. Walked in order.
list2Required. Array. The list of values to exclude. Membership uses pred, not a hard-coded R.equals.

Return Value

Return ValueDescription
ArrayA 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.

Ramda
const cmp = (x, y) => x.a === y.a;
const l1 = [{ a: 1 }, { a: 2 }, { a: 3 }];
const l2 = [{ a: 3 }, { a: 4 }];
R.differenceWith(cmp, l1, l2);
//=> [{ a: 1 }, { a: 2 }]
Try It Yourself

How It Works

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.

Ramda
R.differenceWith(R.equals, [1, 2, 3, 3, 3], []);
//=> [1, 2, 3]

R.differenceWith(R.equals, [1, 2, 3, 3, 3], [1]);
//=> [2, 3]
Try It Yourself

How It Works

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.

Ramda
const cmp = (x, y) => x.a === y.a;
const l1 = [{ a: 1, n: 'x' }, { a: 2, n: 'keep' }];
const l2 = [{ a: 1, n: 'y' }];

R.differenceWith(cmp, l1, l2);
//=> [{ a: 2, n: 'keep' }]

R.difference(l1, l2);
//=> [{ a: 1, n: 'x' }, { a: 2, n: 'keep' }]
Try It Yourself

How It Works

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.

Ramda
const byId = R.eqBy(R.prop('id'));
const users = [
  { id: 1, name: 'Ada' },
  { id: 2, name: 'Grace' },
  { id: 3, name: 'Alan' }
];
const gone = [{ id: 2, name: 'whoever' }];

R.differenceWith(byId, users, gone);
//=> [{ id: 1, name: 'Ada' }, { id: 3, name: 'Alan' }]
Try It Yourself

How It Works

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.

Ramda
const minusById = R.differenceWith((x, y) => x.id === y.id);

minusById([{ id: 1 }, { id: 2 }, { id: 3 }], [{ id: 2 }]);
//=> [{ id: 1 }, { id: 3 }]

R.differenceWith(R.equals, [1, 2, 3, 3, 3])([1]);
//=> [2, 3]
Try It Yourself

How It Works

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.

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 Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All 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.

Continue to R.eqBy()

Learn projection equality — compare two values after mapping them with a function.

R.eqBy() Method →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

6 people found this page helpful