JavaScript BigInt

by

JavaScript BigInt is a special numeric data type that allows you to work with whole numbers that are larger than the maximum safe integer supported by the standard JavaScript number type.

For most everyday calculations, the regular JavaScript number type is more than enough. You can use it for prices, quantities, scores, percentages, measurements, counters, and many other numerical values. However, when an application needs to work with extremely large integers, the standard number type has a precision limit that can cause unexpected results.

This is where BigInt becomes useful.

BigInt allows JavaScript developers to represent and perform calculations with integers that are outside the safe integer range of the ordinary number type. It is particularly useful when working with very large integer values, large identifiers, cryptographic-related calculations, financial systems that require integer-based calculations, and other applications where losing integer precision could cause problems.

In this tutorial, you will learn what BigInt is, why it is needed, how to create BigInt values, how to perform arithmetic operations, how to compare BigInts, how to convert between number and BigInt, the differences between Number and BigInt, common errors, and important limitations you should know before using BigInt.

What Is BigInt in JavaScript?

BigInt is a JavaScript primitive data type designed to represent integers with arbitrary precision.

In simple terms, BigInt allows you to work with very large whole numbers without the same integer precision limitations associated with the standard JavaScript number type.

A BigInt value is created by adding the letter n to the end of an integer.

let bigNumber = 9007199254740993n;

console.log(bigNumber);

Output:

9007199254740993n

The n at the end tells JavaScript that the value is a BigInt rather than a regular number.

You can check its data type using typeof.

let bigNumber = 9007199254740993n;

console.log(typeof bigNumber);

Output:

bigint

Notice that the result is bigint, not number.

Why Do We Need BigInt?

JavaScript’s standard number type uses double-precision floating-point representation. This provides a large range of numerical values, but not every integer within that range can be represented exactly.

JavaScript provides a safe integer range for ordinary integers.

The largest safe integer is available through:

console.log(Number.MAX_SAFE_INTEGER);

Output:

9007199254740991

The smallest safe integer is:

console.log(Number.MIN_SAFE_INTEGER);

Output:

-9007199254740991

Once you move beyond this safe integer range, ordinary number calculations can lose precision.

For example:

let number = 9007199254740993;

console.log(number);

The value may not be represented exactly as you intended.

This is one of the main reasons BigInt exists.

With BigInt:

let number = 9007199254740993n;

console.log(number);

JavaScript can represent the integer precisely.

JavaScript Number vs BigInt

The standard number type and BigInt are both used for numerical values, but they are designed for different purposes.

FeatureNumberBigInt
Data typenumberbigint
Whole numbersYesYes
Decimal numbersYesNo
Very large integersLimited precisionSupports arbitrary-size integers
Decimal calculationsSupportedNot supported
Example100100n
Type checkingtypeof value === "number"typeof value === "bigint"
Math operationsSupportedSupported for BigInt operands
Mix directly with other typeN/ACannot freely mix with number

For normal calculations, number is usually appropriate. BigInt is specifically useful when you need exact integer arithmetic with very large values.

How to Create a BigInt

The easiest way to create a BigInt is to add n to the end of an integer literal.

let value = 12345678901234567890n;

console.log(value);

You can also create negative BigInt values.

let temperature = -10000000000000000000n;

console.log(temperature);

The important point is that BigInt literals must represent integers.

You cannot create a BigInt literal containing a decimal portion.

let value = 10.5n;

This produces a syntax error because BigInt is designed specifically for integers.

Creating BigInt With BigInt()

You can also create a BigInt using the BigInt() function.

let value = BigInt(100);

console.log(value);

Output:

100n

You can convert a string containing an integer into a BigInt.

let value = BigInt("12345678901234567890");

console.log(value);

Output:

12345678901234567890n

This is useful when large integer values arrive as strings from forms, APIs, databases, or other sources.

Checking the Type of BigInt

The typeof operator returns "bigint" for BigInt values.

let value = 100n;

console.log(typeof value);

Output:

bigint

Compare this with a normal number:

