HTML Standard

HTML Standard
4.8
Embedded content
4.8.1
The
picture
element
4.8.2
The
source
element
4.8.3
The
img
element
4.8
Embedded content
4.8.1
The
picture
element
Element/picture
Support in all current engines.
Firefox
38+
Safari
9.1+
Chrome
38+
Opera
Edge
79+
Edge (Legacy)
13+
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
HTMLPictureElement
Support in all current engines.
Firefox
38+
Safari
9.1+
Chrome
38+
Opera
Edge
79+
Edge (Legacy)
13+
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
Categories
Flow content
Phrasing content
Embedded content
Palpable content
Contexts in which this element can be used
Where
embedded content
is expected.
Content model
Zero or more
source
elements, followed by one
img
element,
optionally intermixed with
script-supporting elements
Tag omission in text/html
Neither tag is omissible.
Content attributes
Global attributes
Accessibility considerations
For authors
For implementers
DOM interface
Exposed
Window
interface
HTMLPictureElement
HTMLElement
HTMLConstructor
constructor
();
};
The
picture
element is a container
which provides multiple sources to its contained
img
element
to allow authors to declaratively control or give hints to the user agent about which image resource to use,
based on the screen pixel density,
viewport
size, image format, and other factors.
It
represents
its children.
The
picture
element is somewhat different from the similar-looking
video
and
audio
elements. While all of them contain
source
elements, the
source
element's
src
attribute
has no meaning when the element is nested within a
picture
element, and the resource
selection algorithm is different. Also, the
picture
element itself does not display
anything; it merely provides a context for its contained
img
element that enables it
to choose from multiple
URLs
4.8.2
The
source
element
Element/source
Support in all current engines.
Firefox
3.5+
Safari
3.1+
Chrome
3+
Opera
Edge
79+
Edge (Legacy)
12+
Internet Explorer
9+
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
HTMLSourceElement
Support in all current engines.
Firefox
3.5+
Safari
3.1+
Chrome
3+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
9+
Firefox Android
Safari iOS
Chrome Android
WebView Android
37+
Samsung Internet
Opera Android
12.1+
Categories
None.
Contexts in which this element can be used
As a child of a
picture
element, before the
img
element.
As a child of a
media element
, before any
flow content
or
track
elements.
Content model
Nothing
Tag omission in text/html
No
end tag
Content attributes
Global attributes
type
— Type of embedded resource
media
— Applicable media
src
(in
audio
or
video
) — Address of the resource
srcset
(in
picture
) — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes
(in
picture
) — Image sizes for different page layouts
width
(in
picture
) — Horizontal dimension
height
(in
picture
) — Vertical dimension
Accessibility considerations
For authors
For implementers
DOM interface
Exposed
Window
interface
HTMLSourceElement
HTMLElement
HTMLConstructor
constructor
();

