Skip to main content Link Search Menu Expand Document (external link)

firstWhere() : Find First Matching Item

On this page

Summary

Find and return the first item in a collection where a specific property matches a value.

Signature 

firstWhere(collection, propertyName, value)

Parameters

Parameter Type Required Description
collection Array/Collection Yes The collection to search
propertyName String Yes Name of the property to check
value Any Yes Value to match against

Returns

Type: Object or null

The first item where the specified property equals the given value, or null if no match found.

Examples

Find User by ID 


  <p>Welcome, !</p>
  <p>Email: </p>

Data:

doc.Params["model"] = new {
    currentUserId = 2,
    users = new[] {
        new { id = 1, name = "Alice", email = "alice@example.com" },
        new { id = 2, name = "Bob", email = "bob@example.com" },
        new { id = 3, name = "Charlie", email = "charlie@example.com" }
    }
};

Output:

<p>Welcome, Bob!</p>
<p>Email: bob@example.com</p>

Get Product Details 


  <h3></h3>
  <p>Price: $</p>
  <p>Stock:  units</p>

Data:

doc.Params["model"] = new {
    products = new[] {
        new { sku = "WIDGET-001", name = "Premium Widget", price = 29.99, quantity = 45 },
        new { sku = "WIDGET-002", name = "Standard Widget", price = 19.99, quantity = 120 },
        new { sku = "WIDGET-003", name = "Basic Widget", price = 9.99, quantity = 200 }
    }
};

Output:

<h3>Premium Widget</h3>
<p>Price: $29.99</p>
<p>Stock: 45 units</p>

Find First Active Item 


  <p>Active plan: </p>
  <p>Renews: </p>

  <p>No active subscription</p>

Data:

doc.Params["model"] = new {
    subscriptions = new[] {
        new { planName = "Basic", status = "expired", renewalDate = new DateTime(2024, 1, 15) },
        new { planName = "Pro", status = "active", renewalDate = new DateTime(2024, 4, 20) },
        new { planName = "Enterprise", status = "pending", renewalDate = new DateTime(2024, 3, 30) }
    }
};

Output:

<p>Active plan: Pro</p>
<p>Renews: April 20, 2024</p>


  
    <p>: $ x  = $</p>

Data:

doc.Params["model"] = new {
    products = new[] {
        new { id = 101, name = "Widget A", price = 10.00 },
        new { id = 102, name = "Widget B", price = 15.00 },
        new { id = 103, name = "Widget C", price = 20.00 }
    },
    orderItems = new[] {
        new { productId = 102, quantity = 2 },
        new { productId = 101, quantity = 3 },
        new { productId = 103, quantity = 1 }
    }
};

Output:

<p>Widget B: $15 x 2 = $30</p>
<p>Widget A: $10 x 3 = $30</p>
<p>Widget C: $20 x 1 = $20</p>

Notes

  • Returns null if no match is found
  • Only returns the first matching item (stops searching after first match)
  • Uses equality comparison (==) for matching
  • Case-sensitive for string comparisons
  • More efficient than selectWhere() when you only need one item
  • Useful for:
    • ID-based lookups
    • Finding first active/enabled item
    • Configuration lookups
    • Related data joins
    • Default item selection
  • Use with `` helper for clean null handling
  • For finding all matches, use selectWhere() instead
  • For counting matches, use countOf() instead
  • Performance: O(n) worst case, but stops at first match

See Also