let number = 100;
let bigNumber = 100n;

console.log(typeof number);
console.log(typeof bigNumber);

Output:

number
bigint

Even though both values represent 100, they are different JavaScript data types.

BigInt Arithmetic

BigInt supports several common arithmetic operations.

You can perform addition, subtraction, multiplication, division, remainder, and exponentiation using BigInt values.

BigInt Addition

let a = 10000000000000000000n;
let b = 20000000000000000000n;

let result = a + b;

console.log(result);

Output:

30000000000000000000n

BigInt Subtraction

let a = 50000000000000000000n;
let b = 20000000000000000000n;

let result = a - b;

console.log(result);

Output:

30000000000000000000n

BigInt Multiplication

let a = 1000000000000n;
let b = 20n;

let result = a * b;

console.log(result);

Output:

20000000000000n

BigInt Division

BigInt supports division, but it is important to remember that the result is an integer.

let a = 10n;
let b = 3n;

console.log(a / b);

Output:

3n

The decimal portion is discarded because BigInt cannot represent fractional values.

With regular numbers:

console.log(10 / 3);

Output:

3.3333333333333335

With BigInt:

console.log(10n / 3n);

Output:

3n

This difference is extremely important when working with BigInt calculations.

BigInt Remainder

You can use the % operator with BigInt values.

let result = 10n % 3n;

console.log(result);

Output:

1n

The remainder is also returned as a BigInt.

BigInt Exponentiation

The ** operator can be used with BigInt values.

let result = 2n ** 10n;

console.log(result);

Output:

1024n

Both operands involved in the BigInt operation must be BigInt values.

You Cannot Mix BigInt and Number Directly

One of the most important BigInt rules is that you cannot directly perform arithmetic between a BigInt and a regular number.

For example:

let a = 10n;
let b = 5;

console.log(a + b);

This causes a TypeError.

The two values have different types.

Instead, convert one value so that both operands use the same numeric type.

let a = 10n;
let b = 5n;

console.log(a + b);

Output:

15n

Or, when appropriate:

let a = 10n;
let b = 5;

console.log(a + BigInt(b));

Output:

15n

You should always be deliberate when converting between number and BigInt because converting a very large number that has already lost precision cannot recover the original value.

Comparing BigInt and Number

Although BigInt and Number cannot generally be mixed in arithmetic operations, they can be compared.

For example:

console.log(10n === 10);

Output:

false

The strict equality operator checks both the value and the data type.

The types are different, so the result is false.

However:

console.log(10n == 10);

Output:

true

The loose equality operator allows type conversion for the comparison.

Relational operators can also compare BigInt and Number values.

console.log(20n > 10);

Output:

true

And:

console.log(5n < 10);

Output:

true

For predictable code, it is generally a good idea to be clear about the types you are comparing.

BigInt and Equality

The difference between == and === is particularly noticeable when comparing BigInt and Number values.

console.log(100n == 100);

Output:

true

But:

console.log(100n === 100);

Output:

false

This happens because 100n is a BigInt while 100 is a Number.

When writing JavaScript applications, strict equality with === is generally preferred when you want both the value and type to match.

Converting BigInt to Number

You can convert a BigInt into a regular number using the Number() function.

let bigValue = 100n;

let numberValue = Number(bigValue);

console.log(numberValue);
console.log(typeof numberValue);

Output:

100
number

However, you need to be careful when converting very large BigInts to Numbers.

For example, if the BigInt is outside the safe integer range, converting it to a Number can result in precision loss.

let bigValue = 9007199254740993n;

let numberValue = Number(bigValue);

console.log(numberValue);

The resulting Number may not represent the original integer exactly.

Therefore, you should not convert a BigInt to Number simply because it is convenient unless you know the value is within a safe range.

Converting Number to BigInt

You can convert an integer Number to BigInt using BigInt().

let number = 100;

let bigNumber = BigInt(number);

console.log(bigNumber);

Output:

100n

The Number must represent an integer.

For example:

console.log(BigInt(10));

works because 10 is an integer.