CEReactions
ReflectURL
attribute
USVString
src
CEReactions
Reflect
attribute
DOMString
type
CEReactions
Reflect
attribute
USVString
srcset
CEReactions
Reflect
attribute
DOMString
sizes
CEReactions
Reflect
attribute
DOMString
media
CEReactions
Reflect
attribute
unsigned
long
width
CEReactions
Reflect
attribute
unsigned
long
height
};
The
source
element allows authors to specify multiple alternative
source sets
for
img
elements or multiple alternative
media resources
for
media
elements
. It does not
represent
anything on its own.
The
type
attribute
may be present. If present, the value must be a
valid MIME type string
The
media
attribute may also be present. If present, the value must contain a
valid media query
list
. The user agent will skip to the next
source
element if the value does
not
match the environment
The
media
attribute is only evaluated
once during the
resource selection algorithm
for
media elements
. In contrast, when using the
picture
element, the user agent will
react to
changes in the environment
The remainder of the requirements depend on whether the parent is a
picture
element or a
media element
The
source
element's parent is a
picture
element
The
srcset
attribute must be present, and is a
srcset attribute
The
srcset
attribute contributes the
image sources
to the
source set
, if the
source
element is selected.
If the
srcset
attribute has any
image candidate strings
using a
width descriptor
, the
sizes
attribute may also be present. If, additionally,
the following sibling
img
element does not
allow
auto-sizes
, the
sizes
attribute must be present.
The
sizes
attribute is a
sizes attribute
, which contributes the
source size
to
the
source set
, if the
source
element is selected.
If the
img
element
allows auto-sizes
, then the
sizes
attribute can be omitted on previous sibling
source
elements. In such cases, it is equivalent to specifying
auto
The
source
element supports
dimension attributes
. The
img
element can use the
width
and
height
attributes of a
source
element, instead of
those on the
img
element itself, to determine its rendered dimensions and
aspect-ratio,
as defined in the Rendering section
The
type
attribute gives the type of the images in the
source set
, to allow the user agent to skip to the next
source
element
if it does not support the given type.
If the
type
attribute is
not
specified, the user agent will not select a different
source
element if it finds
that it does not support the image format after fetching it.
When a
source
element has a following sibling
source
element or
img
element with a
srcset
attribute
specified, it must have at least one of the following:
media
attribute specified with a value that,
after
stripping leading and trailing
ASCII whitespace
, is not the empty string and is not an
ASCII
case-insensitive
match for the string "
all
".
type
attribute specified.
The
src
attribute must not be present.
The
source
element's parent is a
media element
The
src
attribute
gives the
URL
of the
media resource
. The value must be a
valid
non-empty URL potentially surrounded by spaces
. This attribute must be present.
The
type
attribute gives the type of the
media
resource
, to help the user agent determine if it can play this
media
resource
before fetching it. The
codecs
parameter, which certain
MIME types define, might be necessary to specify exactly how the resource is encoded.
[RFC6381]
Dynamically modifying a
source
element's
src
or
type
attribute
when the element is already inserted in a
video
or
audio
element will
have no effect. To change what is playing, just use the
src
attribute on the
media element
directly, possibly making use of the
canPlayType()
method to pick from amongst available
resources. Generally, manipulating
source
elements manually after the document has
been parsed is an unnecessarily complicated approach.
The following list shows some examples of how to use the
codecs=
MIME
parameter in the
type
attribute.
H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container
source
src
'video.mp4'
type
'video/mp4; codecs="avc1.42E01E, mp4a.40.2"'
H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container
source
src
'video.mp4'
type
'video/mp4; codecs="avc1.58A01E, mp4a.40.2"'
H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container
source
src
'video.mp4'
type
'video/mp4; codecs="avc1.4D401E, mp4a.40.2"'
H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container
source
src
'video.mp4'
type
'video/mp4; codecs="avc1.64001E, mp4a.40.2"'
MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container
source
src
'video.mp4'
type
'video/mp4; codecs="mp4v.20.8, mp4a.40.2"'
MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container
source
src
'video.mp4'
type
'video/mp4; codecs="mp4v.20.240, mp4a.40.2"'
MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container
source
src
'video.3gp'
type
'video/3gpp; codecs="mp4v.20.8, samr"'
Theora video and Vorbis audio in Ogg container
source
src
'video.ogv'
type
'video/ogg; codecs="theora, vorbis"'
Theora video and Speex audio in Ogg container
source
src
'video.ogv'
type
'video/ogg; codecs="theora, speex"'
Vorbis audio alone in Ogg container
source
src
'audio.ogg'
type
'audio/ogg; codecs=vorbis'
Speex audio alone in Ogg container
source
src
'audio.spx'
type
'audio/ogg; codecs=speex'
FLAC audio alone in Ogg container
source
src
'audio.oga'
type
'audio/ogg; codecs=flac'
Dirac video and Vorbis audio in Ogg container
source
src
'video.ogv'
type
'video/ogg; codecs="dirac, vorbis"'
The
srcset
and
sizes
attributes must not be present.
The
source
HTML element insertion steps
, given
insertedNode
, are:
Let
parent
be
insertedNode
's
parent
If
parent
is a
media element
that has no
src
attribute and whose
networkState
has the value
NETWORK_EMPTY
, then invoke that
media
element
's
resource selection
algorithm
If
parent
is a
picture
element, then
for each
child
of
parent
's
children
, if
child
is an
img
element,
then count this as a
relevant mutation
for
child
The
source
HTML element moving steps
, given
movedNode
isSubtreeRoot
, and
oldAncestor
are:
If
isSubtreeRoot
is true and
oldAncestor
is a
picture
element, then
for each
child
of
oldAncestor
's
children
: if
child
is an
img
element, then count this as a
relevant
mutation
for
child
The
source
HTML element removing steps
, given
removedNode
isSubtreeRoot
, and
oldAncestor
are:
If
isSubtreeRoot
is true and
oldAncestor
is a
picture
element, then
for each
child
of
oldAncestor
's
children
: if
child
is an
img
element, then count this as a
relevant
mutation
for
child
If the author isn't sure if user agents will all be able to render the media resources
provided, the author can listen to the
error
event on the last
source
element and trigger fallback behavior:
script
function
fallback
video
// replace

