Ramda.js R.mergeDeepWithKey() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object

Definition

Ramda’s R.mergeDeepWithKey() answers a nested-merge question: how do I mix two records so inner objects walk together, 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. Nested c objects mix, so thing becomes bar and values becomes [10, 20, 15, 35]. Need the same rule on every leaf, with no key? That is R.mergeDeepWith. Need a shallow clash that sees the key? That is R.mergeWithKey.

Syntax

Call R.mergeDeepWithKey. Start with this line.

Ramda
R.mergeDeepWithKey(fn, lObj, rObj)
CallWhat it does
R.mergeDeepWithKey(fn, lObj, rObj)Primary signature.
R.mergeDeepWithKey(...)Call the object helper.

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

Library declarations
Ramda
R.mergeDeepWithKey(fn, lObj, rObj)

Parameters

ParameterDescription
fnRequired. Function. Called as fn(key, leftValue, rightValue) when a key exists on both sides and the values are not two plain objects.
lObjRequired. Object. The first record. Own keys that do not exist on the right are copied.
rObjRequired. Object. The second record. Own keys that do not exist on the left are copied. Nested objects still merge.

Return Value

Return ValueDescription
ObjectA new object with own properties from both sides. Nested plain objects are merged recursively. Leaf clashes use fn. The source objects are not mutated.

Ramda Examples

📚 Getting Started

The official keyed concat, then the same inputs with mergeDeepWith so every leaf concatenates.

Example 1 — Official concatValues

Nested objects mix. values joins. thing keeps the right string.

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

How It Works

The docs use == on the key. c is two objects, so it recurses before fn runs. That is the sample from ramdajs.com.

Example 2 — vs R.mergeDeepWith

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

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.mergeDeepWith(R.concat, left, right);
//=> { a: true, b: true, c: { thing: 'foobar', values: [10, 20, 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

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.mergeWithKey

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, info: { tags: ['js'], city: 'London' } };
const right = { score: 5, info: { tags: ['fp'] } };
const merged = R.mergeDeepWithKey(byKey, left, right);

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

How It Works

Recursion only copies nested objects into a new object. The original left.info object is not assigned to.

Example 5 — Curry with pipe

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

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

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

How It Works

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

Browser Support

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

✓ Ramda 0.24.0+ · Any JS runtime

Ramda.js R.mergeDeepWithKey()

Load Ramda 0.24.0 or later via CDN or npm, then call R.mergeDeepWithKey with a keyed clash function and two objects. No extra browser API is required.

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

Bottom line: Safe in any project that includes Ramda 0.24.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.mergeDeepWithKey(fn, lObj, rObj) returns a new object with own properties from both records. Nested plain objects are merged recursively. On a clash that is not two objects, fn(key, leftValue, rightValue) becomes the stored value. Added in v0.24.0. Neither source object is mutated.
concatValues is (k, l, r) => k == 'values' ? R.concat(l, r) : r. R.mergeDeepWithKey(concatValues, { a: true, c: { thing: 'foo', values: [10, 20] } }, { b: true, c: { thing: 'bar', values: [15, 35] } }) is { a: true, b: true, c: { thing: 'bar', values: [10, 20, 15, 35] } }. Nested objects mix. values concatenates. thing keeps the right string. a and b exist on only one side and are kept.
Both walk nested plain objects. mergeDeepWith calls fn(left, right) and never sees the key, so R.concat would join every leaf including thing. mergeDeepWithKey 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 that are not two plain objects.
No. R.mergeDeepWithKey is a stable Ramda object helper from v0.24.0. It is not deprecated, experimental, or non-standard.

Continue to R.mergeLeft()

Learn how to overlay two objects in one shallow pass so the first record wins using Ramda R.mergeLeft().

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