Lodash _.matches() Method

What You’ll Learn

By the end of this tutorial, you’ll build reusable partial-match predicates with Lodash’s _.matches() and use them in filter, find, and conditional checks.

What Is _.matches()?

_.matches() creates a predicate function for partial deep comparison. You describe a pattern object (source); the returned function checks whether another object matches every key you listed—nothing more. Extra fields on the target object are ignored.

If you have ever written _.filter(users, { age: 30 }), you already used matches semantics—Lodash converts that object shorthand internally. Explicit _.matches() lets you store and reuse the same predicate.

📝 Syntax

Pass a pattern object; receive a predicate function:

_.matches(source)

Syntax Rules

• source — plain object describing properties and values to match.
• Return value — a function (object) => boolean.
• Partial — only keys in source are checked; extra target keys are allowed.
• Deep — nested plain objects in source are compared recursively.
• One-off check — use _.isMatch(object, source) when you do not need a reusable predicate.

import matches from "lodash/matches";



const users = [

  { id: 1, name: "John", age: 30 },

  { id: 2, name: "Jane", age: 25 },

];



const isThirty = matches({ age: 30 });



_.filter(users, isThirty);

// [{ id: 1, name: 'John', age: 30 }]

Examples Gallery

Practical _.matches() patterns with copy-ready code, sample output, and interactive Try It Yourself labs.

const users = [

  { id: 1, name: "John", age: 30 },

  { id: 2, name: "Jane", age: 25 },

  { id: 3, name: "Alice", age: 35 },

];



console.log(_.filter(users, _.matches({ age: 30 })));

// [{ id: 1, name: 'John', age: 30 }]

[ { id: 1, name: 'John', age: 30 } ]

const data = [

  { id: 1, name: "John", age: 30 },

  { id: 2, name: "Jane", age: 25 },

];



const matcher = _.matches({ id: 1, name: "John" });



console.log(_.find(data, matcher));

// { id: 1, name: 'John', age: 30 }

{ id: 1, name: 'John', age: 30 }

const records = [

  { id: 1, user: { name: "John", age: 30 } },

  { id: 2, user: { name: "Jane", age: 25 } },

];



const nestedMatcher = _.matches({ user: { name: "John" } });



console.log(_.find(records, nestedMatcher));

// { id: 1, user: { name: 'John', age: 30 } }

{ id: 1, user: { name: 'John', age: 30 } }

const users = [

  { id: 2, name: "Jane", age: 25, city: "NYC" },

  { id: 3, name: "Alice", age: 35 },

];



console.log(_.filter(users, _.matches({ name: "Jane" })));

// Jane matches — id, age, and city are not required



console.log(_.isMatch(users[0], { name: "Jane" }));

// true — one-off check without building a predicate

[ { id: 2, name: 'Jane', age: 25, city: 'NYC' } ]

true

const users = [

  { id: 1, name: "John", age: 30 },

  { id: 2, name: "Jane", age: 25 },

];



const explicit = _.filter(users, _.matches({ age: 30, name: "John" }));

const shorthand = _.filter(users, { age: 30, name: "John" });



console.log(explicit);

console.log(shorthand);

// both: [{ id: 1, name: 'John', age: 30 }]

[ { id: 1, name: 'John', age: 30 } ]

[ { id: 1, name: 'John', age: 30 } ]

const user = { name: "John", age: 30 };

const isAdmin = _.matches({ role: "admin" });



if (isAdmin(user)) {

  console.log("User is an admin");

} else {

  console.log("User is not an admin");

}

// User is not an admin — no role property

User is not an admin

📝 Notes

• Matching is partial—only keys in source matter; extra target properties are fine.
• Nested patterns use nested objects, not dot-path strings like 'user.name'.
• _.filter(arr, { k: v }) and _.filter(arr, _.matches({ k: v })) behave the same.
• Use _.isMatch(obj, pattern) for a single immediate check without storing a predicate.
• For custom validation logic per field (types, ranges), use _.conforms() instead.
• Next in the series: _.matchesProperty() for path + value matching.

💡 Best Practices