setTimeout() global function
The setTimeout() global function runs a callback once after the given delay.
Syntax
setTimeout(handler)
setTimeout(handler, delay)
setTimeout(handler, delay, ...args)Parameters
handler
The function to run once the delay is up. A string of code isn't accepted.
delay optional
The delay, in milliseconds; fractions are allowed. Defaults to 0.
- The delay is a minimum: the callback never runs earlier than it, but may run later; see The delay is a minimum, not an exact time.
- There is no minimum value.
0means "run as soon as possible after the current code ends", and isn't lengthened to some fixed number of milliseconds, even when deeply nested. - Negative numbers,
NaN, omitting it, and values that can't be converted to a number (such as'abc') all equal 0. A string such as'100'is converted to 100.
...args optional
Arguments passed unchanged to handler.
Return value
A number, this timer's ID: an increasing integer starting from 1. Pass it to clearTimeout().
Exceptions
TypeError
handler isn't a function: setTimeout: the first argument must be a function. Passing a string of code also throws this.
Description
- Timers with the same delay run in the order they were registered.
queueMicrotask()andPromisecallbacks run beforesetTimeout(fn, 0).- Calling
setTimeout(fn, 0)again inside a timer callback puts the new callback in the next turn, and in between the interface gets a chance to refresh and respond to touches. - When a callback runs for more than 50 milliseconds, the console prints a warning; see Callbacks that run too long.
- Exceptions thrown in the callback are reported by the
errorevent onapplication, and other timers run as usual.
Examples
Running once after a delay
js
setTimeout(() => {
console.log('1 second has passed');
}, 1000);Result: After at least 1000 milliseconds, the console prints a line.
Passing arguments to the callback
js
setTimeout((a, b) => {
console.log(a + b);
}, 0, 'passed ', 'through');Result: Prints passed through.
Order with the same delay
js
setTimeout(() => console.log('A'), 10);
setTimeout(() => console.log('B'), 10);Result: Prints A first, then B.
Differences from the web
- Deeply nested
setTimeout(fn, 0): browsers lengthen the delay to at least 4 milliseconds; here it isn't lengthened. - A string of code as the first argument: browsers run the string as code; here it throws
TypeError. - The return value is a number, not Node's
Timeoutobject; there are no methods likeunref(). - When a single callback runs for more than 50 milliseconds, a warning is printed to the console here; browsers give no indication.
- After the app goes to the background, the system suspends it and callbacks don't run; browsers throttle them instead. Not verified in the simulator.
See also
clearTimeout(): cancel itsetInterval(): run repeatedly- Waiting a period with
await