CEReactions
Reflect
attribute
DOMString
alt
CEReactions
ReflectURL
attribute
USVString
src
CEReactions
Reflect
attribute
USVString
srcset
CEReactions
Reflect
attribute
DOMString
sizes
CEReactions
attribute
DOMString
crossOrigin
CEReactions
Reflect
attribute
DOMString
useMap
CEReactions
Reflect
attribute
boolean
isMap
CEReactions
Reflect
attribute
boolean
controls
CEReactions
ReflectSetter
attribute
unsigned
long
width
CEReactions
ReflectSetter
attribute
unsigned
long
height
readonly
attribute
unsigned
long
naturalWidth
readonly
attribute
unsigned
long
naturalHeight
readonly
attribute
boolean
complete
readonly
attribute
USVString
currentSrc
CEReactions
attribute
DOMString
referrerPolicy
CEReactions
attribute
DOMString
decoding
CEReactions
attribute
DOMString
loading
CEReactions
attribute
DOMString
fetchPriority
Promise
undefined
decode
();

//
also has obsolete members
};
An
img
element represents an image.
An
img
element has a
dimension
attribute source
, initially set to the element itself.
HTMLImageElement/src
Support in all current engines.
Firefox
1+
Safari
3+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
5.5+
Firefox Android
Safari iOS
1+
Chrome Android
WebView Android
Samsung Internet
Opera Android
12.1+
Element/img#attr-srcset
Support in all current engines.
Firefox
38+
Safari
8+
Chrome
34+
Opera
Edge
79+
Edge (Legacy)
≤18+
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
The image given by the
src
and
srcset
attributes, and
any previous sibling
source
elements'
srcset
attributes if the parent is a
picture
element, is the embedded content; the value of
the
alt
attribute provides
equivalent content for those who cannot process images or who have image loading disabled (i.e.,
it is the
img
element's
fallback content
).
The requirements on the
alt
attribute's value are described
in a separate section
At least one of the
src
and
srcset
attributes must be present.
If the
src
attribute is present, it must contain a
valid non-empty URL potentially surrounded by spaces
referencing a non-interactive,
optionally animated, image resource that is neither paged nor scripted.
The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs,
JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element),
animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG
document element
that use declarative SMIL animation), and so forth. However, these
definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML
documents, plain text documents, and the like.
[PNG]
[GIF]
[JPEG]
[PDF]
[XML]
[APNG]
[SVG]
[MNG]
The
srcset
attribute is a
srcset
attribute
The
srcset
attribute and the
src
attribute (if
width
descriptors
are not used) contribute the
image sources
to the
source set
(if no
source
element was selected).
If the
srcset
attribute is present and has any
image candidate strings
using a
width
descriptor
, the
sizes
attribute must also be present.
If the
srcset
attribute is
not
specified, and the
loading
attribute is in the
Lazy
state, the
sizes
attribute may be specified with the value "
auto
" (
ASCII case-insensitive
). The
sizes
attribute is a
sizes attribute
which contributes the
source size
to the
source set
(if no
source
element was selected).
An
img
element
allows auto-sizes
if:
its
loading
attribute is in the
Lazy
state, and
its
sizes
attribute's value is "
auto
" (
ASCII case-insensitive
), or starts with "
auto,
" (
ASCII case-insensitive
).
Attributes/crossorigin
Support in all current engines.
Firefox
8+
Safari
6+
Chrome
13+
Opera
Edge
79+
Edge (Legacy)
12+
Internet Explorer
Yes
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
The
crossorigin
attribute is a
CORS settings attribute
. Its purpose is to allow images from
third-party sites that allow cross-origin access to be used with
canvas
The
referrerpolicy
attribute is a
referrer
policy attribute
. Its purpose is to set the
referrer policy
used when
fetching
the image.
[REFERRERPOLICY]
The
decoding
attribute indicates the preferred method to
decode
this
image. The attribute, if present, must be an
image decoding hint
. This attribute's
missing value default
and
invalid value default
are both the
Auto
state.
HTMLImageElement/fetchPriority
Firefox
No
Safari
🔰 preview+
Chrome
102+
Opera
Edge
102+
Edge (Legacy)
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
The
fetchpriority
attribute is a
fetch
priority attribute
. Its purpose is to set the
priority
used when
fetching
the image.
The
loading
attribute is a
lazy
loading attribute
. Its purpose is to indicate the policy for loading images that are
outside the viewport.
When the
loading
attribute's state is changed to the
Eager
state, the user agent must run these
steps:
Let
resumptionSteps
be the
img
element's
lazy load
resumption steps
If
resumptionSteps
is null, then return.
Set the
img
's
lazy load resumption steps
to null.
Invoke
resumptionSteps
img
src
"1.jpeg"
alt
"1"
img
src
"2.jpeg"
loading
eager
alt
"2"
img
src
"3.jpeg"
loading
lazy
alt
"3"
div
id
very-large
>div

