Ramda.js R.symmetricDifferenceWith() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Relation

Definition

Ramda’s R.symmetricDifferenceWith() answers a set question with a comparator you choose: which unique items sit in either list, but not in both, according to pred? You pass a two-argument predicate, then two lists. You get back a new array: leftovers from list1 that have no pred match in list2, then leftovers from list2 that have no pred match in list1, with leftover duplicates collapsed by that same predicate. R.symmetricDifference always uses R.equals. symmetricDifferenceWith lets you pick R.eqBy, a custom (x, y) => pair test, or R.equals itself. Need only first-minus-second with a custom test? That is R.differenceWith. Need first-minus-second with whole-value equality? That is R.difference. Lodash _.xorWith is a similar XOR-with-comparator; Ramda puts the predicate first so leftovers curry toward the lists.

The official sample is the whole idea. Match on .a and shared a: 3 and a: 4 drop even when the objects are different identities. Leftovers from l1 come first ({a:1}, {a:2}), then leftovers from l2 ({a:5}, {a:6}). Previous helper is R.symmetricDifference. Next is R.union.

Syntax

Call R.symmetricDifferenceWith. Start with this line.

Ramda
R.symmetricDifferenceWith(pred, list1, list2)
CallWhat it does
R.symmetricDifferenceWith(pred, list1, list2)Primary signature.
R.symmetricDifferenceWith(...)Call the relation helper.

Prefer import { symmetricDifferenceWith } from "ramda" when you want a named import.

