Ramda.js R.union() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Relation

Definition

Ramda’s R.union() answers a set question: what unique items appear in the first list, the second list, or both? You pass two lists. You get back a new array: first-appearance order from as, then items from bs that are not already in the set. Equality is R.equals, so objects and nested arrays match by value, not by identity. Need a bag that keeps every copy? That is R.concat. Need uniqueness on one list only? That is R.uniq. Need items in both lists? That is R.intersection. Need first minus second? That is R.difference. Need either-not-both? That is R.symmetricDifference. Need a custom match instead of R.equals? That is R.unionWith. Lodash _.union looks similar but uses SameValueZero, so two {a: 1} objects with different identities do not match.

The official sample is the whole idea. Shared 2 and 3 appear once. R.union([1, 2, 3], [2, 3, 4]) is [1, 2, 3, 4]. Swap the lists and you get [2, 3, 4, 1] — the SET of values is the same (1,2,3,4), but the ARRAY order follows whichever list you pass first. Teaching shortcut: union is uniq(concat(as, bs)). Previous helper is R.symmetricDifferenceWith. Next is R.unionWith.

Syntax

Call R.union. Start with this line.

Ramda
R.union(as, bs)
CallWhat it does
R.union(as, bs)Primary signature.
R.union(...)Call the relation helper.

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

Library declarations
Ramda
R.union(as, bs)

Parameters

ParameterDescription
asRequired. Array. The first list. Unique first-appearance items from this list appear first. Not mutated.
bsRequired. Array. The second list. Items not already in the set are appended. Membership uses R.equals.

Return Value

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

Ramda Examples

📚 Getting Started

The official Ramda sample, then unique concat vs concat that keeps a second 2 and 3.

Example 1 — Official Number Sample

Shared 2 and 3 appear once. First-appearance order comes from the first list, then novel items from the second.

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

How It Works

That is the docs sample from ramdajs.com. Walk [1, 2, 3] first: all three are new. Then walk [2, 3, 4]: 2 and 3 are already in the set; 4 is novel, so it is appended.

Example 2 — vs R.concat on the Same Lists

concat keeps a second 2 and 3. union collapses them.

Ramda
R.concat([1, 2, 3], [2, 3, 4]);
//=> [1, 2, 3, 2, 3, 4]

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

How It Works

R.concat is join-only. R.union is that join plus R.uniq. Previous cousin: R.concat.

📈 Practical Patterns

Set cousins on the same pair, objects compared by value, then swap order, duplicates collapse, and a curried leftover.

Example 3 — vs R.intersection, R.difference, and XOR

On [1,2,3] and [2,3,4]: union is the merge, intersection is both, difference is first-minus-second, XOR is either-not-both.

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

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

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

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

How It Works

Union keeps everything unique. Intersection keeps the shared pair. Difference keeps only 1. XOR drops the shared pair and keeps leftovers from both sides. Cousins: R.intersection, R.difference, R.symmetricDifference.

Example 4 — Objects with R.equals

{a: 1} in the first list matches {a: 1} in the second even though they are different object identities. The second copy drops; novel records stay.

Ramda
R.union([{ a: 1 }, { b: 2 }], [{ a: 1 }, { c: 3 }]);
//=> [{ a: 1 }, { b: 2 }, { c: 3 }]
Try It Yourself

How It Works

Membership uses R.equals, not ===. {a: 1} is already in the set from as, so the copy in bs drops. {c: 3} is novel. Lodash _.union would keep all four objects here because SameValueZero does not deep-compare records. Previous helper is R.equals.

Example 5 — Swap Order, Deduping, and Curry

Duplicates collapse. Swap lists to change array order, not membership. Fill the first list and you get a function of the second: const withA = R.union([1, 2, 3]).

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

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

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

How It Works

Extra copies of 1 and 3 collapse because uniq walks the concat. Swapping [2,3,4] first yields the same set with a different array. Because the helper is arity 2, filling one argument leaves a leftover. Need a custom predicate instead of R.equals? That is R.unionWith.

Browser Support

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

Load Ramda 0.1.0 or later via CDN or npm, then call R.union with 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.union() 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.union(as, bs) combines two lists into a set: the first and second lists concatenated, with duplicates removed. Type: [*] → [*] → [*]. Arity 2, curried. Added in v0.1.0.
R.union([1, 2, 3], [2, 3, 4]) returns [1, 2, 3, 4]. Shared 2 and 3 appear once. First-appearance order comes from as, then novel items from bs.
concat keeps duplicates: concat([1,2,3],[2,3,4]) is [1,2,3,2,3,4]. uniq is one list; union is uniq(concat(as, bs)). intersection is items in both lists ([2,3] on the official pair). difference is first minus second ([1]). symmetricDifference is either-not-both ([1,4]). Lodash _.union is similar but uses SameValueZero, not deep equals.
No. Objects and arrays use R.equals (value equality). R.union([{a:1},{b:2}], [{a:1},{c:3}]) is [{a:1},{b:2},{c:3}] because {a:1} matches by value.
The SET of values stays the same (same membership). The ARRAY order changes: first-appearance from the first argument, then novel items from the second. R.union([2,3,4],[1,2,3]) is [2,3,4,1].
No. R.union is a stable Ramda relation helper from v0.1.0. It is not deprecated, experimental, or non-standard.

Continue to R.unionWith()

Learn unique concat of two lists with a custom predicate — official eqA, first-list wins, vs union extra fields, vs concat, and curry leftovers.

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