: The Image Embed element

Defines text that can replace the image in the page.

Note: Browsers do not always display images. There are a number of situations in which a browser might not display images, such as:

In these cases, the browser may replace the image with the text in the element's alt attribute. For these reasons and others, provide a useful value for alt whenever possible.

Setting this attribute to an empty string (alt="") indicates that this image is not a key part of the content (it's decoration or a tracking pixel), and that non-visual browsers may omit it from rendering. Visual browsers will also hide the broken image icon if the alt attribute is empty and the image failed to display.

This attribute is also used when copying and pasting the image to text, or saving a linked image to a bookmark.

specifies that you want the browser to send an Attribution-Reporting-Eligible header along with the image request.

On the server-side this is used to trigger sending an Attribution-Reporting-Register-Source or Attribution-Reporting-Register-Trigger header in the response, to register an image-based attribution source or attribution trigger, respectively. Which response header should be sent back depends on the value of the Attribution-Reporting-Eligible header that triggered the registration.

The corresponding source or trigger event is set off once the browser receives the response containing the image file.

Note: See the Attribution Reporting API for more details.

There are two versions of this attribute that you can set:

This is useful in cases where the requested resource is not on a server you control, or you just want to handle registering the attribution source on a different server. In this case, you can specify one or more URLs as the value of attributionsrc. When the resource request occurs the Attribution-Reporting-Eligible header will be sent to the URL(s) specified in attributionSrc in addition to the resource origin. These URLs can then respond with a Attribution-Reporting-Register-Source or Attribution-Reporting-Register-Trigger header as appropriate to complete registration.

Note: Specifying multiple URLs means that multiple attribution sources can be registered on the same feature. You might for example have different campaigns that you are trying to measure the success of, which involve generating different reports on different data.

Indicates if the fetching of the image must be done using a CORS request. Image data from a CORS-enabled image returned from a CORS request can be reused in the element without being marked "tainted".

If the crossorigin attribute is not specified, then a non-CORS request is sent (without the Origin request header), and the browser marks the image as tainted and restricts access to its image data, preventing its usage in elements.

If the crossorigin attribute is specified, then a CORS request is sent (with the Origin request header); but if the server does not opt into allowing cross-origin access to the image data by the origin site (by not sending any Access-Control-Allow-Origin response header, or by not including the site's origin in any Access-Control-Allow-Origin response header it does send), then the browser blocks the image from loading, and logs a CORS error to the devtools console.

Allowed values:

A CORS request is sent with credentials omitted (that is, no cookies, X.509 certificates, or Authorization request header).

The CORS request is sent with any credentials included (that is, cookies, X.509 certificates, and the Authorization request header). If the server does not opt into sharing credentials with the origin site (by sending back the Access-Control-Allow-Credentials: true response header), then the browser marks the image as tainted and restricts access to its image data.

If the attribute has an invalid value, browsers handle it as if the anonymous value was used. See CORS settings attributes for additional information.

This attribute provides a hint to the browser as to whether it should perform image decoding along with rendering the other DOM content in a single presentation step that looks more "correct" (sync), or render and present the other DOM content first and then decode the image and present it later (async). In practice, async means that the next paint does not wait for the image to decode.

It is often difficult to perceive any noticeable effect when using decoding on static elements. They'll likely be initially rendered as empty images while the image files are fetched (either from the network or from the cache) and then handled independently anyway, so the "syncing" of content updates is less apparent. However, the blocking of rendering while decoding happens, while often quite small, can be measured — even if it is difficult to observe with the human eye. See What does the image decoding attribute actually do? for a more detailed analysis (tunetheweb.com, 2023).

Using different decoding types can result in more noticeable differences when dynamically inserting elements into the DOM via JavaScript — see HTMLImageElement.decoding for more details.

Allowed values:

Decode the image synchronously along with rendering the other DOM content, and present everything together.

Decode the image asynchronously, after rendering and presenting the other DOM content.

No preference for the decoding mode; the browser decides what is best for the user. This is the default value.

Marks the image for observation by the PerformanceElementTiming API. The value given becomes an identifier for the observed image element. See also the elementtiming attribute page.

Provides a hint of the relative priority to use when fetching the image. Allowed values:

Signals a high-priority fetch relative to other images.

Signals a low-priority fetch relative to other images.

Default: Signals automatic determination of fetch priority relative to other images.

The intrinsic height of the image, in pixels. Must be an integer without a unit.

Note: Including height and width enables the aspect ratio of the image to be calculated by the browser prior to the image being loaded. This aspect ratio is used to reserve the space needed to display the image, reducing or even preventing a layout shift when the image is downloaded and painted to the screen. Reducing layout shift is a major component of good user experience and web performance.

This Boolean attribute indicates that the image is part of a server-side map. If so, the coordinates where the user clicked on the image are sent to the server.

Note: This attribute is allowed only if the element is a descendant of an element with a valid href attribute. This gives users without pointing devices a fallback destination.

Indicates how the browser should load the image:

Loads the image immediately, regardless of whether or not the image is currently within the visible viewport (this is the default value).

Defers loading the image until it reaches a calculated distance from the viewport, as defined by the browser. The intent is to avoid the network and storage bandwidth needed to handle the image until it's reasonably certain that it will be needed. This generally improves the performance of the content in most typical use cases.

Note: Loading is only deferred when JavaScript is enabled. This is an anti-tracking measure, because if a user agent supported lazy loading when scripting is disabled, it would still be possible for a site to track a user's approximate scroll position throughout a session, by strategically placing images in a page's markup such that a server can track how many images are requested and when. Note: Images with loading set to lazy will never be loaded if they do not intersect a visible part of an element, even if loading them would change that as unloaded images have a width and height of 0. Putting width and height on lazyloaded images fixes this issue and is a best practice, recommended by the specification. Doing so also helps prevent layout shifts.

A string indicating which referrer to use when fetching the resource:

One or more strings separated by commas, indicating a set of source sizes. Each source size consists of:

Media Conditions describe properties of the viewport, not of the image. For example, (max-height: 500px) 1000px proposes to use a source of 1000px width, if the viewport is not higher than 500px.

Source size values specify the intended display size of the image. User agents use the current source size to select one of the sources supplied by the srcset attribute, when those sources are described using width (w) descriptors. The selected source size affects the intrinsic size of the image (the image's display size if no CSS styling is applied). If the srcset attribute is absent, or contains no values with a width descriptor, then the sizes attribute has no effect.

The image URL. Mandatory for the element. On browsers supporting srcset, src is treated like a candidate image with a pixel density descriptor 1x, unless an image with this pixel density descriptor is already defined in srcset, or unless srcset contains w descriptors.

One or more strings separated by commas, indicating possible image sources for the user agent to use. Each string is composed of:

If no descriptor is specified, the source is assigned the default descriptor of 1x.

It is incorrect to mix width descriptors and pixel density descriptors in the same srcset attribute. Duplicate descriptors (for instance, two sources in the same srcset which are both described with 2x) are also invalid.

If the srcset attribute uses width descriptors, the sizes attribute must also be present, or the srcset itself will be ignored.

The user agent selects any of the available sources at its discretion. This provides them with significant leeway to tailor their selection based on things like user preferences or bandwidth conditions. See our Responsive images tutorial for an example.

The intrinsic width of the image in pixels. Must be an integer without a unit.

The partial URL (starting with #) of an image map associated with the element.

Note: You cannot use this attribute if the element is inside an or element.