recursal/MDN huggingface dataset:
HTMLImageElement: decode() method
=================================

 The **`decode()`**
 method of the `HTMLImageElement` interface returns a
 `Promise` that resolves once the image is decoded and it is safe to append
 it to the DOM.

 This can be used to initiate loading of the image prior
 to attaching it to an element in the DOM (or adding it to the DOM as a new element), so
 that the image can be rendered immediately upon being added to the DOM. This, in turn,
 prevents the rendering of the next frame after adding the image to the DOM from causing
 a delay while the image loads.

Syntax
------


```js
decode()
```

### Parameters

None.

### Return value

A `Promise` that fulfills with `undefined` once the image data is ready to be used.

### Exceptions

`EncodingError`

 A `DOMException` indicating that an error occurred while decoding the
 image.


Usage notes
-----------

 One potential use case for `decode()`: when loading very large images (for
 example, in an online photo album), you can present a low resolution thumbnail image
 initially and then replace that image with the full-resolution image by instantiating a
 new `HTMLImageElement`, setting its source to the full-resolution image's
 URL, then using `decode()` to get a promise which is resolved once the
 full-resolution image is ready for use. At that time, you can then replace the
 low-resolution image with the full-resolution one that's now available.

Examples
--------

### Basic usage

 The following example shows how to use the `decode()` method to control when
 an image is appended to the DOM.


```js
const img = new Image();
img.src = "nebula.jpg";
img
  .decode()
  .then(() => {
    document.body.appendChild(img);
  })
  .catch((encodingError) => {
    // Do something with the error.
  });
```


**Note:** Without a `Promise`-returning method, you
 would add the image to the DOM in a `load` event handler,
 and handle the error in the `error` event's handler.


### Avoiding empty images

In the below example, you'll likely get an empty image shown on the page as the image is downloaded:


```js
const img = new Image();
img.src = "img/logo.png";
document.body.appendChild(img);
```


Using `decode()` will delay inserting the image into the DOM until it is fully downloaded and decoded, thereby avoiding the empty image problem:


```js
async function getImage() {
  const img = new Image();
  img.src = "img/logo.png";
  await img.decode();
  document.body.appendChild(img);
  const p = document.createElement("p");
  p.textContent = "Image is fully loaded!";
  document.body.appendChild(p);
}
```


This is particularly useful if you're dynamically swapping an existing image for a new one, and also prevents unrelated paints outside of this code from being held up while the image is decoding.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-img-decode-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* What does the image decoding attribute actually do? on tunetheweb.com (2023)
* The `HTMLImageElement.decoding` property
HTMLImageElement: complete property
===================================

 The read-only `HTMLImageElement` interface's
 **`complete`** attribute is a Boolean value which indicates
 whether or not the image has completely loaded.

Value
-----

 A Boolean value which is `true` if the image has completely loaded;
 otherwise, the value is `false`.

The image is considered completely loaded if any of the following are true:

* Neither the `src` nor the `srcset`
 attribute is specified.
* The `srcset` attribute is absent and the `src` attribute,
 while specified, is the empty string (`""`).
* The image resource has been fully fetched and has been queued for
 rendering/compositing.
* The image element has previously determined that the image is fully available and
 ready for use.
* The image is "broken;" that is, the image failed to load due to an error or because
 image loading is disabled.

 It's worth noting that due to the image potentially being received asynchronously, the
 value of `complete` may change while your script is running.

Examples
--------

 Consider a photo library app that provides the ability to open images into a lightbox
 mode for improved viewing as well as editing of the image. These photos may be very
 large, so you don't want to wait for them to load, so your code
 uses `async`/`await` to load the images in the background.

 But imagine that you have other code that needs to only run when the image has
 completed loading, such as a command that performs red-eye removal on the image in the
 lightbox. While ideally this command wouldn't even be executed if the image hasn't fully
 loaded, for improved reliability you want to check to ensure this is the case.

 So the `fixRedEyeCommand()` function, which is called by the button that
 triggers red-eye removal, checks the value of the lightbox
 image's `complete` property before attempting to do its work. This is
 demonstrated in the code below.


