Underscore.js _.matcher() Method

Beginner
5 min read
Updated: Nov 2026
4 examples
Object

Definition

Returns a predicate function that tells you whether a passed-in object contains all of the key/value properties present in attrs (official Underscore docs). Stable helper — not deprecated. Alias: matches.

Pass the required arguments shown below. Underscore object helpers usually return a new value — check whether the source object is mutated.

Syntax

Call _.matcher. Start with this line.

Underscore
_.matcher(attrs) / _.matches(attrs)
CallWhat it does
_.matcher(attrs) / _.matches(attrs)Primary signature.
_.matcher(...)Call with the arguments your case needs.

Load Underscore with import _ from "underscore" (or the UMD CDN build) so these helpers are available as _.

Library declarations
Underscore
_.matcher(attrs) / _.matches(attrs)

Parameters

ParameterDescription
attrsRequired. Key/value pairs that must be present

Return Value

Return ValueDescription
*Predicate function (object) → boolean

Underscore.js Examples

Example 1 — Official: Ready + Filter

Build a reusable predicate and keep only matching items.

Underscore
var list = [
  {id: 1, selected: true,  visible: true},
  {id: 2, selected: true,  visible: false},
  {id: 3, selected: false, visible: true}
];

var ready = _.matcher({selected: true, visible: true});
_.filter(list, ready);
// → [{id: 1, selected: true, visible: true}]
Try It Yourself

How It Works

  1. Attrs. Require selected: true and visible: true.
  2. Predicate. _.matcher returns the ready function.
  3. Filter. _.filter keeps items where ready is true.
  4. Result. Only item id: 1 matches both pairs.

Example 2 — Call the Predicate Directly

You can test one object without a collection helper.

Underscore
var isMoe = _.matcher({name: "moe", age: 50});

isMoe({name: "moe", age: 50});  // → true
isMoe({name: "curly"});         // → false
Try It Yourself

How It Works

  1. Build once. isMoe remembers the required pairs.
  2. Full match. Both name and age match → true.
  3. Incomplete. Missing age → false.
  4. Reuse. Call the same predicate on any later object.

Example 3 — Extra Properties Still Match

The object may have more keys than attrs.

Underscore
var hasRole = _.matcher({role: "admin"});

hasRole({role: "admin", name: "Ada"});  // → true
hasRole({role: "user",  name: "Ada"});  // → false
Try It Yourself

How It Works

  1. Partial check. Only role: "admin" is required.
  2. Extra keys. name does not break the match.
  3. Wrong value. role: "user" fails the predicate.
  4. Pattern. Same idea behind _.where.

Example 4 — _.matcher vs _.isMatch

Same test; different shape — reusable function vs immediate boolean.

Underscore
var obj = {name: "moe", age: 50, stooge: true};
var attrs = {name: "moe", age: 50};

_.matcher(attrs)(obj);     // → true
_.isMatch(obj, attrs);     // → true

// Prefer matcher when you will reuse the test
// Prefer isMatch for a one-line check
Try It Yourself

How It Works

  1. matcher. Returns a function; call it with obj.
  2. isMatch. Takes object + attrs and returns the boolean directly — see _.isMatch.
  3. Same rule. Both check that every pair in attrs is present.
  4. Pick. Reuse across a list → matcher; one check → isMatch.

Browser & Runtime Support

_.matcher (alias _.matches) ships with Underscore.js (1.x). It runs anywhere Underscore runs — modern browsers (CDN or bundle) and Node.js / Bun / Deno with npm install underscore.

✓ Stable · Underscore 1.x

_.matcher()

Available in [email protected] (UMD / ESM). Works in evergreen browsers and current Node LTS when Underscore is loaded.

100% With Underscore 1.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
_.matcher Underscore 1.x+

Bottom line: Safe for production once Underscore is on the page or in your bundle. Not a native browser API by itself — load Underscore first. Prefer a pinned CDN version (e.g. [email protected]).

Frequently Asked Questions

_.matcher(attrs) returns a predicate function. Call that function with an object and it returns true if the object contains every key-value pair from attrs. Extra properties on the object are allowed.
Yes. matches is the documented alias of matcher. Either name refers to the same function.
_.isMatch(object, attrs) answers immediately with true or false. _.matcher(attrs) returns a reusable predicate you can pass to _.filter, _.find, _.reject, and similar helpers.
No. The object only needs to contain all pairs in attrs. Extra keys do not fail. A missing key or a different value does fail.
No. Values use SameValueZero-style checks (like Underscore's isMatch). Nested objects/arrays need the same reference unless you compare with _.isEqual yourself.
No. It is a stable Underscore object helper (alias: matches). Load Underscore 1.x and call _.matcher(attrs).

Next: _.isEqual()

Compare two values with Underscore’s deep equality helper.

_.isEqual() tutorial →

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.

10 people found this page helpful