However:

console.log(BigInt(10.5));

causes an error because 10.5 is not an integer.

BigInt and Decimal Numbers

BigInt does not support decimal values.

For example:

let value = 10.5n;

is invalid.

BigInt is specifically designed for whole numbers.

If your application requires decimal calculations, the standard number type or another appropriate numeric approach may be more suitable.

This is particularly important for financial applications where decimal precision requirements may call for specialized techniques or libraries rather than simply switching everything to BigInt.

BigInt Increment and Decrement

You can use the increment operator with BigInt values.

let count = 10n;

count++;

console.log(count);

Output:

11n

Similarly, you can decrement a BigInt.

let count = 10n;

count--;

console.log(count);

Output:

9n

The resulting value remains a BigInt.

BigInt With Variables

BigInt can be used just like other JavaScript values stored in variables.

let population = 8000000000n;
let increase = 500000000n;

let newPopulation = population + increase;

console.log(newPopulation);

Output:

8500000000n

This makes BigInt useful when an application needs exact integer calculations involving large values.

BigInt in Loops

BigInt values can also be used with loops, but you need to make sure the loop counter and comparison values use compatible types.

For example:

for (let i = 0n; i < 5n; i++) {
    console.log(i);
}

Output:

0n
1n
2n
3n
4n

Notice that both the starting value and the comparison value are BigInts.

Mixing a BigInt counter with a Number increment or arithmetic operation can produce errors.

BigInt and JSON

One important limitation of BigInt is that it cannot be directly serialized using the standard JSON.stringify() behavior.

For example:

let value = 100n;

console.log(JSON.stringify(value));

This results in an error because JSON does not have a standard BigInt data type.

When working with APIs or storing BigInt values as JSON, developers generally need to convert the value into an appropriate representation, such as a string, before serialization.

For example:

let value = 100n;

let data = {
    amount: value.toString()
};

console.log(JSON.stringify(data));

Output:

{"amount":"100"}

The value can later be converted back into BigInt when needed.

let value = BigInt("100");

console.log(value);

Output:

100n

This approach can be useful when large integer values need to move between JavaScript applications and APIs.

BigInt With Arrays

BigInt values can be stored inside arrays just like other JavaScript values.

let numbers = [
    10000000000000000000n,
    20000000000000000000n,
    30000000000000000000n
];

console.log(numbers);

You can access an individual value:

console.log(numbers[0]);

Output:

10000000000000000000n

You can also perform BigInt calculations using array values.

let total = numbers[0] + numbers[1];

console.log(total);

Output:

30000000000000000000n

BigInt With Functions

Functions can accept BigInt values as arguments and return BigInt values.

function addNumbers(a, b) {
    return a + b;
}

let result = addNumbers(
    10000000000000000000n,
    20000000000000000000n
);

console.log(result);

Output:

30000000000000000000n

When creating functions that work with BigInt, make sure callers provide compatible values.

Practical BigInt Example

Consider an application that needs to calculate a very large integer quantity.

let totalUsers = 9007199254740993n;
let newUsers = 5000000000000000n;

let updatedUsers = totalUsers + newUsers;

console.log(`Total: ${updatedUsers}`);

Output:

Total: 14007192547409993

Template literals can display BigInt values without requiring you to manually remove the n notation.

This approach can be useful when displaying large integer values in dashboards, reports, analytics applications, or other interfaces.

Practical BigInt Example With a Counter

A BigInt counter can be useful when an application needs to maintain an extremely large integer value.

let counter = 10000000000000000000n;

counter += 1n;
counter += 1n;
counter += 1n;

console.log(counter);

Output:

10000000000000000003n

Every operation remains an integer calculation using BigInt.

When Should You Use BigInt?

BigInt should not automatically replace the normal JavaScript number type. It is intended for situations where large integer precision is important.

BigInt can be appropriate when working with:

  • Extremely large integer values
  • Large counters
  • Large integer identifiers
  • Certain cryptographic calculations
  • Applications that require exact large-integer arithmetic
  • Systems that process integer values beyond the safe Number range

