The IdleDeadline Object
You'll learn how to use the IdleDeadline object's properties to intelligently manage how much work your code performs during browser idle periods.
What Is the IdleDeadline Object?
When you call requestIdleCallback(), your callback function receives an IdleDeadline object as its parameter. This object is your dashboard for making smart decisions about how much work to perform before yielding control back to the browser.
Think of it like a timer at an arcade game: you need to know how much time remains on your turn and whether you've already run out of time completely.
The Two Critical Properties
timeRemaining()
This method returns the number of milliseconds remaining in the current idle period. It helps you decide whether to continue processing or save work for the next idle callback.
requestIdleCallback((deadline) => {
// Check if we have at least 10ms to work
while (tasks.length > 0 && deadline.timeRemaining() > 10) {
processTask(tasks.shift());
}
});
didTimeout
This boolean property tells you whether the callback was invoked because your optional timeout expired, rather than because the browser became idle. When true, you should prioritize completing critical work even if timeRemaining() is low.
requestIdleCallback((deadline) => {
if (deadline.didTimeout) {
// Timeout expired - do at least one critical task
processTask(tasks.shift());
} else {
// Browser idle - respect time budget
while (tasks.length > 0 && deadline.timeRemaining() > 5) {
processTask(tasks.shift());
}
}
}, { timeout: 2000 });
Key Takeaway: The IdleDeadline object gives you timeRemaining() to check your available time budget and didTimeout to know if your timeout expired, allowing you to balance responsiveness with guaranteed progress on non-critical work.