Creates a predicate that compares the value at a path on an object to a fixed srcValue — true when they are equivalent (deep compare). Part of Lodash Util since 3.2.0 (stable — not deprecated).
Note: The iteratee shorthand is a two-element array [path, value] — same rules as calling _.matchesProperty(path, value).
Call _.matchesProperty. Start with this line.
_.matchesProperty(path, srcValue)| Call | What it does |
|---|---|
_.matchesProperty(path, srcValue) | Primary signature. |
_.matchesProperty(...) | Call the util helper. |
Prefer import matchesProperty from "lodash/matchesProperty" when you want a smaller bundle.
_.matchesProperty(path, srcValue)| Parameter | Description |
|---|---|
| path | Required. String or array path to read |
| srcValue | Required. Value to compare at that path |
| Return Value | Description |
|---|---|
| * | Predicate (object) → boolean |
Find the first object whose path equals the expected value.
var objects = [
{ 'a': 1, 'b': 2, 'c': 3 },
{ 'a': 4, 'b': 5, 'c': 6 }
];
_.find(objects, _.matchesProperty('a', 4));
// → { 'a': 4, 'b': 5, 'c': 6 }_.matchesProperty('a', 4) means “path a equals 4.”a is 1 → skip.a is 4 → match.[path, value]Collection methods accept the two-element array form directly.
var objects = [
{ 'a': 1, 'b': 2, 'c': 3 },
{ 'a': 4, 'b': 5, 'c': 6 }
];
_.find(objects, ['a', 4]);
// → { 'a': 4, 'b': 5, 'c': 6 }
_.find(objects, _.matchesProperty('a', 4));
// → same result['a', 4] is the iteratee form of path + value._.matchesProperty('a', 4).Use a dot path or path array for nested fields.
var users = [
{ user: { name: 'barney', active: true } },
{ user: { name: 'fred', active: false } }
];
_.find(users, _.matchesProperty('user.name', 'fred'));
// → { user: { name: 'fred', active: false } }
_.find(users, _.matchesProperty(['user', 'active'], false));
// → same object'user.name' reads the nested name.['user','active'] is equivalent style for keys.srcValue._.matches object.srcValueOfficial note: empty {} / [] match any object / array at that path.
var hasAnyMeta = _.matchesProperty('meta', {});
hasAnyMeta({ meta: { x: 1 } });
// → true
hasAnyMeta({ meta: {} });
// → true
hasAnyMeta({ meta: null });
// → false{} as srcValue means “any object here.”null fails.Combine matchers with _.overSome for OR-style path checks.
var objects = [
{ 'a': 1, 'b': 2, 'c': 3 },
{ 'a': 4, 'b': 5, 'c': 6 }
];
_.filter(objects, _.overSome([
_.matchesProperty('a', 1),
_.matchesProperty('a', 4)
]));
// → both objectsa === 1 or a === 4._.overSome succeeds if any matcher passes._.matchesProperty is a Lodash Util helper since 3.2.0. It runs anywhere Lodash 3.2+ / 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/matchesProperty 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 matchesProperty from "lodash/matchesProperty" for smaller bundles. Collection methods already accept [path, value] shorthands with the same rules.
Create a function that invokes a method at a path on a given object.
10 people found this page helpful