Library declarations
Ramda
R.symmetricDifferenceWith(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 first list. Unique leftovers from this list appear first. Not mutated. Walked in order.
list2Required. Array. The second list. Unique leftovers from this list are appended. Membership uses pred, not a hard-coded R.equals.

Return Value

Return ValueDescription
ArrayA new array: the set of elements in list1 or list2, but not both, with equality and duplication determined by pred. Empty leftover → [].

Ramda Examples

📚 Getting Started

The official Ramda sample on .a, then extra fields vs whole-value XOR on the same shape.

Example 1 — Official eqA on .a

Predicate compares the a property. Shared a: 3 and a: 4 drop. Leftovers from l1 keep first-appearance order, then leftovers from l2.

Ramda
const eqA = R.eqBy(R.prop('a'));
const l1 = [{ a: 1 }, { a: 2 }, { a: 3 }, { a: 4 }];
const l2 = [{ a: 3 }, { a: 4 }, { a: 5 }, { a: 6 }];
R.symmetricDifferenceWith(eqA, l1, l2);
//=> [{ a: 1 }, { a: 2 }, { a: 5 }, { a: 6 }]
Try It Yourself

How It Works

That is the docs sample from ramdajs.com. pred(item, other) is truthy when a matches. Objects do not need to be the same identity. Shared a: 3 and a: 4 drop. {a:1} and {a:2} are missing from l2; {a:5} and {a:6} are missing from l1.

Example 2 — vs R.symmetricDifference Extra Fields

{a: 1, n: 'x'} and {a: 1, n: 'y'} do not match under whole-value R.equals, so XOR keeps both a: 1 records. eqA treats a: 1 as shared and drops them.

Ramda
const eqA = R.eqBy(R.prop('a'));
const l1 = [{ a: 1, n: 'x' }, { a: 2 }];
const l2 = [{ a: 1, n: 'y' }, { a: 3 }];

R.symmetricDifference(l1, l2);
//=> [{ a: 1, n: 'x' }, { a: 2 }, { a: 1, n: 'y' }, { a: 3 }]

R.symmetricDifferenceWith(eqA, l1, l2);
//=> [{ a: 2 }, { a: 3 }]
Try It Yourself

How It Works

That is the reason symmetricDifferenceWith exists. Extra fields make whole-value mismatch. When those fields should not keep a record alive on both sides, pass a predicate that ignores them. Full walkthrough of the R.equals cousin: R.symmetricDifference.

📈 Practical Patterns

First-minus-second vs XOR on the official lists, swap-list leftover order, then a curried xorByA.

Example 3 — vs R.differenceWith on Official Lists

differenceWith keeps only the first leftover. symmetricDifferenceWith concatenates both leftovers.

Ramda
const eqA = R.eqBy(R.prop('a'));
const l1 = [{ a: 1 }, { a: 2 }, { a: 3 }, { a: 4 }];
const l2 = [{ a: 3 }, { a: 4 }, { a: 5 }, { a: 6 }];

R.differenceWith(eqA, l1, l2);
//=> [{ a: 1 }, { a: 2 }]

R.symmetricDifferenceWith(eqA, l1, l2);
//=> [{ a: 1 }, { a: 2 }, { a: 5 }, { a: 6 }]
Try It Yourself

How It Works

R.differenceWith is first-minus-second: [{a:1},{a:2}]. XOR appends the second leftover [{a:5},{a:6}]. Previous cousin: R.differenceWith.

Example 4 — Swap Lists (Order Changes)

Membership by pred stays the same. Array order follows whichever list you pass first.

Ramda
const eqA = R.eqBy(R.prop('a'));
const l1 = [{ a: 1 }, { a: 2 }, { a: 3 }, { a: 4 }];
const l2 = [{ a: 3 }, { a: 4 }, { a: 5 }, { a: 6 }];

R.symmetricDifferenceWith(eqA, l1, l2);
//=> [{ a: 1 }, { a: 2 }, { a: 5 }, { a: 6 }]

R.symmetricDifferenceWith(eqA, l2, l1);
//=> [{ a: 5 }, { a: 6 }, { a: 1 }, { a: 2 }]
Try It Yourself

How It Works

Reverse the lists and membership is still a: 1, 2, 5, 6, but leftover order starts from the other tray. Same idea as swapping arguments to R.symmetricDifference.

Example 5 — Curried Leftover xorByA

Fill the predicate once. The leftover is a function of two lists. Passing R.equals matches number XOR from R.symmetricDifference.

Ramda
const eqA = R.eqBy(R.prop('a'));
const l1 = [{ a: 1 }, { a: 2 }, { a: 3 }, { a: 4 }];
const l2 = [{ a: 3 }, { a: 4 }, { a: 5 }, { a: 6 }];
const xorByA = R.symmetricDifferenceWith(eqA);

xorByA(l1)(l2);
//=> [{ a: 1 }, { a: 2 }, { a: 5 }, { a: 6 }]

R.symmetricDifferenceWith(R.equals, [1, 2, 3, 4], [7, 6, 5, 4, 3]);
//=> [1, 2, 7, 6, 5]
Try It Yourself

How It Works

Because symmetricDifferenceWith is arity 3, filling one argument leaves a leftover of two: xorByA(l1)(l2). Lodash would write _.xorWith(l1, l2, eqA) with the comparator last. Boolean analog for two flags: R.xor.

Browser Support

R.symmetricDifferenceWith() is ordinary JavaScript once Ramda is loaded. Logos use the shared browser-image-sprite.png sprite from this project.

✓ Ramda 0.19.0+ · Any JS runtime

Ramda.js R.symmetricDifferenceWith()

Load Ramda 0.19.0 or later via CDN or npm, then call R.symmetricDifferenceWith with a predicate and two lists. No extra browser API is required.

100% With Ramda 0.19.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.symmetricDifferenceWith() Universal

Bottom line: Safe in any project that includes Ramda 0.19.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.symmetricDifferenceWith(pred, list1, list2) finds the set of all elements in the first or second list, but not both. Duplication and equality use the supplied two-argument predicate. Type: ((a, a) → Boolean) → [a] → [a] → [a]. Arity 3, curried. Added in v0.19.0.
With eqA = R.eqBy(R.prop('a')), l1 = [{a:1},{a:2},{a:3},{a:4}] and l2 = [{a:3},{a:4},{a:5},{a:6}], R.symmetricDifferenceWith(eqA, l1, l2) is [{a:1},{a:2},{a:5},{a:6}]. Shared a:3 and a:4 drop. Leftovers from l1 first, then leftovers from l2.
symmetricDifference always uses R.equals. Extra fields make whole-value mismatch, so both a:1 records can survive XOR. With(eqBy(prop('a'))) ignores extra fields and treats a:1 as shared. differenceWith is only first-minus-second leftovers; symmetricDifferenceWith concatenates both leftovers (XOR). Lodash _.xorWith is similar but takes the comparator last.
Yes. The result is a unique set according to pred. An item is kept only when pred finds no match in the other list and no match already in that leftover. First-seen order is kept on each side.
The SET of values stays the same according to pred (same membership). The ARRAY order changes: unique leftovers from the first argument, then unique leftovers from the second. So it is not commutative as arrays.
No. R.symmetricDifferenceWith is a stable Ramda relation helper from v0.19.0. It is not deprecated, experimental, or non-standard.

Continue to R.union()

Learn unique concat of two lists with R.equals — official numbers, vs concat and set cousins, objects, and curry leftovers.

R.union() 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