Underscore.js _.findWhere() Method

Beginner
5 min read
Updated: Nov 2026
4 examples
Collection

Definition

Looks through the list and returns the first value that matches all of the key-value pairs listed in properties (official Underscore docs). Empty list or no match → undefined.

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

Syntax

Call _.findWhere. Start with this line.

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

Parameters

ParameterDescription
listRequired. Collection of objects to search
propertiesRequired. Key-value pairs that must all match

Return Value

Return ValueDescription
*First matching object, or undefined

Underscore.js Examples

Example 1 — Match One Property

Return the first object whose field matches a single key-value pair.

Underscore
var items = [
  { name: "Apple", type: "fruit" },
  { name: "Carrot", type: "veg" },
  { name: "Mango", type: "fruit" }
];

_.findWhere(items, { type: "fruit" });
// → { name: "Apple", type: "fruit" }
Try It Yourself

How It Works

  1. List. Three objects; two are fruits.
  2. Matcher. { type: "fruit" } requires that one field.
  3. First hit. Apple matches at the start → return it.
  4. Stop early. Mango is never checked.

Example 2 — Match Several Properties

Every listed pair must match — same idea as _.where, but only the first object.

Underscore
var plays = [
  { title: "Cymbeline", author: "Shakespeare", year: 1611 },
  { title: "The Tempest", author: "Shakespeare", year: 1611 },
  { title: "Hamlet", author: "Shakespeare", year: 1601 }
];

_.findWhere(plays, { author: "Shakespeare", year: 1611 });
// → { title: "Cymbeline", author: "Shakespeare", year: 1611 }
Try It Yourself

How It Works

  1. Two keys. Must match both author and year.
  2. Cymbeline. Fits both → returned first.
  3. The Tempest. Also fits, but search already stopped.
  4. Hamlet. Wrong year — would fail the matcher if reached.

Example 3 — No Match Returns undefined

Empty results are undefined, not null or [].

Underscore
var items = [
  { name: "Apple", type: "fruit" },
  { name: "Carrot", type: "veg" }
];

_.findWhere(items, { type: "meat" });
// → undefined
Try It Yourself

How It Works

  1. Scan. Neither object has type: "meat".
  2. End. List finishes with no hit.
  3. Result. Underscore returns undefined.
  4. Safe use. Check the value before reading .name or similar.

Example 4 — _.findWhere vs _.where

Same matcher — one object vs an array of all matches.

Underscore
var items = [
  { name: "Apple", type: "fruit" },
  { name: "Carrot", type: "veg" },
  { name: "Mango", type: "fruit" }
];

_.findWhere(items, { type: "fruit" });
// → { name: "Apple", type: "fruit" }

_.where(items, { type: "fruit" });
// → [{ name: "Apple", type: "fruit" },
//    { name: "Mango", type: "fruit" }]
Try It Yourself

How It Works

  1. findWhere. Stops at Apple — one object.
  2. where. Collects Apple and Mango — an array.
  3. Pick by intent. Need one row → findWhere; need all → where.
  4. Misses. findWhere → undefined; where → [].

Browser & Runtime Support

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

_.findWhere()

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

_.findWhere(list, properties) returns the first value in the list that matches all key-value pairs in properties. If nothing matches or the list is empty, it returns undefined.
_.findWhere returns the first match (or undefined) and can stop early. _.where returns an array of every matching object.
_.findWhere matches objects by properties. _.find accepts any predicate (function or iteratee). findWhere is like _.find(list, _.matcher(properties)).
You get undefined. Guard before reading properties: if (item) { ... }.
Yes. Every key-value pair in the properties object must match. Partial matches are not enough.
No. It only reads and returns a reference to the matching object (or undefined).

Next: _.reject()

Return the values that fail a truth test — the opposite of filter.

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

9 people found this page helpful