Ramda.js R.mergeWithKey() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object

Definition

Ramda’s R.mergeWithKey() answers a one-level merge question: how do I mix two records so unique keys stay, while the clash rule can still depend on the field name? You pass a clash function of (key, leftValue, rightValue), then the left object, then the right object. You get a new object. Neither source is mutated.

The official sample is the whole idea. concatValues concatenates when the key is values and otherwise keeps the right value. So thing becomes bar and values becomes [10, 20, 15, 35]. Need the same rule on every clash, with no key? That is R.mergeWith. Need nested objects to mix first? That is R.mergeDeepWithKey.

Syntax

Call R.mergeWithKey. Start with this line.

Ramda
R.mergeWithKey(fn, l, r)
CallWhat it does
R.mergeWithKey(fn, l, r)Primary signature.
R.mergeWithKey(...)Call the object helper.

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

Library declarations
Ramda
R.mergeWithKey(fn, l, r)

Parameters

ParameterDescription
fnRequired. Function. Called as fn(key, leftValue, rightValue) when a key exists on both sides.
lRequired. Object. The first record. Own keys that do not exist on the right are copied.
rRequired. Object. The second record. Own keys that do not exist on the left are copied. Nested objects are not walked.

Return Value

Return ValueDescription
ObjectA new object with own properties from both sides. Clash values come from fn. The source objects are not mutated.

Ramda Examples

📚 Getting Started

The official keyed concat, then the same inputs with mergeWith so every clash concatenates.

Example 1 — Official concatValues

values joins. thing keeps the right string. Unique keys a and b stay.

Ramda
const concatValues = (k, l, r) => k == 'values' ? R.concat(l, r) : r;
R.mergeWithKey(concatValues,
  { a: true, thing: 'foo', values: [10, 20] },
  { b: true, thing: 'bar', values: [15, 35] }
);
//=> { a: true, b: true, thing: 'bar', values: [10, 20, 15, 35] }
Try It Yourself

How It Works

The docs use == on the key. That is the sample from ramdajs.com. JSON key order follows left keys first, then right-only b.

Example 2 — vs R.mergeWith

Without the key, R.concat also glues the thing strings.

Ramda
const left = { a: true, thing: 'foo', values: [10, 20] };
const right = { b: true, thing: 'bar', values: [15, 35] };
const concatValues = (k, l, r) => k == 'values' ? R.concat(l, r) : r;

R.mergeWith(R.concat, left, right);
//=> { a: true, b: true, thing: 'foobar', values: [10, 20, 15, 35] }
R.mergeWithKey(concatValues, left, right);
//=> { a: true, b: true, thing: 'bar', values: [10, 20, 15, 35] }
Try It Yourself

How It Works

Both helpers keep a and b and concat the arrays. Only thing changes, because only WithKey can treat that field differently.

📈 Practical Patterns

Shallow vs deep with the same callback, two rules in one walk, then a curried helper in a pipe.

Example 3 — vs R.mergeDeepWithKey

Shallow merge sees key c, not values, so it keeps the whole right nested object. Deep merge still concatenates the inner list.

Ramda
const left = { a: true, c: { thing: 'foo', values: [10, 20] } };
const right = { b: true, c: { thing: 'bar', values: [15, 35] } };
const concatValues = (k, l, r) => k == 'values' ? R.concat(l, r) : r;

R.mergeWithKey(concatValues, left, right);
//=> { a: true, b: true, c: { thing: 'bar', values: [15, 35] } }
R.mergeDeepWithKey(concatValues, left, right);
//=> { a: true, b: true, c: { thing: 'bar', values: [10, 20, 15, 35] } }
Try It Yourself

How It Works

For mergeWithKey, k is c, so the official fallback returns the right nested object and the left 10, 20 never join.

Example 4 — Score, Tags, and Extra Keys

score adds. tags concatenates. Other clashes keep right. Left-only city is still copied.

Ramda
const byKey = (k, l, r) => {
  if (k === 'tags') return R.concat(l, r);
  if (k === 'score') return l + r;
  return r;
};
const left = { score: 10, tags: ['js'], city: 'London' };
const right = { score: 5, tags: ['fp'] };
const merged = R.mergeWithKey(byKey, left, right);

merged;
//=> { score: 15, tags: ['js', 'fp'], city: 'London' }
left;
//=> { score: 10, tags: ['js'], city: 'London' }
right;
//=> { score: 5, tags: ['fp'] }
Try It Yourself

How It Works

The merge copies own keys into a new object. The original left and right objects are not assigned to.

Example 5 — Curry with pipe

Fix the keyed concat helper first, then read values. Label clashes still keep right.

Ramda
const concatValues = (k, l, r) => k == 'values' ? R.concat(l, r) : r;
const mergeLists = R.mergeWithKey(concatValues);
const valueList = R.pipe(
  R.mergeWithKey(concatValues, { values: [10], label: 'seed' }),
  R.prop('values')
);
const extra = { values: [20], label: 'user' };

mergeLists({ values: [10], label: 'seed' }, extra);
//=> { values: [10, 20], label: 'user' }
valueList(extra);
//=> [10, 20]
Try It Yourself

How It Works

R.mergeWithKey(concatValues) waits for two objects. R.mergeWithKey(concatValues, seed) waits for one object, which is why it drops into R.pipe.

Browser Support

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

Load Ramda 0.19.0 or later via CDN or npm, then call R.mergeWithKey with a keyed clash function and two objects. 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.mergeWithKey() 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.mergeWithKey(fn, l, r) returns a new object with own properties from both records. On a clash, fn(key, leftValue, rightValue) becomes the stored value. Unique keys are copied as-is. Added in v0.19.0. Neither source object is mutated. The merge is shallow.
concatValues is (k, l, r) => k == 'values' ? R.concat(l, r) : r. R.mergeWithKey(concatValues, { a: true, thing: 'foo', values: [10, 20] }, { b: true, thing: 'bar', values: [15, 35] }) is { a: true, b: true, thing: 'bar', values: [10, 20, 15, 35] }. values concatenates. thing keeps the right string. a and b exist on only one side and are kept.
Both are shallow. mergeWith calls fn(left, right) and never sees the key, so R.concat would join every clash including thing. mergeWithKey calls fn(key, left, right), so you can concat only values and keep right for everything else.
mergeWithKey is shallow: a nested object clash calls fn on the two nested objects themselves. mergeDeepWithKey walks inside those objects first, and only then calls fn on leaves such as strings or arrays.
No. A key on only one side is copied as-is. fn is for clashes.
No. R.mergeWithKey is a stable Ramda object helper from v0.19.0. It is not deprecated, experimental, or non-standard.

Continue to R.modify()

Learn how to update one property through a function using Ramda R.modify().

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