Lodash _.isMatchWith() Method

Beginner

5 min read

Updated: Nov 2026

5 examples

Lang

Decorative image with the word ISMATCHWITH

Definition

Like _.isMatch, but accepts a customizer to compare values. If the customizer returns undefined, Lodash handles the comparison. Part of Lodash Lang since 4.0.0 (stable — not deprecated).

Pass the value you want to inspect or convert. Read the return type carefully before you use the result.

Syntax

Call _.isMatchWith. Start with this line.

Lodash

_.isMatchWith(object, source, customizer)

Call	What it does
`_.isMatchWith(object, source, customizer)`	Primary signature.
`_.isMatchWith(value)`	Check, compare, clone, or convert a value.

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

Library declarations

Lodash

_.isMatchWith(object, source, customizer)

Parameters

Parameter	Description
object	Required. The object to inspect
source	Required. Property values that must match
customizer	Optional. Compare values; omit-like when unused (pass a function)

Return Value

Return Value	Description
*	true if object matches source, else false

Lodash Examples

Example 1 — Official: Greeting Customizer

Treat related greeting strings as a match.

Lodash

function isGreeting(value) {
  return /^h(?:i|ello)$/.test(value);
}

function customizer(objValue, srcValue) {
  if (isGreeting(objValue) && isGreeting(srcValue)) {
    return true;
  }
}

var object = { 'greeting': 'hello' };
var source = { 'greeting': 'hi' };

_.isMatchWith(object, source, customizer);
// → true

Try It Yourself

How It Works

Helpers. isGreeting accepts "hi" or "hello".
Customizer. If both values are greetings, return true.
Call. _.isMatchWith compares greeting via your rule.
Result. true even though the strings differ.

Example 2 — Same Data Without Customizer

Default partial match treats the strings as unequal.

Lodash

var object = { greeting: 'hello' };
var source = { greeting: 'hi' };

_.isMatch(object, source);
// → false

_.isMatchWith(object, source, function (objValue, srcValue) {
  if (/^h(?:i|ello)$/.test(objValue) && /^h(?:i|ello)$/.test(srcValue)) {
    return true;
  }
});
// → true

Try It Yourself

How It Works

isMatch. Strict value compare → "hello" !== "hi".
isMatchWith. Customizer overrides that pair.
Partial rules. Both still only check keys in source.
Use. Reach for With when domain rules differ from strict equality.

Example 3 — Return `undefined` for Default Compare

Only override the cases you care about; leave the rest to Lodash.

Lodash

function customizer(objValue, srcValue, key) {
  if (key === 'greeting') {
    return /^h(?:i|ello)$/.test(objValue) &&
           /^h(?:i|ello)$/.test(srcValue);
  }
  // other keys → undefined → default compare
}

var object = { greeting: 'hello', active: true };
var source = { greeting: 'hi', active: true };

_.isMatchWith(object, source, customizer);
// → true

Try It Yourself

How It Works

greeting. Customizer returns a boolean for that key.
active. Customizer returns nothing → default equality.
Both pass. Greeting rule + exact active: true.
Tip. Keep customizers small — override only special keys.

Example 4 — Force a Mismatch With `false`

Returning false rejects a pair even if values look equal.

Lodash

function customizer(objValue, srcValue, key) {
  if (key === 'id') {
    return false; // never treat id as matching here
  }
}

var object = { id: 1, name: 'Ada' };
var source = { id: 1 };

_.isMatchWith(object, source, customizer);
// → false

_.isMatch(object, source);
// → true

Try It Yourself

How It Works

Customizer. For key id, always return false.
Result. Match fails even though both ids are 1.
Contrast. Plain _.isMatch would succeed.
Use sparingly. Force-fail is for explicit business rules.

Example 5 — Case-Insensitive Strings

A common customizer: compare strings without caring about case.

Lodash

function customizer(objValue, srcValue) {
  if (typeof objValue === 'string' && typeof srcValue === 'string') {
    return objValue.toLowerCase() === srcValue.toLowerCase();
  }
}

var object = { city: 'Chennai' };
var source = { city: 'chennai' };

_.isMatchWith(object, source, customizer);
// → true

_.isMatch(object, source);
// → false

Try It Yourself

How It Works

Types. Customizer only special-cases strings.
Normalize. Lowercase both sides before comparing.
Other types. Returning nothing keeps default compare.
Result. "Chennai" matches "chennai".

Compatibility

Browser & Runtime Support

_.isMatchWith is a Lodash Lang helper (available since 4.0.0, stable in 4.x). It runs anywhere Lodash runs — modern browsers (via CDN or bundle) and Node.js / Bun / Deno with npm install lodash.

✓ Stable · Lodash 4.0.0+

_.isMatchWith()

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

100% With Lodash 4.x

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

_.isMatchWith Lodash 4.0.0+

Bottom line: Safe for production once Lodash is on the page or in your bundle. Prefer import isMatchWith from "lodash/isMatchWith" for smaller builds. Use _.isMatch when you do not need a customizer.

Frequently Asked Questions

What does _.isMatchWith() do?

_.isMatchWith(object, source, customizer) is like _.isMatch, but each compared value pair can go through your customizer. Return true to force a match, false to reject, or undefined to use Lodash’s default comparison.

How is it different from _.isMatch?

Same partial-match rules (only source keys matter). The customizer lets you treat related values as equal — for example greeting strings "hello" and "hi".

Which arguments does the customizer receive?

The customizer is invoked with (objValue, srcValue, index|key, object, source).

When is the customizer not called?

If a source key is missing on the object, the match fails in a pre-check before deep comparison — so the customizer may not run for that case.

How does this relate to _.isEqualWith?

Same customization idea. isEqualWith compares whole structures; isMatchWith only checks properties present in source.

How do I import only isMatchWith?

Use import isMatchWith from "lodash/isMatchWith" or require("lodash/isMatchWith"). Full build: import _ from "lodash" then _.isMatchWith.

Next: _.isNaN()

Check whether a value is NaN — Lodash’s version of the classic gotcha.

_.isNaN() tutorial →

About the author

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 _.isMatch() Method Lodash _.isNaN() Method

Lodash _.isMatchWith() Method

Definition

Syntax

Parameters

Return Value

Lodash Examples

Example 1 — Official: Greeting Customizer

How It Works

Example 2 — Same Data Without Customizer

How It Works

Example 3 — Return undefined for Default Compare

How It Works

Example 4 — Force a Mismatch With false

How It Works

Example 5 — Case-Insensitive Strings

How It Works

Browser & Runtime Support

_.isMatchWith()

Frequently Asked Questions

Related Topics

_.isMatch()

_.isEqualWith()

_.isEqual()

_.matches()

_.matchesProperty()

_.conformsTo()

Next: _.isNaN()

About the author

Example 3 — Return `undefined` for Default Compare

Example 4 — Force a Mismatch With `false`