Lodash _.mergeWith() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object
Decorative image with the word MERGEWITH

Definition

Like _.merge, but accepts a customizer that decides the merged value for each property. Part of Lodash Object since 4.0.0 (stable — not deprecated).

Warning: Mutates the first argument (same as _.merge). Return undefined from the customizer to keep Lodash’s default merge for that key.

Syntax

Call _.mergeWith. Start with this line.

Lodash
_.mergeWith(object, …sources, customizer)
CallWhat it does
_.mergeWith(object, …sources, customizer)Primary signature.
_.mergeWith(object)Work with an object’s keys, values, or paths.

Prefer import mergeWith from "lodash/mergeWith" when you want a smaller bundle.

Library declarations
Lodash
_.mergeWith(object, …sources, customizer)

Parameters

This method has no parameters beyond those shown in the signature.

Return Value

Return ValueDescription
*The mutated destination

Lodash Examples

Example 1 — Official: Concat Arrays

Override array merging so lists concatenate instead of merging by index.

Lodash
function customizer(objValue, srcValue) {
  if (_.isArray(objValue)) {
    return objValue.concat(srcValue);
  }
}

_.mergeWith({ a: [1], b: [2] }, { a: [3], b: [4] }, customizer);
// → { a: [1, 3], b: [2, 4] }
Try It Yourself

How It Works

  1. Detect. Customizer sees dest value is an array.
  2. Concat. Returns objValue.concat(srcValue).
  3. a / b. Become [1,3] and [2,4].
  4. No return. Non-arrays fall through to default merge.

Example 2 — Return undefined (Default Merge)

When the customizer returns nothing useful, Lodash merges by index.

Lodash
_.mergeWith(
  { items: [1, 2, 3] },
  { items: [10] },
  function() { /* returns undefined */ }
);
// → { items: [10, 2, 3] }
Try It Yourself

How It Works

  1. Empty body. Function returns undefined.
  2. Fallback. Default merge applies to items.
  3. Index 0. 1 → 10; rest kept.
  4. Rule. Only return a value when you want to override.

Example 3 — Sum Numbers

Add numeric conflicts; still recurse into nested objects.

Lodash
_.mergeWith(
  { a: 1, b: { c: 2 } },
  { a: 3, b: { c: 4 } },
  function(objValue, srcValue) {
    if (typeof objValue === 'number' && typeof srcValue === 'number') {
      return objValue + srcValue;
    }
  }
);
// → { a: 4, b: { c: 6 } }
Try It Yourself

How It Works

  1. a. Both numbers → customizer returns 1 + 3 = 4.
  2. b. Both objects → undefined → recurse.
  3. b.c. Numbers → 2 + 4 = 6.
  4. Selective. Only number pairs are customized.

Example 4 — Fresh Object + Concat

Start with {} so sources stay unchanged.

Lodash
function concatArrays(objValue, srcValue) {
  if (_.isArray(objValue)) {
    return objValue.concat(srcValue);
  }
}

_.mergeWith({}, { a: [1] }, { a: [2] }, concatArrays);
// → { a: [1, 2] }
Try It Yourself

How It Works

  1. Empty dest. Writes go into a new object.
  2. First source. Seeds a: [1].
  3. Second. Customizer concatenates [2].
  4. Habit. Prefer {} in pure helpers.

Example 5 — mergeWith vs merge

Same inputs: concat vs index overwrite.

Lodash
var left  = { items: [1, 2, 3] };
var right = { items: [10] };

_.merge({}, left, right);
// → { items: [10, 2, 3] }

_.mergeWith({}, left, right, function(o, s) {
  if (_.isArray(o)) return o.concat(s);
});
// → { items: [1, 2, 3, 10] }
Try It Yourself

How It Works

  1. merge. Index 0 becomes 10; length stays 3.
  2. mergeWith. Concat appends 10; length 4.
  3. Pick. Index rules → merge; list append → mergeWith.
  4. Both. Use {} so sources stay clean.
Compatibility

Browser & Runtime Support

_.mergeWith is a Lodash Object helper since 4.0.0. It runs anywhere Lodash runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install lodash.

✓ Stable · Lodash 4.0.0+

_.mergeWith()

Available in [email protected] full builds and the lodash/mergeWith modular import. Works in evergreen browsers and current Node LTS when Lodash is installed.

100% With Lodash 4.0+
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
_.mergeWith Lodash 4.0.0+

Bottom line: Safe for production once Lodash 4+ is loaded. Prefer import mergeWith from "lodash/mergeWith" for smaller bundles. Remember it mutates the destination — and return undefined to keep default merge for a key.

Frequently Asked Questions

_.mergeWith(object, …sources, customizer) deep-merges like _.merge, but calls customizer for each property so you can override how values combine. Official: concat arrays instead of merging by index.
Lodash falls back to its normal merge behavior for that property (recurse into plain objects/arrays, otherwise assign).
Yes. The destination is updated in place and returned. Use _.mergeWith({}, …sources, customizer) for a fresh object.
Typically (objValue, srcValue, key, object, source, stack). Return the merged value, or undefined to let Lodash continue.
_.merge always uses built-in rules (arrays by index). _.mergeWith lets you replace those rules — e.g. concatenate arrays.
Use import mergeWith from "lodash/mergeWith" or require("lodash/mergeWith") for tree-shaking. Full build: import _ from "lodash" then _.mergeWith.

Next: _.omit()

Create an object without the listed paths.

_.omit() 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.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

Lodash _.merge() Method — Deep Merge Objects Lodash _.omit() Method — Omit Object Properties