whenLoaded()

Description

The whenLoaded() function is a utility that allows you to execute a callback function once the page is fully loaded (including images, stylesheets, and other resources). It helps manage functions that need to wait for all page resources to be available before executing.

Key features

• Callback Management: Supports multiple callbacks that can be queued and executed once the page is fully loaded.
• Automatic Handling: Automatically detects if the page is already loaded and executes the callbacks immediately if so.
• Event Listener: Adds an event listener for the load event if the page is not yet loaded, ensuring callbacks are executed at the right time.

Technical specifications

whenLoaded is available as a named and default export.

whenLoaded(fn);

whenLoaded(fn)

• Parameters:
  • fn: The callback function to execute once the page is fully loaded (all resources). It will be called with no arguments and its return value is ignored.
• Return Value: Returns undefined.

scheduleWhenLoaded(fn)

A promise-based version of whenLoaded.

• Parameters:
  • fn: The function to schedule. If null or undefined, the promise resolves with undefined.
• Return Value: Returns a Promise that resolves with the return value of fn(), or rejects if fn() throws.

remove(fn)

Removes a previously queued function from the waiting list.

• Parameters:
  • fn: The function to remove.
• Return Value: Returns true if the function was found and removed, false otherwise.

Usage instructions

To use the whenLoaded() function, import it into your project and pass your callback function as an argument. Here’s an example:

import whenLoaded, {scheduleWhenLoaded, remove} from 'time-queues/when-loaded.js';

whenLoaded(() => console.log('Document is fully loaded!'));

// Promise-based version
const result = await scheduleWhenLoaded(() => document.title);
console.log('Page title:', result);

// Remove a queued callback
const myCallback = () => console.log('hello');
whenLoaded(myCallback);
remove(myCallback); // returns true if removed

Troubleshooting

• Callback Not Executing: Ensure that the whenLoaded() function is called before the page is fully loaded. If it's called afterward, the callback will execute immediately.
• Multiple Callbacks: If multiple callbacks are registered, they will all execute in the order they were added once the page is fully loaded.

See Also

• whenDomLoaded() - DOM content loaded utility
• defer() - Execute on next tick