Ramda.js R.mergeDeepWith() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object

Definition

Ramda’s R.mergeDeepWith() answers a nested-merge question: how do I mix two records so inner objects walk together, while I still choose what happens when a field is not two objects? You pass a clash function, then the left object, then the right object. You get a new object. Neither source is mutated.

The official sample is the whole idea. Left has a: true and nested values: [10, 20]. Right has b: true and nested values: [15, 35]. Nested objects mix. The clash function is R.concat, so the arrays join instead of replacing. Need the second array to win with no concat? That is R.mergeDeepRight. Need the clash to see the key name? That is R.mergeDeepWithKey. Need a shallow clash only? That is R.mergeWith.

Syntax

Call R.mergeDeepWith. Start with this line.

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

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

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

Parameters

ParameterDescription
fnRequired. Function. Called as fn(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 nested concat, then the same inputs with mergeDeepRight so the nested array is replaced.

Example 1 — Official concat

Nested objects mix. Nested arrays join. Unique keys a and b are kept.

Ramda
R.mergeDeepWith(R.concat,
  { a: true, c: { values: [10, 20] } },
  { b: true, c: { values: [15, 35] } }
);
//=> { a: true, b: true, c: { values: [10, 20, 15, 35] } }
Try It Yourself

How It Works

c is two objects, so it recurses. values is two arrays, so R.concat runs. That is the docs example from ramdajs.com.

Example 2 — vs R.mergeDeepRight

Same two records. Concat joins the nested list. Right-wins replaces it.

Ramda
const left = { a: true, c: { values: [10, 20] } };
const right = { b: true, c: { values: [15, 35] } };

R.mergeDeepWith(R.concat, left, right);
//=> { a: true, b: true, c: { values: [10, 20, 15, 35] } }
R.mergeDeepRight(left, right);
//=> { a: true, b: true, c: { values: [15, 35] } }
Try It Yourself

How It Works

Both helpers keep a and b. Only the nested array rule changes.

📈 Practical Patterns

Shallow vs deep with R.add, nested max with extra keys, then a curried concat in a pipe.

Example 3 — vs R.mergeWith

Shallow merge calls R.add on the nested objects themselves, which is NaN. Deep merge adds the inner numbers.

Ramda
const left = { a: 1, nest: { x: 2 } };
const right = { a: 3, nest: { x: 4 } };

R.mergeWith(R.add, left, right).nest;
//=> NaN
R.mergeDeepWith(R.add, left, right);
//=> { a: 4, nest: { x: 6 } }
Try It Yourself

How It Works

R.mergeWith never walks inside nest. R.add on two objects is not a number. Deep merge waits until x is two numbers.

Example 4 — Nested Max and Extra Keys

R.max keeps the larger number. Left-only name is still copied. Sources stay unchanged.

Ramda
const left = { score: 10, meta: { hits: 2, name: 'Ada' } };
const right = { score: 7, meta: { hits: 5 } };
const merged = R.mergeDeepWith(R.max, left, right);

merged;
//=> { score: 10, meta: { hits: 5, name: 'Ada' } }
left;
//=> { score: 10, meta: { hits: 2, name: 'Ada' } }
right;
//=> { score: 7, meta: { hits: 5 } }
Try It Yourself

How It Works

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

Example 5 — Curry with pipe

Fix a concat helper first, then read nested tags. Both helpers are data-last.

Ramda
const concatDeep = R.mergeDeepWith(R.concat);
const tagList = R.pipe(
  R.mergeDeepWith(R.concat, { nest: { tags: ['js'] } }),
  R.path(['nest', 'tags'])
);
const extra = { a: ['y'], nest: { tags: ['fp'] } };

concatDeep({ a: ['x'], nest: { tags: ['js'] } }, extra);
//=> { a: ['x', 'y'], nest: { tags: ['js', 'fp'] } }
tagList(extra);
//=> ['js', 'fp']
Try It Yourself

How It Works

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

Browser Support

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

Load Ramda 0.24.0 or later via CDN or npm, then call R.mergeDeepWith with a 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.mergeDeepWith() 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.mergeDeepWith(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(leftValue, rightValue) becomes the stored value. Added in v0.24.0. Neither source object is mutated.
R.mergeDeepWith(R.concat, { a: true, c: { values: [10, 20] } }, { b: true, c: { values: [15, 35] } }) is { a: true, b: true, c: { values: [10, 20, 15, 35] } }. Nested objects mix. Nested arrays are concatenated. a and b exist on only one side and are kept.
Both walk nested plain objects. mergeDeepRight always keeps the right value on a clash. mergeDeepWith lets you pick the clash, so R.concat can join arrays instead of replacing them.
mergeWith is shallow: a nested object clash calls fn on the two objects themselves. mergeDeepWith walks inside those objects first, and only then calls fn on leaves such as numbers or arrays.
No. fn is (leftValue, rightValue) => value. Need the key too? That is R.mergeDeepWithKey.
No. R.mergeDeepWith is a stable Ramda object helper from v0.24.0. It is not deprecated, experimental, or non-standard.

Continue to R.mergeDeepWithKey()

Learn how to deep-merge two objects with a clash function that also receives the key using Ramda R.mergeDeepWithKey().

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