Ramda.js R.unionWith() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Relation

Definition

Ramda’s R.unionWith() answers a set question with a comparator you choose: what unique items appear in the first list, the second list, or both, according to pred? You pass a two-argument predicate, then two lists. You get back a new array: unique first-appearance items from list1, then items from list2 that have no pred match already in the set. If an element exists in both lists, the first element from the first list will be used — that is the official docs note. R.union always uses R.equals. unionWith lets you pick R.eqBy, a custom (x, y) => pair test, or R.equals itself. Need a bag that keeps every copy? That is R.concat. Need uniqueness on one list only? That is R.uniq or R.uniqWith. Need either-not-both with a custom test? That is R.symmetricDifferenceWith. Need first-minus-second with a custom test? That is R.differenceWith. Lodash _.unionWith is a similar unique concat with a 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: 1 uses the object from l1, even though l2 also has an {a:1}. Then {a:2} from l1. Then novel {a:4} from l2. Previous helper is R.union. Next is R.is.

Syntax

Call R.unionWith. Start with this line.

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

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

Library declarations
Ramda
R.unionWith(pred, list1, list2)

Parameters

ParameterDescription
predRequired. Function. A two-argument predicate. Truthy means the two elements are treated as equal (for membership and uniqueness).
list1Required. Array. The first list. Unique first-appearance items from this list appear first. On a pred match, this list's object is kept. Not mutated.
list2Required. Array. The second list. Items with no pred match already in the set are appended. Membership uses pred, not a hard-coded R.equals.

Return Value

Return ValueDescription
ArrayA new array: the first and second lists concatenated, with duplicates removed according to pred. Empty inputs → [].

Ramda Examples

📚 Getting Started

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

Example 1 — Official eqA on .a

Predicate compares the a property. Shared a: 1 uses the object from l1. Then {a:2} from l1. Then novel {a:4} from l2.

Ramda
const l1 = [{ a: 1 }, { a: 2 }];
const l2 = [{ a: 1 }, { a: 4 }];
R.unionWith(R.eqBy(R.prop('a')), l1, l2);
//=> [{ a: 1 }, { a: 2 }, { a: 4 }]
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: 1 keeps l1’s object. {a:2} is unique to l1. {a:4} is novel in l2.

Example 2 — vs R.union Extra Fields

{a: 1, n: 'x'} and {a: 1, n: 'y'} do not match under whole-value R.equals, so union keeps both a: 1 records. eqA treats a: 1 as one and keeps the first-list record.

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

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

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

How It Works

That is the reason unionWith exists. Extra fields make whole-value mismatch, so R.union keeps both a: 1 records. With eqA, they are one element: the first-list object {a:1,n:'x'} wins, then {a:2}, then novel {a:4}. Full walkthrough of the R.equals cousin: R.union.

📈 Practical Patterns

concat keeps two {a:1} copies, swap-list order changes who wins, then a curried unionByA plus R.equals numbers.

Example 3 — vs R.concat on Official Objects

concat keeps two {a: 1} objects. unionWith collapses them to the first-list copy. Same idea as uniqWith(eqA, concat(l1, l2)).

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

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

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

R.uniqWith(eqA, R.concat(l1, l2));
//=> [{ a: 1 }, { a: 2 }, { a: 4 }]
Try It Yourself

How It Works

R.concat is join-only: two {a:1} copies stay. R.unionWith is that join plus R.uniqWith. Previous cousins: R.concat, R.uniqWith.

Example 4 — Swap Lists (First List Wins)

Membership by pred stays the same. Array order follows whichever list you pass first, and that list’s a: 1 object is the one kept.

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

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

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

How It Works

Reverse the lists and membership is still a: 1, 2, 4, but order starts from the other tray: {a:1} and {a:4} from l2, then novel {a:2} from l1. The first-list object still wins on the shared a: 1. Same idea as swapping arguments to R.union.

Example 5 — Curried Leftover unionByA

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

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

unionByA(l1)(l2);
//=> [{ a: 1 }, { a: 2 }, { a: 4 }]

R.unionWith(R.equals, [1, 2, 3], [2, 3, 4]);
//=> [1, 2, 3, 4]

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

How It Works

Because unionWith is arity 3, filling one argument leaves a leftover of two: unionByA(l1)(l2). Pass R.equals and you recreate R.union([1,2,3],[2,3,4]) → [1,2,3,4]. Lodash would write _.unionWith(l1, l2, eqA) with the comparator last.

Browser Support

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

Load Ramda 0.1.0 or later via CDN or npm, then call R.unionWith 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.unionWith() 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.unionWith(pred, list1, list2) combines two lists into a set of elements from each list. Duplication is determined by the supplied two-argument predicate. Type: ((a, a) → Boolean) → [*] → [*] → [*]. Arity 3, curried. Added in v0.1.0.
With l1 = [{a:1},{a:2}] and l2 = [{a:1},{a:4}], R.unionWith(R.eqBy(R.prop('a')), l1, l2) returns [{a:1},{a:2},{a:4}]. Shared a:1 uses the object from l1. Then {a:2} from l1. Then novel {a:4} from l2.
union always uses R.equals. Extra fields make two a:1 records both survive. unionWith(eqBy(prop('a'))) treats them as one and keeps the first list's record. concat keeps copies: two {a:1} objects stay. uniqWith is unique on one list; unionWith is uniqWith(pred, concat(list1, list2)). Lodash _.unionWith is similar but takes the comparator last.
The first element from the first list. That is the official docs note. Match on pred, then keep list1's object, not list2's copy.
Membership by pred stays the same. Array order and which object wins on a match both follow the first argument. R.unionWith(eqA, l2, l1) on the official pair is [{a:1},{a:4},{a:2}] — l2's a:1 wins because l2 is first.
No. R.unionWith is a stable Ramda relation helper from v0.1.0. It is not deprecated, experimental, or non-standard.

Continue to R.is()

Learn how to ask whether a value is an instance of a constructor with Ramda R.is().

R.is() tutorial →

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