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)
Call
What 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
Parameter
Description
pred
Required. Function. A two-argument predicate. Truthy means the two elements are treated as equal (for membership and uniqueness).
list1
Required. 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.
list2
Required. 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 Value
Description
Array
A 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.
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.
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)).
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.
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.
Compatibility
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 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.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.