Lodash _.toNumber() method

Beginner
⏱️ 6 min read
📚 Updated: May 2026
🎯 3 Code examples
🚀 3 Try-it labs
Lodash

What you’ll learn

  • How _.toNumber(value) is the raw coercion behind _.toFinite, _.toInteger, and _.toLength.
  • Why NaN and ±Infinity pass through untouched (unlike _.toFinite).
  • How object inputs get their valueOf() called.
  • The numeric-string tricks: whitespace trimming, hex/binary/octal prefixes, bad-hex detection.

Prerequisites

You’ve used Number() and know the valueOf /toString conversion hooks.

  • You’re comfortable distinguishing NaN, 0, and Infinity when reasoning about coercion.
  • Try-it labs load lodash from the CDN.

Overview

The algorithm in five steps: number → return; Symbol → NaN; object → call valueOf() (then fall back to String(other)); non-string → +value; string → trim, check 0x/0b/0o prefixes, parse.

Faithful coercion

NaN, Infinity, and undefined survive—no sanitising.

String prefixes

Parses 0x, 0b, 0o; trims whitespace; rejects bad signed hex.

valueOf hook

Objects with a numeric valueOf() coerce cleanly.

Syntax

javascript
_.toNumber(value)
  • value: the value to convert.
  • Returns: a number. Can be NaN or ±Infinity. Throws only for BigInt.
1

Lodash docs baseline

Four official examples—decimal, tiny, infinite, and numeric string. Notice Infinity stays Infinity.

javascript
import toNumber from "lodash/toNumber";

console.log(
  "3.2:             " + toNumber(3.2) + "\n" +                          // 3.2
  "MIN_VALUE:       " + toNumber(Number.MIN_VALUE) + "\n" +             // 5e-324
  "Infinity:        " + toNumber(Infinity) + "\n" +                      // Infinity (preserved!)
  "'3.2' string:    " + toNumber("3.2")                              // 3.2
);
Try it Yourself
2

Nullish, falsy, and Symbol

A common myth: “_.toNumber turns nullish into 0.” Half-true—null coerces to 0, but undefined coerces to NaN. Symbols also short-circuit to NaN.

javascript
import toNumber from "lodash/toNumber";

console.log(
  "null:        " + toNumber(null) + "\n" +              // 0   (Number(null) = 0)
  "undefined:   " + toNumber(undefined) + "\n" +         // NaN (Number(undefined) = NaN)
  "'':          " + toNumber("") + "\n" +                 // 0
  "true:        " + toNumber(true) + "\n" +              // 1
  "false:       " + toNumber(false) + "\n" +             // 0
  "Symbol():    " + toNumber(Symbol())                    // NaN
);
Try it Yourself
3

String prefixes & valueOf hook

Whitespace trim, three numeric literal prefixes, the “bad signed hex” rejection, and the custom valueOf hook that lets your own objects coerce.

javascript
import toNumber from "lodash/toNumber";

const money = { valueOf: () => 7 };

console.log(
  "' 7 '   trim:        " + toNumber(" 7 ") + "\n" +     // 7
  "'0x1f'  hex:         " + toNumber("0x1f") + "\n" +    // 31
  "'0b11'  binary:      " + toNumber("0b11") + "\n" +    // 3
  "'0o17'  octal:       " + toNumber("0o17") + "\n" +    // 15
  "'-0x10' bad hex:     " + toNumber("-0x10") + "\n" +    // NaN (signed hex rejected)
  "{ valueOf:()=>7 } obj: " + toNumber(money)                  // 7
);
Try it Yourself

📋 _.toNumber vs related conversions

Input_.toNumber_.toFiniteNumber()parseFloat
undefinedNaN0NaNNaN
InfinityInfinity1.79e+308InfinityInfinity
'0x1f'3131310
'0b11'3330
' 7px 'NaN0NaN7

Pitfalls to avoid

Undefined

undefined is not 0

_.toNumber(undefined) is NaN. Reach for _.toFinite when you want missing data to default to 0.

Arrays

Multi-element arrays → NaN

_.toNumber([5]) is 5, but _.toNumber([5, 6]) is NaN because the string fallback produces '5,6'. Same trap as +arr.

BigInt

BigInt throws

_.toNumber(1n) raises “Cannot convert a BigInt value to a number.” Convert via Number(bigint) first if you can accept precision loss.

❓ FAQ

No—it returns NaN. Only _.toNumber(null) returns 0 (because +null === 0). _.toFinite(undefined) is the one that yields 0.
Two things: it trims whitespace before parsing, and it parses the 0x / 0b / 0o numeric-literal prefixes the same way the JavaScript engine does (Number('0o17') is 15).
Lodash explicitly calls value.valueOf() when the input is an object. If that returns another object, lodash falls back to String(...). It's a deliberate hook for custom coercible types.
Symbol returns NaN (lodash short-circuits). BigInt throws 'Cannot convert a BigInt value to a number'—use Number(bigint) up front if needed.

Summary

  • Purpose: the raw number-coercion primitive used by _.toFinite, _.toInteger, _.toLength, and the relational helpers _.lt/_.gt.
  • Remember: it can return NaN or ±Infinity. Use _.toFinite if you need a sanitised number.
  • Next: see Lodash _.toPlainObject() — _.toPlainObject and the remaining Lang helpers.
Did you know?

_.toNumber calls valueOf() on object inputs first—so a tagged value like { valueOf: () => 7 } returns 7. That’s the same hook the + operator uses, just exposed as a named utility.

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.

AWS Certified Developer – Associate (Credly)

6 people found this page helpful

Lodash _.toLength() Lodash _.toPlainObject()