Underscore.js _.isMatch() Method

Beginner
5 min read
Updated: Nov 2026
4 examples
Object

Definition

Tells you if the keys and values in properties are contained in object (official Underscore docs). Extra keys on the object do not fail the test.

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

Syntax

Call _.isMatch. Start with this line.

Underscore
_.isMatch(object, properties)
CallWhat it does
_.isMatch(object, properties)Primary signature.
_.isMatch(...)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
_.isMatch(object, properties)

Parameters

ParameterDescription
objectRequired. Value being tested
propertiesRequired. Key/value pairs that must be contained

Return Value

Return ValueDescription
*true or false

Underscore.js Examples

Example 1 — Official Docs

Ask whether a stooge object contains age: 32. Extra fields like name are ignored.

Underscore
var stooge = { name: "moe", age: 32 };

_.isMatch(stooge, { age: 32 });
// → true

_.isMatch(stooge, { age: 40 });
// → false
Try It Yourself

How It Works

  1. Spec { age: 32 }. Object has that pair → true.
  2. name. Extra key on the object — ignored.
  3. age: 40. Wrong value → false.
  4. Takeaway. Containment, not full equality.

Example 2 — Extra Properties

The object only has to contain the spec. Extra keys like age and job do not fail.

Underscore
var moe = { name: "moe", age: 32, job: "comedian" };

console.log(_.isMatch(moe, { name: "moe" }));    // true
console.log(_.isMatch(moe, { name: "curly" }));  // false
Try It Yourself

How It Works

  1. name: "moe". Present and equal → passes.
  2. Extra keys. age and job do not matter.
  3. name: "curly". Wrong value → fails.
  4. Rule. Spec keys must match; object may have more.

Example 3 — Several Pairs

Every key in the spec is required. One mismatch fails the whole test.

Underscore
var task = { name: "Draft", selected: true, visible: true };

console.log(_.isMatch(task, { selected: true, visible: true }));  // true
console.log(_.isMatch(task, { selected: true, visible: false })); // false
Try It Yourself

How It Works

  1. Both true. Every required pair matches → true.
  2. visible: false. One mismatch fails the whole spec.
  3. Reuse. Same idea as _.matcher for filters.
  4. Takeaway. Spec is an AND of all pairs.

Example 4 — vs _.isEqual

A partial spec passes isMatch and fails isEqual because extra keys are not allowed there.

Underscore
var moe = { name: "moe", age: 32 };

console.log(_.isMatch(moe, { name: "moe" }));  // true
console.log(_.isEqual(moe, { name: "moe" }));  // false
Try It Yourself

How It Works

  1. isMatch. Partial — age ignored → true.
  2. isEqual. Full deep equality — shapes differ → false.
  3. Pick the tool. Containment vs sameness.
  4. Related. See _.isEqual.

Browser & Runtime Support

_.isMatch 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

_.isMatch()

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
_.isMatch Underscore 1.x+

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

Frequently Asked Questions

_.isMatch(object, properties) returns true when object contains every key-value pair from properties. Extra keys on the object are allowed. It answers immediately with a boolean — it does not return a function.
Given stooge = {name: "moe", age: 32}, _.isMatch(stooge, {age: 32}) returns true. The object contains the required pair; name is ignored.
_.isMatch(object, properties) tests right now and returns true or false. _.matcher(properties) returns a reusable predicate you can pass to _.filter or _.find. Under the hood, matcher calls isMatch for each object.
_.isEqual requires the same shape on both sides — extra keys fail. _.isMatch is a partial match: the object only needs to contain the given pairs. {name:"moe", age:32} isMatch {age:32} is true, but isEqual is false.
No. Values are compared with !==, so nested objects and arrays must be the same reference. For a deep comparison of two whole objects, use _.isEqual.
No. It is a stable Underscore 1.x helper used for partial property checks and as the engine behind _.matcher.

Next: _.isEmpty()

Test whether a collection has no elements — another core object helper.

_.isEmpty() 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