Creates a predicate that performs a partial deep comparison against a source object — true when the given object has equivalent values for every listed key. Part of Lodash Util since 3.0.0 (stable — not deprecated).
Note: Equivalent to _.isMatch with source partially applied. Extra keys on the object are ignored.
Call _.matches. Start with this line.
_.matches(source)| Call | What it does |
|---|---|
_.matches(source) | Primary signature. |
_.matches(...) | Call the util helper. |
Prefer import matches from "lodash/matches" when you want a smaller bundle.
_.matches(source)| Parameter | Description |
|---|---|
| source | Required. Object of property values to match |
| Return Value | Description |
|---|---|
| * | Predicate function (object) → boolean |
Keep objects whose listed keys match the source pattern.
var objects = [
{ 'a': 1, 'b': 2, 'c': 3 },
{ 'a': 4, 'b': 5, 'c': 6 }
];
_.filter(objects, _.matches({ 'a': 4, 'c': 6 }));
// → [{ 'a': 4, 'b': 5, 'c': 6 }]a === 4 and c === 6.a is 1 → fails.b is ignored.Same rules as _.isMatch(object, source), as a reusable function.
var isMatchAC = _.matches({ a: 4, c: 6 });
isMatchAC({ a: 4, b: 5, c: 6 });
// → true
isMatchAC({ a: 1, b: 2, c: 3 });
// → false
_.isMatch({ a: 4, b: 5, c: 6 }, { a: 4, c: 6 });
// → true // same comparisonsource.a and c → true.a differs → false._.isMatch is the one-shot form of the same check.Collection methods already treat plain objects as matches predicates.
var objects = [
{ 'a': 1, 'b': 2, 'c': 3 },
{ 'a': 4, 'b': 5, 'c': 6 }
];
_.filter(objects, { 'a': 4, 'c': 6 });
// → [{ 'a': 4, 'b': 5, 'c': 6 }]
_.filter(objects, _.matches({ 'a': 4, 'c': 6 }));
// → same result_.filter is enough._.iteratee → matches._.matches when you reuse the predicate.Official note: empty {} / [] in source match any object / array.
var matchAnyObj = _.matches({ meta: {} });
matchAnyObj({ meta: { x: 1 } });
// → true
matchAnyObj({ meta: {} });
// → true
matchAnyObj({ meta: null });
// → false{} in source means “any object here.”{x:1} and {} pass.null fails the object check.Combine matchers with _.overSome for OR-style patterns.
var objects = [
{ 'a': 1, 'b': 2, 'c': 3 },
{ 'a': 4, 'b': 5, 'c': 6 }
];
_.filter(objects, _.overSome([
_.matches({ 'a': 1 }),
_.matches({ 'a': 4 })
]));
// → both objectsa:1 or a:4._.overSome returns true if any matcher passes._.matches is a Lodash Util helper since 3.0.0. It runs anywhere Lodash 3+ / 4.x runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install lodash.
Available in [email protected] full builds and the lodash/matches modular import. Works in evergreen browsers and current Node LTS when Lodash is installed.
Bottom line: Safe for production once Lodash is loaded. Prefer import matches from "lodash/matches" for smaller bundles. Collection methods already accept object shorthands with the same rules.
Check that one path equals a value — the path-pair iteratee shorthand.
10 people found this page helpful