jQuery event.timeStamp

What You’ll Learn

event.timeStamp records when the browser created the event — epoch milliseconds you can subtract to measure gaps between clicks or key presses. This tutorial covers the official consecutive-click demo, handler profiling, comparing with Date.getTime() and performance.now(), double-click detection, input throttling, and the Firefox caveat.

Introduction

Every jQuery handler receives an event object. Among its properties, event.timeStamp answers: when did the browser create this event? The value is a number — milliseconds between that moment and January 1, 1970 (the Unix epoch). It is not updated while your handler runs; reading it twice inside the same callback returns the same number.

jQuery has exposed event.timeStamp since version 1.2.6. The official docs highlight profiling: store event.timeStamp at one point, read it again on a later event, and note the difference. The canonical demo compares consecutive clicks with diff = event.timeStamp - last. For current wall-clock time inside a handler, use (new Date).getTime() instead — not timeStamp.

Understanding event.timeStamp

event.timeStamp is the browser’s record of event creation time in epoch milliseconds:

• Fixed per event — set when the browser dispatches the event; unchanged for the lifetime of that event object.
• Comparable across events — subtract two timestamps to get milliseconds between user actions (clicks, keydowns).
• Not handler “now” — if work delays your callback, timeStamp still reflects creation time, not when your code runs.
• Profiling aid — official pattern: read at start and end of handler work, or compare consecutive events via a stored last variable.

📝 Syntax

Official jQuery API form (since 1.2.6):

event.timeStamp

// read inside any .on() handler:
function handler( event ) {
  var created = event.timeStamp;
  console.log( "Event created at epoch ms:", created );
}

// consecutive events — official delta pattern:
var last;
$( "div" ).on( "click", function ( event ) {
  if ( last ) {
    var diff = event.timeStamp - last;
    console.log( "ms since last:", diff );
  }
  last = event.timeStamp;
});

Type

• Number — milliseconds since January 1, 1970 UTC at event creation.

Return value

• Not a method — a read-only property on the event object passed to your handler.
• Same value for the entire dispatch of that event — subtract across events, not across lines in one handler expecting “now”.

Official jQuery API example

var last, diff;
$( "div" ).on( "click", function ( event ) {
  if ( last ) {
    diff = event.timeStamp - last;
    $( "div" ).append( "time since last event: " + diff + " " );
  } else {
    $( "div" ).append( "Click again. " );
  }
  last = event.timeStamp;
});

Examples Gallery

Example 1 follows the official consecutive-click demo. Examples 2–5 cover handler profiling, timeStamp vs wall clock, double-click interval detection, and keydown throttling.

var last, diff;
$( "div" ).on( "click", function ( event ) {
  if ( last ) {
    diff = event.timeStamp - last;
    $( "div" ).append( "time since last event: " + diff + " " );
  } else {
    $( "div" ).append( "Click again. " );
  }
  last = event.timeStamp;
});

First click → "Click again."
Second click → "time since last event: 842 " (example ms)
Each click updates last = event.timeStamp for the next delta

$( "#run" ).on( "click", function ( event ) {
  var t0 = performance.now();
  var birth = event.timeStamp;
  // simulate work
  for ( var i = 0; i < 1e6; i++ ) {}
  var t1 = performance.now();
  $( "#log" ).html(
    "event.timeStamp: " + birth + "
" +
    "handler work: " + ( t1 - t0 ).toFixed( 2 ) + " ms"
  );
});

event.timeStamp: 1738123456789 (epoch ms at click creation)
handler work: 12.40 ms (performance.now() delta)
timeStamp does not advance during the loop — use performance.now() for handler duration

$( "button" ).on( "click", function ( event ) {
  var now = ( new Date ).getTime();
  var lag = now - event.timeStamp;
  $( "#log" ).html(
    "event.timeStamp: " + event.timeStamp + "
" +
    "Date.getTime(): " + now + "
" +
    "handler lag: " + lag + " ms"
  );
});

event.timeStamp: 1738123456789
Date.getTime(): 1738123456794
handler lag: 5 ms (small under normal conditions; larger if main thread is busy)
Use Date.getTime() for "now" — not timeStamp

var lastClick = 0;
$( "#item" ).on( "click", function ( event ) {
  var delta = event.timeStamp - lastClick;
  if ( lastClick && delta < 300 ) {
    $( "#log" ).text( "Double-click detected (" + delta + " ms)" );
    lastClick = 0;
  } else {
    $( "#log" ).text( "Single click — click again quickly" );
    lastClick = event.timeStamp;
  }
});

First click → "Single click — click again quickly"
Second click within 300 ms → "Double-click detected (187 ms)"
Slow second click → treated as new single click

var lastKey = 0;
$( "#search" ).on( "keydown", function ( event ) {
  if ( event.timeStamp - lastKey < 200 ) {
    return;
  }
  lastKey = event.timeStamp;
  $( "#status" ).text( "Handled key at " + lastKey );
});

Rapid key repeat → most keydowns ignored
Keys spaced ≥ 200 ms apart → #status updates each time
Same timeStamp delta pattern as the official click demo

🚀 Common Use Cases

• Click spacing — official demo: diff = event.timeStamp - last between consecutive clicks.
• Handler profiling — compare timestamps at two code points or use performance.now() inside one handler.
• Double-click detection — threshold on event.timeStamp - lastClick (~300 ms).
• Input throttling — ignore keydown/keyup when delta from last handled event is below 200 ms.
• Event ordering — compare creation times when debugging race conditions between rapid events.
• Debug lag — Date.now() - event.timeStamp shows queue delay before your handler ran.

📝 Notes

• Available since jQuery 1.2.6 — returns a Number (epoch milliseconds at event creation).
• Measures time between event creation and January 1, 1970 — not current time inside the handler.
• For wall clock now, use (new Date).getTime() or Date.now() — as stated in the official jQuery docs.
• Official profiling pattern: read at two points and note the difference; consecutive clicks use event.timeStamp - last.
• Firefox caveat — long-standing bug: timeStamp not populated correctly; exact event creation time unavailable there.
• For in-handler duration, prefer performance.now() over re-reading event.timeStamp.
• Read-only — store in a variable if you need the value after async work in the same dispatch.

💡 Best Practices