For ordinary values such as:

let age = 25;
let price = 499.99;
let score = 95;

using the standard number type is generally simpler and more appropriate.

When Should You Avoid BigInt?

BigInt is not designed for every numerical calculation.

You generally should not use BigInt when your application requires:

  • Decimal values
  • Fractional calculations
  • Direct interoperability with APIs that expect ordinary Numbers
  • Mathematical functions from Math that require Number values
  • Calculations where standard Numbers already provide sufficient precision

For example:

let price = 99.99;

This should be a Number rather than:

let price = 99.99n;

because BigInt cannot represent decimal values.

BigInt and Math Methods

Many methods in the Math object work with ordinary Numbers rather than BigInts.

For example:

let value = 100n;

console.log(Math.round(value));

This results in an error because Math.round() expects a Number.

If you need to use a Math function, you may need to convert the BigInt to a Number, but you should only do this when the conversion is safe and precision will not be lost.

Common BigInt Mistakes

Forgetting the n

This is a regular Number:

let value = 100;

This is a BigInt:

let value = 100n;

The n is what distinguishes a BigInt literal from an ordinary numeric literal.

Mixing Number and BigInt in Arithmetic

This is invalid:

let a = 10n;
let b = 5;

console.log(a + b);

Use compatible types:

let a = 10n;
let b = 5n;

console.log(a + b);

Expecting BigInt to Support Decimals

This is invalid:

let price = 10.5n;

BigInt only represents integers.

Converting a Very Large BigInt to Number

Be careful with:

let value = 9007199254740993n;

let number = Number(value);

The resulting Number may lose precision because it exceeds the safe integer range.

Using JSON.stringify() Directly on BigInt

This can cause an error:

let value = 100n;

JSON.stringify(value);

Convert the BigInt to a string when preparing data for standard JSON serialization.

JavaScript BigInt Cheat Sheet

TaskExample
Create BigInt100n
Create with functionBigInt(100)
Convert stringBigInt("100")
Check typetypeof value
Addition10n + 5n
Subtraction10n - 5n
Multiplication10n * 5n
Division10n / 3n
Remainder10n % 3n
Power2n ** 3n
Incrementvalue++
Decrementvalue--
Convert to NumberNumber(value)
Convert to Stringvalue.toString()
Compare10n > 5n
Check typetypeof value === "bigint"

Frequently Asked Questions About JavaScript BigInt

What is BigInt in JavaScript?

BigInt is a JavaScript primitive data type that allows programs to represent and perform calculations with arbitrarily large integers.

Why was BigInt introduced?

BigInt was introduced to provide a way to work with very large integers without the precision limitations of the standard JavaScript number type.

How do you create a BigInt?

You can add n to the end of an integer literal.

let value = 12345678901234567890n;

You can also use the BigInt() function.

let value = BigInt("12345678901234567890");

What is the difference between Number and BigInt?

Number is JavaScript’s standard numeric type and supports both integers and decimal values, while BigInt is designed specifically for arbitrarily large integers and does not support decimal values.

Can BigInt contain decimal values?

No. BigInt represents whole numbers only.

let value = 10.5n;

is invalid.

Can you add a Number and BigInt?

You cannot directly perform arithmetic between a Number and a BigInt.

10n + 5;

causes a TypeError.

Convert the values to a compatible type first.

How do you convert BigInt to Number?

Use the Number() function.

let value = 100n;

let number = Number(value);

However, converting a BigInt outside the safe Number range can result in precision loss.

How do you convert a Number to BigInt?

Use the BigInt() function when the Number represents an integer.

let number = 100;

let value = BigInt(number);

Can BigInt be used with JSON?

BigInt does not have a native JSON representation, so it cannot normally be passed directly to JSON.stringify(). A common approach is to convert BigInt values to strings before serialization.

What does the n mean in BigInt?

The n suffix tells JavaScript that the numeric literal is a BigInt.

100

is a Number, while:

100n

is a BigInt.

Leave a Comment