```js
let lightboxElem = document.querySelector("#lightbox");
let lightboxImgElem = lightboxElem.querySelector("img");
let lightboxControlsElem = lightboxElem.querySelector(".toolbar");

async function loadImage(url, elem) {
  return new Promise((resolve, reject) => {
    elem.onload = () => resolve(elem);
    elem.onerror = reject;
    elem.src = url;
  });
}

async function lightBox(url) {
  lightboxElem.style.display = "block";
  await loadImage("https://somesite.net/huge-image.jpg", lightboxImgElem);
  lightboxControlsElem.disabled = false;
}

// …

function fixRedEyeCommand() {
  if (lightboxElem.style.display === "block" && lightboxImgElem.complete) {
    fixRedEye(lightboxImgElem);
  } else {
    /\* can't start doing this until the image is fully loaded \*/
  }
}
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-img-complete-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTMLImageElement: width property
================================

 The **`width`** property of the
 `HTMLImageElement` interface indicates the width at which an image is
 drawn in CSS pixels if it's being drawn or rendered to
 any visual medium such as a screen or printer. Otherwise, it's the natural, pixel
 density-corrected width of the image.

Value
-----

 An integer value indicating the width of the image. The way the width is defined
 depends on whether or not the image is being rendered to a visual medium, such as a
 screen or printer:

* If the image is being rendered to a visual medium, the width is expressed in
 CSS pixels.
* If the image is not being rendered to a visual medium, its width is represented
 using the image's natural (intrinsic) width, adjusted for the display density as
 indicated by `naturalWidth`.
Examples
--------

 In this example, two different sizes are provided for an image of a clock using the
 `srcset` attribute. One is 200px wide and the other is 400px
 wide. The `sizes` attribute is used to specify the width at
 which the image should be drawn given the viewport's width.

### HTML

 For viewports up to 400px wide, the image is drawn at a width of 200px. Otherwise, it's
 drawn at 400px.


```html
<p>Image width: <span class="size">?</span>px (resize to update)</p>
<img
 src="/en-US/docs/Web/HTML/Element/img/clock-demo-200px.png"
 alt="Clock"
 srcset="
 /en-US/docs/Web/HTML/Element/img/clock-demo-200px.png 200w,
 /en-US/docs/Web/HTML/Element/img/clock-demo-400px.png 400w
 "
 sizes="(max-width: 400px) 200px, 400px" />
```

### JavaScript

 JavaScript looks at the `width` property to determine the width of the image
 at the moment. This is performed in the window's `load` and `resize` event handlers so the most
 current width information is always available.


```js
const clockImage = document.querySelector("img");
let output = document.querySelector(".size");

const updateWidth = (event) => {
  output.innerText = clockImage.width;
};

window.addEventListener("load", updateWidth);
window.addEventListener("resize", updateWidth);
```

### Result

This example may be easier to try out in its own window.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-img-width-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `HTMLCanvasElement.width`
* `HTMLObjectElement.width`
* `HTMLVideoElement.width`
HTMLImageElement: isMap property
================================

 The `HTMLImageElement` property **`isMap`** is a
 Boolean value which indicates that the image is to be used by a server-side image map.
 This may only be used on images located within an `<a>` element.


**Note:** For accessibility reasons, you should generally avoid using
 server-side image maps, as they require the use of a mouse. Use a client-side image map instead.


Value
-----

 A Boolean value which is `true` if the image is being used for a server-side
 image map; otherwise, the value is `false`.

Usage notes
-----------

 When an image marked as being part of a server-side image map is clicked, the browser
 constructs the string "?x,y", where x and y indicate the coordinates at which the
 mouse was clicked as offsets from the top-left corner of the image, specified in CSS
 pixels.

 The browser then fetches that URL from the server and displays or downloads it
 depending on the value of the `download` attribute.

 Unlike server-side image maps, client-side image maps don't cause the
 `<img>` element to adopt interactive content mode.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-img-ismap |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTMLImageElement: fetchPriority property
========================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`fetchPriority`** property of the
 `HTMLImageElement` interface represents a hint given to the browser on how
 it should prioritize the fetch of the image relative to other images.

Value
-----

A string representing the priority hint. Possible values are:

`high`

Fetch the image at a high priority relative to other images.

`low`

Fetch the image at a low priority relative to other images.

`auto`

 Default mode, which indicates no preference for the fetch priority.
 The browser decides what is best for the user.



 The `fetchPriority` property allows you to signal high or low priority image
 fetches. This can be useful when applied to `<img>` elements
 to signal images that are "important" to the user experience early in the
 loading process.

 The effects of the hint on resource loading is browser-specific so make sure to
 test on multiple browser engines.

 Use it sparingly for exceptional cases where the browser may not be able to
 infer the best way to load the image automatically. Over use can result in
 degrading performance.

Examples
--------


```js
const img = new Image();
img.fetchPriority = "high";
img.src = "img/logo.png";
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # attr-img-fetchpriority |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTMLImageElement: align property
================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

 The *obsolete* **`align`**
 property of the `HTMLImageElement` interface is a string which indicates
 how to position the image relative to its container.

 You should instead use the
 CSS property `vertical-align`, which does in fact also work on images
 despite its name. You can also use the `float` property to float the image
 to the left or right margin.

 The `align` property reflects the HTML `align`
 content attribute.

