Lodash _.isMatch() method

Beginner
⏱️ 7 min read
📚 Updated: May 2026
🎯 3 Code examples
🚀 3 Try-it labs
Lodash

What you’ll learn

  • How _.isMatch(object, source) performs partial deep matching.
  • How nested objects and arrays are evaluated in source-driven checks.
  • Why missing required keys fail even when many other keys match.
  • When to use _.isMatch versus _.isEqual in validation logic.

Prerequisites

You understand plain objects and basic nested JSON-like data structures.

  • You know the difference between subset checks and full equality checks.
  • Try-it labs load lodash from the CDN.

Overview

Use _.isMatch for feature flags, request payload validation, filter predicates, and rule engines where source describes required fields while allowing additional object data.

Partial matching

Only keys in source are required for success.

Deep by default

Nested objects and arrays are compared recursively.

Missing keys fail

If source demands a field absent in object, result is false.

Syntax

javascript
_.isMatch(object, source)
  • object: value to inspect.
  • source: required property/value subset to compare against.
  • Returns: true if object contains equivalent source properties, otherwise false.
1

Basic subset match

Extra properties in the object do not hurt a successful subset comparison.

javascript
import isMatch from "lodash/isMatch";

var object = { a: 1, b: 2, c: 3 };

console.log(
  "matchB2: " + isMatch(object, { b: 2 }) + "\n" + // true
  "matchB1: " + isMatch(object, { b: 1 })           // false
);
Try it Yourself
2

Nested objects and arrays

Source can target deep structures, including array content.

javascript
import isMatch from "lodash/isMatch";

var object = { profile: { role: "admin", active: true }, tags: ["a", "b"] };

console.log(
  "nestedRole: " + isMatch(object, { profile: { role: "admin" } }) + "\n" + // true
  "tagPrefix: " + isMatch(object, { tags: ["a"] })                           // true
);
Try it Yourself
3

Missing required properties

If source asks for unavailable properties, the match fails.

javascript
import isMatch from "lodash/isMatch";

var object = { id: 100, status: "ok" };

console.log(
  "needsStatus: " + isMatch(object, { status: "ok" }) + "\n" + // true
  "needsType: " + isMatch(object, { type: "service" })         // false
);
Try it Yourself

📋 _.isMatch vs related checks

APIBehavior
_.isMatch(object, source)Partial deep comparison based on source keys.
_.isEqual(a, b)Full deep equality; both structures must fully match.
_.matches(source)Creates a reusable predicate equivalent to partially applying _.isMatch.
===Strict reference/value equality only; no deep object comparison.

Pitfalls to avoid

Subset logic

Unexpected true

If source is too small, many objects may match. Include enough required keys to avoid false positives.

Arrays

Order matters

Array comparison is structural; position changes can affect results.

Validation

Type assumptions

Combine with explicit shape checks when input may be nullish or not object-like.

❓ FAQ

No. It only checks keys present in source. Extra keys in object do not fail the comparison.
_.isEqual compares complete structures both ways. _.isMatch performs subset-style matching from source to object.
Yes. Nested objects are compared deeply, as long as the nested path exists and values are equivalent.
Arrays are compared with deep semantics; source array values are matched structurally at corresponding positions.

Summary

  • Purpose: verify whether an object contains required source properties.
  • Remember: _.isMatch checks subsets, not complete equality.
  • Next: explore more on Lodash _.isMatchWith().
Did you know?

_.isMatch(object, source) is a partial deep comparison: only properties present in source must match, so extra keys in object are ignored.

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)

6 people found this page helpful

Lodash _.isMap() Lodash _.isMatchWith()