JavaScript BigInt valueOf() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Instance method

Definition

valueOf() returns the primitive BigInt value. A primitive is a plain value such as 5n, 42, or "hi", as opposed to an object. Most of the time your BigInts are already primitives, and (5n).valueOf() simply returns 5n. The method matters when a BigInt is wrapped in an object, which happens with Object(5n): the wrapper has typeof "object", is never === to 5n, and cannot be used as the same Map key. valueOf() unwraps it. JavaScript also calls it for you when a wrapper is used in math or comparisons.

Remember
const boxed = Object(5n);    // a BigInt wrapper object
typeof boxed;                // "object"
typeof boxed.valueOf();      // "bigint"
boxed === 5n;                // false (an object is never === a primitive)
boxed.valueOf() === 5n;      // true
boxed + 1n;                  // 6n (valueOf() is called automatically)

Syntax

Call it on a BigInt value or on a BigInt wrapper object. It takes no arguments.

JavaScript
bigint.valueOf()
CallWhat it does
(5n).valueOf()On a primitive it returns the same value, 5n. The parentheses are optional: 5n.valueOf() is valid too.
Object(5n).valueOf()Unwraps a BigInt wrapper object and returns the primitive 5n, with typeof "bigint".
wrapper + 1nYou rarely need to call it yourself: math and comparisons such as < call valueOf() automatically.
BigInt.prototype.valueOf.call(5)Calling it on anything that is not a BigInt (here the Number 5) throws a TypeError.

Part of BigInt since ES2020. There is no new BigInt(): BigInt is not a constructor and throws a TypeError with new. The only common way to get a wrapper object is Object(value), which is why wrappers are rare in real code.

Library declarations
JavaScript
bigint.valueOf()   // returns the primitive BigInt

// Works on a BigInt primitive or a BigInt wrapper object.
// Anything else as "this" throws a TypeError.

Parameters

ParameterDescription
(none)valueOf() takes no arguments. Any arguments you pass are ignored.

Return Value

Return ValueDescription
BigIntThe primitive BigInt value, so typeof the result is always "bigint".

JavaScript Examples

Example 1 — A Wrapper Object vs a Plain BigInt

Create the same value as a primitive and as a wrapper object, then compare their types and equality before and after valueOf().

JavaScript
const plain = 5n;
const boxed = Object(5n);              // a BigInt wrapper object

console.log(typeof plain);             // bigint
console.log(typeof boxed);             // object
console.log(typeof boxed.valueOf());   // bigint
console.log(boxed === 5n);             // false
console.log(boxed.valueOf() === 5n);   // true
console.log(boxed == 5n);              // true
Try It Yourself

How It Works

  1. Object() wraps the value. Object(5n) creates an object that holds 5n inside, so typeof reports "object" instead of "bigint".
  2. === sees an object, not a number. Strict equality never converts, and an object is not the primitive 5n, so the first comparison is false.
  3. valueOf() unwraps it. After valueOf() the comparison is between two primitives and gives true. Loose == unwraps the object by itself, which is why it also says true.

Example 2 — Use valueOf() to Get Reliable Map Keys

A Map compares keys like ===, so a wrapper object never finds an entry stored under the plain BigInt. A small helper unwraps values first.

JavaScript
function plainBigInt(x) {
  return typeof x === "object" && x !== null ? x.valueOf() : x;
}

const owners = new Map();
owners.set(7n, "Asha");

const key = Object(7n);
console.log(owners.get(key));                  // undefined
console.log(owners.get(key.valueOf()));        // Asha
console.log(owners.get(plainBigInt(key)));     // Asha
console.log(owners.get(plainBigInt(7n)));      // Asha
Try It Yourself

How It Works

  1. The entry uses a primitive key. owners.set(7n, "Asha") stores the value under the plain BigInt 7n.
  2. A wrapper is a different key. owners.get(Object(7n)) looks for that exact object, finds nothing, and returns undefined.
  3. Normalise before you look up. plainBigInt() calls valueOf() only for objects and leaves primitives alone, so both wrapped and plain inputs find "Asha".

Example 3 — When JavaScript Calls valueOf() for You

Math and comparisons unwrap a wrapper automatically. Before sorting a mixed list, unwrap every item, and use a comparator that returns a Number.

JavaScript
const boxed = Object(40n);
console.log(String(boxed + 2n));   // 42
console.log(boxed > 39n);          // true

const sizes = [Object(30n), 5n, Object(100n), 20n].map(function (x) {
  return x.valueOf();
});
sizes.sort(function (a, b) { return a < b ? -1 : a > b ? 1 : 0; });
console.log(sizes.join(", "));     // 5, 20, 30, 100

try {
  BigInt.prototype.valueOf.call(5);
} catch (e) {
  console.log(e.name);             // TypeError
}
Try It Yourself

How It Works

  1. Operators unwrap automatically. For boxed + 2n and boxed > 39n, JavaScript calls valueOf() behind the scenes, giving 42n and true. String() prints the BigInt without the n.
  2. Unwrap, then sort with a Number comparator. map() calls valueOf() on every item. The comparator returns -1, 1, or 0; returning a - b would give a BigInt, and sort() throws a TypeError for that.
  3. Only BigInts are accepted. BigInt.prototype.valueOf.call(5) runs the method on the Number 5, which is not a BigInt, so it throws a TypeError.

Browser & Runtime Support

BigInt.prototype.valueOf() arrived in ES2020 with the BigInt type and works the same in every engine.

✓ Baseline · ES2020

BigInt.prototype.valueOf()

Works in all modern browsers and in Node.js 10.4 and later, Deno, and Bun. Internet Explorer has no BigInt at all.

96% Modern browser support
Google Chrome Modern versions · Desktop & Mobile
Full support
Mozilla Firefox Modern versions · Desktop & Mobile
Full support
Apple Safari Modern versions · macOS & iOS
Full support
Microsoft Edge Modern versions · Chromium
Full support
Opera Modern versions
Full support
Samsung Internet Modern versions · Android
Full support
Internet Explorer No BigInt type
Not supported
Node.js Node 10.4 and later · checked on Node 24
Supported
Deno All releases
Supported
Bun All releases
Supported
BigInt.prototype.valueOf() Excellent

Bottom line: Safe to use everywhere BigInt exists. In everyday code you will rarely call it directly, because BigInt wrapper objects are uncommon and operators unwrap them automatically.

Frequently Asked Questions

The primitive BigInt value. For a plain BigInt such as 5n it returns 5n itself; for a wrapper object made with Object(5n) it returns the primitive 5n inside.
No. It always returns a BigInt. Use Number(big) to get a Number, and keep in mind that values above Number.MAX_SAFE_INTEGER may lose precision.
Object(5n) wraps the BigInt in an object. Only the value inside is a bigint, so typeof the wrapper is "object" and typeof Object(5n).valueOf() is "bigint".
Yes. Because a BigInt literal ends with n, the dot after it cannot be a decimal point, so 5n.valueOf() works. With a normal number, 5.valueOf() is a syntax error and you need (5).valueOf().
Use a comparator that returns a Number, such as (a, b) => (a < b ? -1 : a > b ? 1 : 0). Returning a - b gives a BigInt, which makes sort() throw a TypeError, and sort() without a comparator orders the values as text.

Back to the BigInt Method Index

See all five BigInt methods side by side, with a one-line summary for each.

BigInt methods →

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.

11 people found this page helpful