Value
-----

 A string specifying one of the following strings which set the
 alignment mode for the image.

### Baseline alignment

 These three values specify the alignment of the element relative to the text baseline.
 These should be replaced by using the CSS `vertical-align` property.

`bottom`

 The bottom edge of the image is to be aligned vertically with the current text
 baseline. **Default value.**

`middle`

The center of the object should be aligned vertically with the current baseline.

`top`

The top edge of the object should be aligned vertically with the current baseline.


 It may be worth noting that `vertical-align` offers several additional
 options for its value; you may wish to consider these when changing your code to use it.

### Floating images horizontally

 The `left` and `right` properties don't affect the
 baseline-relative alignment. Instead, they cause the image to "float" to the left or
 right margin, allowing the following text to flow around the image. You should instead
 use the CSS `float` property, specifying as the value
 either `left` or `right`.

`left`

 Floats the image over to place the left edge flush against the current margin. Any
 text that follows will flow against the image's right edge.


`right`

 Floats the image to place its right edge flush against the right margin. Subsequent
 text will flow along the image's left edge.


Specifications
--------------

| Specification |
| --- |
| HTML Standard # attr-img-align |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTMLImageElement: border property
=================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

 The obsolete `HTMLImageElement`
 property **`border`** specifies the number of pixels thick the
 border surrounding the image should be. A value of 0, the default, indicates that no
 border should be drawn.

 You should *not* use this property! Instead, you should use CSS to style the
 border. The `border` property or its longhand properties to not only set
 the thickness of the border but to potentially apply a wide variety of other styling
 options to it.

 The width, specifically, is controlled using the writing-mode aware
 `border-block-start-width`, `border-block-end-width`,
 `border-inline-start-width`, and `border-inline-end-width`
 properties.

 For compatibility (or perhaps other) reasons, you can use the older properties instead
 (or in addition): `border-top-width`, `border-right-width`,
 `border-bottom-width`, and `border-left-width`.

Value
-----

 A string containing an integer value specifying the thickness of the
 border that should surround the image, in CSS pixels. A value of `0`, or an
 empty string, indicates that there should be no border drawn. The default value of
 `border` is `0`

Usage notes
-----------

 Do not use `border`. It is obsolete. Instead, use the CSS
 `border` property and its longhand properties to establish borders around
 images.

For example, if you have the following HTML:


```html
<img src="image.png" border="2" />
```


 The following will provide the same appearance using CSS instead of this obsolete
 property:


```html
<img src="image.png" style="border: 2px;" />
```


 You can further provide additional information to change the color and other features
 of the border:


```html
<img src="image.png" style="border: dashed 2px #333388;" />
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-img-border |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTMLImageElement: longDesc property
===================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

 The *deprecated* property **`longDesc`** on
 the `HTMLImageElement` interface specifies the URL of a text or HTML file
 which contains a long-form description of the image. This can be used to
 provide optional added details beyond the short description provided in the
 `title` attribute.

Value
-----

 A string which may be either an empty string (indicating that no long
 description is available) or the URL of a file containing a long form description of the
 image's contents.

 For example, if the image is a PNG of a flowchart.
 The `longDesc` property could be used to provide an explanation of the flow
 of control represented by the chart, using only text. This can be used by readers both
 as an explanation, but also as a substitute for visually-impaired users.

Usage notes
-----------

 This property is *deprecated* and should no longer be used. Instead of
 using `longDesc` to provide a link to a detailed description of an image,
 encapsulate the image within a link using the `<a>` element.

Consider the following older HTML:


```html
<img
 src="taco-tuesday.jpg"
 alt="Taco Tuesday"
 longdesc="image-descriptions/taco-tuesday.html" />
