JavaScript Document images Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property

Definition

Document.images is a read-only property that returns a live HTMLCollection of every <img> in the current HTML document. Each entry is an HTMLImageElement (MDN).

Read the notes below before you get or set this property. Prefer feature detection when support is limited.

Syntax

Use document.images. Start with this line.

JavaScript
document.images
CallWhat it does
document.imagesPrimary signature.

Built into the browser. Read or assign document.images — no import required.

Library declarations
JavaScript
document.images

Parameters

ParameterDescription
HTMLCollectionRequired. Live list of <img>

Return Value

Return ValueDescription
*Live HTMLCollection of HTMLImageElement

JavaScript Examples

Example 1 — Length and First Image

Count images and read the first with both index styles (MDN).

JavaScript
const imgs = document.images;

console.log(imgs.length);
console.log(imgs[0] === imgs.item(0));  // true when length > 0

if (imgs[0]) {
  console.log(imgs[0].alt);
}
Try It Yourself

How It Works

  1. Get the collection. document.images lists every <img>.
  2. Read length. That is how many image elements exist right now.
  3. Index either way. [0] and item(0) are equivalent (MDN).
  4. Guard empty pages. Check the first item exists before reading alt.

Example 2 — Find an Image by src (MDN idea)

Loop the collection and look for a specific filename.

JavaScript
for (const image of document.images) {
  if (image.getAttribute("src") === "banner.gif") {
    console.log("Found the banner");
  }
}
Try It Yourself

How It Works

  1. Iterate with for…of. Each value is an HTMLImageElement.
  2. Read the authored src. getAttribute("src") keeps the relative path.
  3. Match the filename. When it equals "banner.gif", log a hit.
  4. Tip: image.src alone is usually an absolute URL — prefer getAttribute for relative names.

Example 3 — The Collection Is Live

Append an <img> and watch document.images.length update.

JavaScript
const imgs = document.images;
console.log(imgs.length);  // before

const img = document.createElement("img");
img.alt = "Demo";
img.src = "demo.png";
document.body.appendChild(img);

console.log(imgs.length);  // after — increased by 1
Try It Yourself

How It Works

  1. Store the collection once. You do not need to call document.images again.
  2. Append a real <img>. Only image elements join this collection.
  3. Length updates live. MDN: the list stays current as the DOM changes.
  4. Contrast with QSA. A saved querySelectorAll("img") result would stay frozen.

Browser Support

Document.images is Baseline Widely available (MDN: since June 2018). Safe to use in modern and older evergreen browsers.

✓ Baseline · Widely available

Document.images

Read-only live HTMLCollection of every <img> element in the document.

99% Widely available
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
document.images Excellent

Bottom line: Safe for production. Use document.images for a live list of img elements; use querySelectorAll when you need CSS selectors or a static snapshot.

Frequently Asked Questions

A read-only HTMLCollection of every <img> element in the document. Each item is an HTMLImageElement (MDN).
No. MDN marks Document.images as Baseline Widely available (since June 2018). It is not Deprecated, Experimental, or Non-standard.
Yes. MDN describes it as a live list — when images are added or removed, document.images updates automatically.
Use document.images[0] or document.images.item(0). MDN notes both are equivalent.
document.images is a live HTMLCollection of img elements only. querySelectorAll returns a static NodeList and accepts any CSS selector.
No. Only <img> elements in the HTML document — not CSS background-image, and not inline SVG drawn without an <img> tag.

Next: implementation

Learn the Document property that exposes DOMImplementation.

implementation tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful