Atomics.add(typedArray, index, value) adds value to the element at index and returns the element’s old value, the number it held just before the addition. The read, the addition, and the write happen as one atomic step: an atomic step is one that no other thread can interrupt halfway. That matters when two threads share the same memory (a SharedArrayBuffer), because a plain counter[0]++ is really three steps (read, add, write) and two threads can overwrite each other’s update. You can also use Atomics.add() on a normal typed array, which is how the examples on this page run in any browser.
Remember
Atomics.add(typedArray, index, value) -> old value
counter[0] is 5
Atomics.add(counter, 0, 1) -> returns 5
counter[0] is now 6
new value = returned value + value
overflow wraps: Uint8Array 255 + 1 -> 0
Syntax
Call it on the global Atomics object. There is one form with three arguments.
JavaScript
Atomics.add(typedArray, index, value)
Call
What it does
Atomics.add(typedArray, index, value)
Adds value to typedArray[index] as one uninterruptible step and returns the element’s value from before the addition.
Atomics.add(typedArray, index, -value)
Adding a negative number subtracts. Atomics.sub() does the same thing and reads more clearly.
Built into JavaScript since ES2017, together with SharedArrayBuffer. Atomics is a namespace object like Math, so there is nothing to import and nothing to construct.
Library declarations
JavaScript
Atomics.add(typedArray, index, value) // returns the old element value
// typedArray: Int8Array, Uint8Array, Int16Array, Uint16Array,
// Int32Array, Uint32Array, BigInt64Array, BigUint64Array
// value: a Number, or a BigInt for the two BigInt arrays
Parameters
Parameter
Description
typedArray
Required. An integer typed array: Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array, or BigUint64Array. It may sit on a SharedArrayBuffer (to share it with workers) or a normal ArrayBuffer. Float32Array, Float64Array, and Uint8ClampedArray throw a TypeError.
index
Required. The position of the element to change. It must be a valid index (0 up to length - 1); anything else throws a RangeError.
value
Required. The amount to add. It is converted to an integer first. For BigInt64Array and BigUint64Array it must be a BigInt such as 1n.
Return Value
Return Value
Description
Number or BigInt
The value the element had before the addition. It is a BigInt for the two BigInt arrays and a Number for every other type.
JavaScript Examples
Example 1 — A Visit Counter
One Int32Array slot counts page visits. Each call adds to it and tells you what the count was before.
JavaScript
const visits = new Int32Array(1); // one slot, starts at 0
console.log(Atomics.add(visits, 0, 1)); // 0
console.log(Atomics.add(visits, 0, 1)); // 1
console.log(Atomics.add(visits, 0, 5)); // 2
console.log(Atomics.load(visits, 0)); // 7
One slot is enough.new Int32Array(1) creates a single 32-bit integer that starts at 0. With a SharedArrayBuffer behind it, several workers could share this slot.
Each call reports the past. The first call returns 0 and stores 1, the second returns 1 and stores 2, and adding 5 returns 2.
Read the total at the end.Atomics.load() shows the current value, 7: the sum of every amount that was added.
Example 2 — Hand Out Unique Ticket Numbers
Because add() returns the old value, it can hand every caller its own number. Even with many threads, no two callers get the same ticket.
JavaScript
const nextTicket = new Int32Array(1);
Atomics.store(nextTicket, 0, 100);
function takeTicket(name) {
const mine = Atomics.add(nextTicket, 0, 1);
return name + " has ticket " + mine;
}
console.log(takeTicket("Asha")); // Asha has ticket 100
console.log(takeTicket("Ben")); // Ben has ticket 101
console.log(takeTicket("Chen")); // Chen has ticket 102
console.log("next free: " + Atomics.load(nextTicket, 0)); // next free: 103
Asha has ticket 100
Ben has ticket 101
Chen has ticket 102
next free: 103
How It Works
Start the numbers at 100.Atomics.store() puts the first ticket number into the slot.
Take and advance together. Inside takeTicket(), the returned old value is the caller’s ticket, and the slot moves on by one in the same atomic step.
No duplicates are possible. A plain read followed by a separate write could give two threads the same number. With add() the next caller always sees the already-increased value, so the slot ends at 103.
Example 3 — Overflow Wraps Around
A typed array element has a fixed size. When the sum does not fit, it wraps around instead of throwing an error.
JavaScript
const bytes = new Uint8Array(1); // 0 to 255
bytes[0] = 255;
console.log(Atomics.add(bytes, 0, 1)); // 255
console.log(bytes[0]); // 0
const small = new Int8Array(1); // -128 to 127
small[0] = 127;
Atomics.add(small, 0, 1);
console.log(small[0]); // -128
A byte holds 0 to 255. Adding 1 to 255 in a Uint8Array returns the old 255 and stores 0, like a car odometer rolling over.
Signed types wrap too. An Int8Array holds -128 to 127, so 127 + 1 wraps to -128.
Pick a type that is big enough. For counters that can grow large, use Int32Array or BigInt64Array so the wrap never happens in practice.
Compatibility
Browser & Runtime Support
Atomics.add() arrived in ES2017 together with SharedArrayBuffer. Modern engines also accept a normal, unshared typed array.
✓ Baseline · ES2017
Atomics.add()
Works in all modern browsers and in Node.js, Deno, and Bun. Sharing the array with workers needs SharedArrayBuffer, which browsers only enable on cross-origin isolated pages.
95%Modern browser support
Google ChromeModern versions · Desktop & Mobile
Full support
Mozilla FirefoxModern versions · Desktop & Mobile
Full support
Apple SafariModern versions · macOS & iOS
Full support
Microsoft EdgeModern versions · Chromium
Full support
OperaModern versions
Full support
Samsung InternetModern versions · Android
Full support
Internet ExplorerNo Atomics object
Not supported
Node.jsCurrent releases · checked on Node 24
Supported
DenoCurrent releases
Supported
BunCurrent releases
Supported
Atomics.add()Excellent
Bottom line: Safe to use everywhere on a normal typed array. To share a counter between workers in a browser, the page must be cross-origin isolated (COOP and COEP headers) so that SharedArrayBuffer exists. Node.js has no such restriction.
Frequently Asked Questions
It returns the old value of the element, the number it held before the addition. The new value is the old value plus the amount you passed.
counter[0]++ reads, adds, and writes in three separate steps. If two threads do it at the same moment on shared memory, one update can be lost. Atomics.add() does all three as one step, so every addition counts.
Yes. It works on a typed array over a normal ArrayBuffer too. You only need a SharedArrayBuffer when several workers must use the same counter at the same time.
The result wraps around using the element type rules, exactly like a normal typed array write. A Uint8Array slot at 255 becomes 0 after adding 1, and no error is thrown.
Yes, but the value must be a BigInt, for example Atomics.add(big, 0, 1n). Passing a regular number such as 1 throws a TypeError, and the returned old value is a BigInt.