img
src
"4.jpeg"
alt
"4"
img
src
"5.jpeg"
loading
lazy
alt
"5"
In the example above, the images load as follows:
1.jpeg
2.jpeg
4.jpeg
The images load eagerly and delay the window's load event.
3.jpeg
The image loads when layout is known, due to being in the viewport, however it does not
delay the window's load event.
5.jpeg
The image loads only once scrolled into the viewport, and does not delay the window's
load event.
Developers are encouraged to specify a preferred aspect ratio via
width
and
height
attributes
on lazy loaded images, even if CSS sets the image's width and height properties, to prevent the
page layout from shifting around after the image loads.
The
img
HTML element insertion steps
, given
insertedNode
are:
If
insertedNode
's parent is a
picture
element, then, count this as
relevant mutation
for
insertedNode
The
img
HTML element moving steps
, given
movedNode
isSubtreeRoot
, and
oldAncestor
are:
If
isSubtreeRoot
is true and
oldAncestor
is a
picture
element, then count this as a
relevant mutation
for
movedNode
The
img
HTML element removing steps
, given
removedNode
oldAncestor
, and
isSubtreeRoot
are:
If
isSubtreeRoot
is true and
oldAncestor
is a
picture
element, then count this as a
relevant mutation
for
removedNode
The
img
element must not be used as a layout tool. In particular,
img
elements should not be used to display transparent images, as such images rarely convey meaning and
rarely add anything useful to the document.
What an
img
element represents depends on the
src
attribute and the
alt
attribute.
If the
src
attribute is set and the
alt
attribute is set to the empty string
The image is either decorative or supplemental to the rest of the content, redundant with
some other information in the document.
If the image is
available
and the user agent is configured
to display that image, then the element
represents
the element's image data.
Otherwise, the element
represents
nothing, and may be omitted completely from
the rendering. User agents may provide the user with a notification that an image is present but
has been omitted from the rendering.
If the
src
attribute is set and the
alt
attribute is set to a value that isn't empty
The image is a key part of the content; the
alt
attribute
gives a textual equivalent or replacement for the image.
If the image is
available
and the user agent is configured
to display that image, then the element
represents
the element's image data.
Otherwise, the element
represents
the text given by the
alt
attribute. User agents may provide the user with a notification
that an image is present but has been omitted from the rendering.
If the
src
attribute is set and the
alt
attribute is not
The image might be a key part of the content, and there is no textual equivalent of the image
available.
In a conforming document, the absence of the
alt
attribute indicates that the image is a key part of the content
but that a textual replacement for the image was not available when the image was generated.
If the image is
available
and the user agent is configured
to display that image, then the element
represents
the element's image data.
If the image has a
src
attribute whose value is
the empty string, then the element
represents
nothing.
Otherwise, the user agent should display some sort of indicator that there is an image that
is not being rendered, and may, if requested by the user, or if so configured, or when required
to provide contextual information in response to navigation, provide caption information for the
image, derived as follows:
If the image has a
title
attribute whose value is not
the empty string, then return the value of that attribute.
If the image is a descendant of a
figure
element that has a child
figcaption
element, and, ignoring the
figcaption
element and its
descendants, the
figure
element has no
flow content
descendants other
than
inter-element whitespace
and the
img
element, then return the
contents of the first such
figcaption
element.
Return nothing. (There is no caption information.)
If the
src
attribute is not set and either the
alt
attribute is set to the empty string or the
alt
attribute is not set at all
The element
represents
nothing.
Otherwise
The element
represents
the text given by the
alt
attribute.
The
alt
attribute does not represent advisory information.
User agents must not present the contents of the
alt
attribute
in the same way as content of the
title
attribute.
User agents may always provide the user with the option to display any image, or to prevent any
image from being displayed. User agents may also apply heuristics to help the user make use of the
image when the user is unable to see it, e.g. due to a visual disability or because they are using
a text terminal with no graphics capabilities. Such heuristics could include, for instance,
optical character recognition (OCR) of text found within the image.
While user agents are encouraged to repair cases of missing
alt
attributes, authors must not rely on such behavior.
Requirements for providing text to act as an alternative for images
are described
in detail below.
The
contents
of
img
elements, if any, are ignored for the purposes of
rendering.
The
usemap
attribute,
if present, can indicate that the image has an associated
image map
The
ismap
attribute,
when used on an element that is a descendant of an
element with an
href
attribute, indicates by its presence that the element
provides access to a server-side image map. This affects how events are handled on the
corresponding
element.
The
ismap
attribute is a
boolean attribute
. The attribute must not be specified
on an element that does not have an ancestor
element
with an
href
attribute.
The
usemap
and
ismap
attributes can result in confusing behavior when used
together with
source
elements with the
media
attribute specified in a
picture
element.
The
controls
attribute is a
boolean attribute
. If present, it indicates that the user agent may
expose a user interface to the user. The attribute must not be specified on an element that does
not have an
alt
attribute, or whose
alt
attribute's value is the empty string.
If the
controls
attribute is present, the user agent
may expose controls over the image (e.g., a control for fullscreen viewing). The specific
controls provided are
implementation-defined
, and can be platform-specific or based
on the user's preferences.
If the user agent exposes a user interface by displaying controls over the
img
element, then the user agent should suppress any user interaction events while the user agent is
interacting with this interface.
Issue #12318
tracks
the interaction between image controls and animated images. User agents should not expose
animation controls for images before that issue is resolved.
The
img
element supports
dimension
attributes
HTMLImageElement/crossOrigin
Support in all current engines.
Firefox
8+
Safari
6+
Chrome
13+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
11
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
12.1+
The
crossOrigin
IDL attribute must
reflect
the
crossorigin
content attribute,
limited to only known values
HTMLImageElement/referrerPolicy
Support in all current engines.
Firefox
50+
Safari
14+
Chrome
52+
Opera
Edge
79+
Edge (Legacy)
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
The
referrerPolicy
IDL attribute must
reflect
the
referrerpolicy
content
attribute,
limited to only known values
HTMLImageElement/decoding
Support in all current engines.
Firefox
63+
Safari
11.1+
Chrome
65+
Opera
Edge
79+
Edge (Legacy)
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
SVGImageElement/decoding
Firefox
63+
Safari
No
Chrome
65+
Opera
Edge
79+
Edge (Legacy)
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
The
decoding
IDL attribute must
reflect
the
decoding
content attribute,
limited to only known values
HTMLImageElement/loading
Support in all current engines.
Firefox
75+
Safari
15.4+
Chrome
77+
Opera
Edge
79+
Edge (Legacy)
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
The
loading
IDL attribute must
reflect
the
loading
content
attribute,
limited to only known values
The
fetchPriority
IDL attribute
must
reflect
the
fetchpriority
content
attribute,
limited to only known values
image
width
[ =
value
HTMLImageElement/width
Support in all current engines.
Firefox
1+
Safari
3+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
5.5+
Firefox Android
Safari iOS
1+
Chrome Android
WebView Android
Samsung Internet
Opera Android
12.1+
image
height
[ =
value
HTMLImageElement/height
Support in all current engines.
Firefox
1+
Safari
3+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
5.5+
Firefox Android
Safari iOS
1+
Chrome Android
WebView Android
Samsung Internet
Opera Android
12.1+
These attributes return the actual rendered dimensions of the image, or 0 if the dimensions
are not known.
They can be set, to change the corresponding content attributes.
image
naturalWidth
HTMLImageElement/naturalWidth
Support in all current engines.
Firefox
1+
Safari
3+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
9+
Firefox Android
Safari iOS
1+
Chrome Android
WebView Android
Samsung Internet
Opera Android
12.1+
image
naturalHeight
HTMLImageElement/naturalHeight
Support in all current engines.
Firefox
1+
Safari
3+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
9+
Firefox Android
Safari iOS
1+
Chrome Android
WebView Android
Samsung Internet
Opera Android
12.1+
These attributes return the
density-corrected natural width and height
of the
image, or 0 if the image is not
available
image
complete
HTMLImageElement/complete
Support in all current engines.
Firefox
1+
Safari
3+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
5.5+
Firefox Android
Safari iOS
1+
Chrome Android
WebView Android
Samsung Internet
Opera Android
12.1+
Returns true if the image has been completely downloaded or if no image is specified;
otherwise, returns false.
image
currentSrc
HTMLImageElement/currentSrc
Support in all current engines.
Firefox
38+
Safari
9.1+
Chrome
38+
Opera
Edge
79+
Edge (Legacy)
13+
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
Returns the image's
absolute URL
image
decode
()
HTMLImageElement/decode
Support in all current engines.
Firefox
68+
Safari
11.1+
Chrome
64+
Opera
Edge
79+
Edge (Legacy)
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
SVGImageElement/decode
Firefox
68+
Safari
No
Chrome
64+
Opera
Edge
79+
Edge (Legacy)
Internet Explorer
No
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
This method causes the user agent to
decode
the
image
in parallel
, returning a promise that fulfills when decoding is complete.
The promise will be rejected with an
EncodingError
DOMException
if the image cannot be decoded.
image
= new
Image
([
width
[,
height
] ])
HTMLImageElement/Image
Support in all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
8+
Edge
79+
Edge (Legacy)
12+
Internet Explorer
5.5+
Firefox Android
Safari iOS
Chrome Android
WebView Android
Samsung Internet
Opera Android
10.1+
Returns a new
img
element, with the
width
and
height
attributes set to the values passed in the
relevant arguments, if applicable.
The IDL attributes
width
and
height
must return the rendered width and height of the
image, in
CSS pixels
, if the image is
being rendered
; or
else the
density-corrected natural width and height
of the image, in
CSS pixels
, if the image has
density-corrected natural width and
height
and is
available
but is not
being
rendered
; or else 0, if the image is not
available
or does
not have
density-corrected natural width and height
[CSS]
The
naturalWidth
and
naturalHeight
getter
steps are:
If the image is not
available
, then return 0.
Return the respective component of the image's
density-corrected natural width and
height
, in
CSS pixels
[CSS]
Since the
density-corrected natural width and height
of an image
take into account any orientation specified in its metadata,
naturalWidth
and
naturalHeight
reflect the dimensions after applying any
rotation needed to correctly orient the image, regardless of the value of the
'image-orientation'
property.
The
complete
getter steps are:
If any of the following are true:
both the
src
attribute and the
srcset
attribute are omitted;
the
srcset
attribute is omitted and the
src
attribute's value is the empty string;
the
img
element's
current request
's
state
is
completely available
and
its
pending request
is null; or
the
img
element's
current request
's
state
is
broken
and its
pending request
is null,
then return true.
Return false.
The
currentSrc
IDL attribute must return the
img
element's
current request
's
current
URL
The
decode()
method, when invoked, must perform the following steps:
Let
promise
be a new promise.
Queue a microtask
to perform the following steps:
This is done because
updating the image data
takes place in a microtask as well. Thus, to make code such as
img
src
"stars.jpg"
img
decode
();
properly decode
stars.jpg
, we need to delay any processing by one
microtask.
Let
global
be
this
's
relevant global
object
If any of the following are true:
this
's
node document
is not
fully active
or
this
's
current request
's
state
is
broken
then reject
promise
with an
EncodingError
DOMException
Otherwise,
in parallel
, wait for one of the following cases to occur, and
perform the corresponding actions:
This
img
element's
node document
stops being
fully
active
This
img
element's
current request
changes or is mutated
This
img
element's
current request
's
state
becomes
broken
Queue a global task
on the
DOM manipulation task source
with
global
to reject
promise
with an
EncodingError
DOMException
This
img
element's
current request
's
state
becomes
completely
available
Decode
the image.
If decoding does not need to be performed for this image (for example because it is a
vector graphic) or the decoding process completes successfully, then
queue a global
task
on the
DOM manipulation task source
with
global
to
resolve
promise
with undefined.
If decoding fails (for example due to invalid image data), then
queue a global
task
on the
DOM manipulation task source
with
global
to
reject
promise
with an
EncodingError
DOMException
User agents should ensure that the decoded media data stays readily available until at
least the end of the next successful
update the rendering
step in the
event loop
. This is an important part of the API contract, and should not be
broken if at all possible. (Typically, this would only be violated in low-memory situations
that require evicting decoded image data, or when the image is too large to keep in decoded
form for this period of time.)
Animated images will become
completely available
only after all their frames are loaded. Thus, even though an implementation could decode the
first frame before that point, the above steps will not do so, instead waiting until all
frames are available.
Return
promise
Without the
decode()
method, the process of loading an
img
element and then displaying it might look like the following:
const
img
new
Image
();
img
src
"nebula.jpg"
img
onload
()
=>
document
body
appendChild
img
);
};
img
onerror
()
=>
document
body
appendChild
new
Text
"Could not load the nebula :("
));
};
However, this can cause notable dropped frames, as the paint that occurs after inserting the
image into the DOM causes a synchronous decode on the main thread.
This can instead be rewritten using the
decode()
method:
const
img
new
Image
();
img
src
"nebula.jpg"
img
decode
().
then
(()
=>
document
body
appendChild
img
);
}).
catch
(()
=>
document
body
appendChild
new
Text
"Could not load the nebula :("
));
});
This latter form avoids the dropped frames of the original, by allowing the user agent to
decode the image
in parallel
, and only inserting it into the DOM (and thus causing
it to be painted) once the decoding process is complete.
Because the
decode()
method attempts to ensure that the
decoded image data is available for at least one frame, it can be combined with the
requestAnimationFrame()
API.
This means it can be used with coding styles or frameworks that ensure that all DOM modifications
are batched together as
animation frame
callbacks
const
container
document
querySelector
"#container"
);
const
containerWidth
containerHeight
computeDesiredSize
();
requestAnimationFrame
(()
=>
container
style
width
containerWidth
container
style
height
containerHeight
});
// ...
const
img
new
Image
();
img
src
"supernova.jpg"
img
decode
().
then
(()
=>
requestAnimationFrame
(()
=>
container
appendChild
img
));
});
A legacy factory function is provided for creating
HTMLImageElement
objects (in
addition to the factory methods from DOM such as
createElement()
):
Image(
width
height
. When invoked,
the legacy factory function must perform the following steps:
Let
document
be the
current global object
's
associated
Document
Let
img
be the result of
creating an
element
given
document
, "
img
", and the
HTML
namespace
If
width
is given, then
set
an attribute value
for
img
using "
width
and
width
If
height
is given, then
set an attribute value
for
img
using "
height
" and
height
Return
img
A single image can have different appropriate alternative text depending on the context.
In each of the following cases, the same image is used, yet the
alt
text is different each time. The image is the coat of arms of the
Carouge municipality in the canton Geneva in Switzerland.
Here it is used as a supplementary icon:
I lived in
img
src
"carouge.svg"
alt
""
Carouge.
Here it is used as an icon representing the town:
Home town:
img
src
"carouge.svg"
alt
"Carouge"
>Here it is used as part of a text on the town:
Carouge has a coat of arms.
><
img
src
"carouge.svg"
alt
"The coat of arms depicts a lion, sitting in front of a tree."
>It is used as decoration all over the town.
Here it is used as a way to support a similar text where the description is given as well as,
instead of as an alternative to, the image:
Carouge has a coat of arms.
><
img
src
"carouge.svg"
alt
""
>The coat of arms depicts a lion, sitting in front of a tree.
It is used as decoration all over the town.
Here it is used as part of a story:
She picked up the folder and a piece of paper fell out.
><
img
src
"carouge.svg"
alt
"Shaped like a shield, the paper had a
red background, a green tree, and a yellow lion with its tongue
hanging out and whose tail was shaped like an S."
>She stared at the folder. S! The answer she had been looking for all
this time was simply the letter S! How had she not seen that before? It all
came together now. The phone call where Hector had referred to a lion's tail,
the time Maria had stuck her tongue out...
Here it is not known at the time of publication what the image will be, only that it will be a
coat of arms of some kind, and thus no replacement text can be provided, and instead only a brief
caption for the image is provided, in the
title
attribute:
The last user to have uploaded a coat of arms uploaded this one:
><
img
src
"last-uploaded-coat-of-arms.cgi"
title
"User-uploaded coat of arms."
>Ideally, the author would find a way to provide real replacement text even in this case, e.g.
by asking the previous user. Not providing replacement text makes the document more difficult to
use for people who are unable to view images, e.g. blind users, or users or very low-bandwidth
connections or who pay by the byte, or users who are forced to use a text-only web browser.
Here are some more examples showing the same picture used in different contexts, with
different appropriate alternate texts each time.
article
h1
My cats
h1
h2
Fluffy
h2
Fluffy is my favorite.
img
src
"fluffy.jpg"
alt
"She likes playing with a ball of yarn."
She's just too cute.
h2
Miles
h2
My other cat, Miles just eats and sleeps.
article
article
h1
Photography
h1
h2
Shooting moving targets indoors
h2
The trick here is to know how to anticipate; to know at what speed and
what distance the subject will pass by.
img
src
"fluffy.jpg"
alt
"A cat flying by, chasing a ball of yarn, can be
photographed quite nicely using this technique."
h2
Nature by night
h2
To achieve this, you'll need either an extremely sensitive film, or
immense flash lights.
article
article
h1
About me
h1
h2
My pets
h2
I've got a cat named Fluffy and a dog named Miles.
img
src
"fluffy.jpg"
alt
"Fluffy, my cat, tends to keep itself busy."
My dog Miles and I like go on long walks together.
h2
music
h2
After our walks, having emptied my mind, I like listening to Bach.
article
article
h1
Fluffy and the Yarn
h1
Fluffy was a cat who liked to play with yarn. She also liked to jump.
aside
><
img
src
"fluffy.jpg"
alt
""
title
"Fluffy"
>aside
She would play in the morning, she would play in the evening.
article