```


 Here, the `longDesc` is used to indicate that the user should be able to
 access a detailed description of the image `taco-tuesday.jpg` in the HTML
 file `image-descriptions/taco-tuesday.html`.

This can be easily converted into modern HTML:


```html
<a href="image-descriptions/taco-tuesday.html">
  <img src="taco-tuesday.jpg" alt="Taco Tuesday" />
</a>
```


With that, the image is a link to the HTML file describing the image in more detail.

Specifications
--------------

This feature is not part of any current specification. It is no longer on track to become a standard.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `aria-details`
HTMLImageElement: name property
===============================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

 The `HTMLImageElement`
 interface's *deprecated* **`name`** property specifies
 a name for the element. This has been replaced by the `id`
 property available on all elements.

Value
-----

A string providing a name by which the image can be referenced.

**Warning:** This property is deprecated and is only in the
 specification still for backward compatibility purposes. Since it functions
 identically to `id`, you can and should use it instead.


Specifications
--------------

| Specification |
| --- |
| HTML Standard # attr-img-name |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTMLImageElement: Image() constructor
=====================================

 The **`Image()`**
 constructor creates a new `HTMLImageElement` instance. It is functionally
 equivalent to `document.createElement('img')`.

**Note:** This function should not be confused with the CSS `image()` function.

Syntax
------


```js
new Image()
new Image(width)
new Image(width, height)
```

### Parameters

`width` Optional

 The width of the image (i.e., the value for the `width`
 attribute).


`height` Optional

 The height of the image (i.e., the value for the `height`
 attribute).


Usage note
----------

 The entire bitmap is loaded regardless of the sizes specified in the constructor. The
 size specified in the constructor is reflected through the properties
 `HTMLImageElement.width` and `HTMLImageElement.height` of the
 resulting instance. The intrinsic width and height of the image in CSS pixels are
 reflected through the properties `HTMLImageElement.naturalWidth` and
 `HTMLImageElement.naturalHeight`. If no size is specified in the
 constructor both pairs of properties have the same values.

Examples
--------


```js
const myImage = new Image(100, 200);
myImage.src = "picture.jpg";
document.body.appendChild(myImage);
```


 This would be the equivalent of defining the following HTML tag inside the
 `<body>`:


```html
<img width="100" height="200" src="picture.jpg" />
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-image-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTMLImageElement: y property
============================

 The read-only `HTMLImageElement` property
 **`y`** indicates the y-coordinate of the
 `<img>` element's top border edge relative to the root element's
 origin.

 The `x` and `y` properties are only valid
 for an image if its `display` property has the computed value
 `table-column` or `table-column-group`. In other words: it has
 either of those values set explicitly on it, or it has inherited it from a containing
 element, or by being located within a column described by either
 `<col>` or `<colgroup>`.

Value
-----

 An integer value indicating the distance in pixels from the top edge of the element's
 nearest root element to the top edge of the `<img>` element's border
 box. The nearest root element is the outermost `<html>` element that
 contains the image. If the image is in an `<iframe>`, its
 `y` is relative to that frame.

 In the diagram below, the top border edge is the top edge of the blue padding area. So
 the value returned by `y` would be the distance from that point to the top
 edge of the content area.

![Diagram showing the relationships between the various boxes associated with an element](/en-US/docs/Web/API/HTMLImageElement/y/boxmodel-3.png)


**Note:** The `y` property is only valid if the computed
 value of the image's `display` property is either
 `table-column` or `table-column-group`; in other words,
 either of those are set directly on the `<img>` or they're
 inherited from a containing element or by being located within a column described
 by either `<col>` or `<colgroup>`.


Example
-------

See `HTMLImageElement.x` for example code that demonstrates the use of the `HTMLImageElement.y` (and `HTMLImageElement.x`).

Specifications
--------------

| Specification |
| --- |
| CSSOM View Module # dom-htmlimageelement-y |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.