HTML Img complete Property: Image Complete

HTML Img complete Property: Image Loading Status

The HTML complete property of the <img> element is a read-only boolean attribute that indicates whether an image has finished loading. It returns true if the image has completely loaded, including all its data, and false otherwise. This property is useful for scripting scenarios where you need to ensure an image is fully loaded before performing certain actions, such as manipulating the image or triggering animations.

Purpose of the complete Property

The primary purpose of the complete property is to provide a way to programmatically check the loading status of an image. This allows developers to:

• Synchronize JavaScript code with image loading.
• Implement fallback behavior if an image fails to load.
• Optimize the user experience by delaying actions until images are ready.

Syntax

The syntax for accessing the complete property is straightforward:

const isComplete = imageElement.complete;

Here, imageElement is a reference to the <img> element in the DOM, and isComplete will be a boolean value.

Property Values

Value	Description
`true`	Indicates that the image has completely loaded.
`false`	Indicates that the image is still loading or has not yet started loading.

Examples

Let’s explore some practical examples of how to use the complete property in JavaScript.

Basic Check for Image Loading

This example demonstrates how to check if an image has loaded and display a message accordingly.

<img id="myImageBasic" src="https://dummyimage.com/200x200/007bff/fff" alt="Dummy Image" />
<p id="imageStatusBasic"></p>

<script>
  const imgBasic = document.getElementById("myImageBasic");
  const statusBasic = document.getElementById("imageStatusBasic");

  function checkImageStatus() {
    if (imgBasic.complete) {
      statusBasic.textContent = "Image loaded successfully!";
    } else {
      statusBasic.textContent = "Image is still loading...";
    }
  }

  imgBasic.onload = checkImageStatus;
  checkImageStatus(); // Initial check in case the image is already cached
</script>

Output:
Initially, “Image is still loading…” might be displayed. Once the image loads completely, the text will change to “Image loaded successfully!”

Using complete to Trigger a Function

In this example, we use the complete property to trigger a function once the image has loaded.

<img id="myImageTrigger" src="https://dummyimage.com/200x200/28a745/fff" alt="Dummy Image" />
<p id="imageStatusTrigger"></p>

<script>
  const imgTrigger = document.getElementById("myImageTrigger");
  const statusTrigger = document.getElementById("imageStatusTrigger");

  function onImageLoad() {
    statusTrigger.textContent = "Image loaded! Performing action...";
    // Add your code here to perform actions after the image is loaded
  }

  if (imgTrigger.complete) {
    onImageLoad();
  } else {
    imgTrigger.onload = onImageLoad;
  }
</script>

Output:
Once the image loads, the text “Image loaded! Performing action…” will be displayed. You can add additional actions within the onImageLoad function.

Handling Image Errors

This example demonstrates how to handle image loading errors using the onerror event and the complete property.

<img id="myImageError" src="invalid-image-url.jpg" alt="Broken Image" />
<p id="imageStatusError"></p>

<script>
  const imgError = document.getElementById("myImageError");
  const statusError = document.getElementById("imageStatusError");

  imgError.onload = () => {
    statusError.textContent = "Image loaded successfully!";
  };

  imgError.onerror = () => {
    statusError.textContent = "Image failed to load.";
  };

  // Check if the image is already marked as complete but has no dimensions
  if (imgError.complete && (imgError.naturalWidth === 0 || typeof imgError.naturalWidth == 'undefined')) {
    statusError.textContent = "Image failed to load.";
  }
</script>

Output:
If the image fails to load (e.g., due to an invalid URL), the text “Image failed to load.” will be displayed.

Lazy Loading with complete

This example shows how to implement lazy loading for images and use the complete property to determine when to reveal the image.

<img
  id="myImageLazy"
  data-src="https://dummyimage.com/200x200/dc3545/fff"
  alt="Lazy Loaded Image"
  style="display: none;"
/>
<button id="loadButton">Load Image</button>

<script>
  const imgLazy = document.getElementById("myImageLazy");
  const loadButtonLazy = document.getElementById("loadButton");

  loadButtonLazy.addEventListener("click", () => {
    imgLazy.src = imgLazy.dataset.src; // Set the src to start loading

    imgLazy.onload = () => {
      imgLazy.style.display = "block"; // Show the image once loaded
    };
  });
</script>

Output:
Initially, the image is hidden. Clicking the “Load Image” button will start loading the image, and once it’s loaded, the image will be displayed.

Using complete with Canvas

This example demonstrates using the complete property with the Canvas API to draw an image onto a canvas once it has fully loaded.

<img id="myImageCanvas" src="https://dummyimage.com/100x100/ffc107/000" alt="Canvas Image" />
<canvas id="myCanvasComplete" width="150" height="150" style="border:1px solid #d3d3d3;">
Your browser does not support the HTML canvas tag.
</canvas>

<script>
  const imgCanvas = document.getElementById("myImageCanvas");
  const canvasComplete = document.getElementById("myCanvasComplete");
  const ctxComplete = canvasComplete.getContext("2d");

  function drawImageOnCanvas() {
    ctxComplete.drawImage(imgCanvas, 0, 0, canvasComplete.width, canvasComplete.height);
  }

  if (imgCanvas.complete) {
    drawImageOnCanvas();
  } else {
    imgCanvas.onload = drawImageOnCanvas;
  }
</script>

This code draws the image onto the canvas once it’s fully loaded, ensuring that the drawImage function has access to the complete image data.

Tips and Considerations

• Always check the complete property before performing any operations that depend on the image being fully loaded.
• Use the onload event to handle cases where the image is not yet loaded when the script is executed.
• Be aware that the complete property might return true even if the image is broken or the URL is invalid. Use the onerror event to handle such cases.
• For cached images, the complete property may be true immediately when the script runs.

Browser Support

The complete property is supported by all modern browsers.

• Chrome
• Firefox
• Safari
• Edge
• Opera

Conclusion

The complete property of the HTML <img> element is a useful tool for determining the loading status of an image. By using this property in conjunction with the onload and onerror events, you can create robust and responsive web applications that handle images efficiently. 🖼️