window.setTimeout

« Gecko DOM Reference

Summary

Executes a code snippet or a function after specified delay.

Syntax

var timeoutID = window.setTimeout(func, delay, [param1, param2, ...]);
var timeoutID = window.setTimeout(code, delay);

where

  • timeoutID is the numerical ID of the timeout, which can be used later with window.clearTimeout.
  • func is the function you want to execute after delay milliseconds.
  • code in the alternate syntax, is a string of code you want to execute after delay milliseconds. (Using this syntax is not_recommended for the same reasons as using eval())
  • delay is the number of milliseconds (thousandths of a second) that the function call should be delayed by. The actual delay may be longer, see Notes below.

Note that passing additional parameters to the function in the first syntax does not work in Internet Explorer.

Note: Prior to Gecko 13 (Firefox 13.0 / Thunderbird 13.0) , Gecko passed an extra parameter to the callback routine, indicating the "actual lateness" of the timeout in milliseconds. This non-standard parameter is no longer passed.

Compatibility

Introduced with JavaScript 1.0, Netscape 2.0. Passing a Function object reference was introduced with JavaScript 1.2, Netscape 4.0; supported by the MSHTML DOM since version 5.0.

Examples

function generateOutput(aConcise) {
    if(aConcise) {
        parent.generateConciseOutput();
    } else {
        parent.generateOutput();
    }
}
window.setTimeout(generateOutput, 1000, true);  // won't pass "true" to the generateOutput in IE
// Increase compatibility with unnamed functions
window.setTimeout(
    function() {
        generateOutput(true);
    },
    1000
);  // will work with every browser
window.setTimeout('window.parent.generateOutput(true)', 1000);  // deprecated

View on jsFiddle

See also clearTimeout() example.

Notes

You can cancel the timeout using window.clearTimeout().

If you wish to have your function called repeatedly (i.e. every N milliseconds), consider using window.setInterval().

Passing string literals

Passing a string instead of a function to setTimeout() suffers from the same hazards as using eval

// Correct
window.setTimeout(function() {
    alert("Hello World!");
}, 500);

// Incorrect
window.setTimeout("alert(\"Hello World!\");", 500);

String literals are evaluated in the global context, so local symbols in the context where setTimeout() was called will not be available when the string is evaluated as code.

The 'this' problem

Code executed by setTimeout() is run in a separate execution context to the function from which it was called. As a consequence, the this keyword for the called function will be set to the window (or global) object, it will not be the same as the this value for the function that called setTimeout. This issue is explained in more detail in the JavaScript reference.

Note: JavaScript 1.8.5 introduces the Function.prototype.bind() method, which lets you specify the value that should be used as this for all calls to a given function. This lets you easily bypass problems where it's unclear what this will be, depending on the context from which your function was called.

Minimum delay and timeout nesting

Historically browsers implement setTimeout() "clamping": successive setTimeout() calls with delay smaller than the "minimum delay" limit are forced to the use at least the minimum delay. The minimum delay, DOM_MIN_TIMEOUT_VALUE, is 4 ms (stored in a preference in Firefox: dom.min_timeout_value), with a DOM_CLAMP_TIMEOUT_NESTING_LEVEL of 5ms.

In fact, 4ms is specified by the HTML5 spec and is consistent across browsers released in 2010 and onward. Prior to (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) , the minimum timeout value for nested timeouts was 10 ms.

In addition to "clamping", the timeout can also fire later when the page (or the OS/browser itself) is busy with other tasks.

To implement a 0 ms timeout in a modern browser you can use window.postMessage() as described here.

Inactive tabs

In (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) and Chrome 11, timeouts are clamped to firing no more often than once per second (1000ms) in inactive tabs; see bug 633421 for more information about this in Mozilla or crbug.com/66078 for details about this in Chrome.

Specification

Part of DOM level 0, as specified in HTML5.

 

Tags (5)

Edit tags

Attachments (0)

 

Attach file