search
element with form functionality — Last Updated 1 December 2021picture
elementSupport in all current engines.
Support in all current engines.
source
elements, followed by one img
element,
optionally intermixed with script-supporting elements.[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.
source
elementSupport in all current engines.
Support in all current engines.
picture
element, before the img
element.track
elements.type
— Type of embedded resourcesrc
(in video
or audio
) — Address of the resourcesrcset
(in picture
) — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.sizes
(in picture
) — Image sizes for different page layoutsmedia
(in picture
) — Applicable mediawidth
(in picture
) — Horizontal dimensionheight
(in picture
) — Vertical dimension[Exposed =Window ]
interface HTMLSourceElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute USVString srcset ;
[CEReactions ] attribute DOMString sizes ;
[CEReactions ] attribute DOMString media ;
[CEReactions ] attribute unsigned long width ;
[CEReactions ] 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 remainder of the requirements depend on whether the parent is a picture
element or a media element:
source
element's parent is a picture
elementThe 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 must
also be present, and is a sizes attribute. The sizes
attribute contributes the source size to
the source set, if the source
element is selected.
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 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:
A 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
".
A type
attribute specified.
The src
attribute must not be present.
source
element's parent is a media elementThe 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.
Dynamically modifying a source
element and its 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 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]
The following list shows some examples of how to use the codecs=
MIME
parameter in the type
attribute.
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.58A01E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.4D401E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.64001E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.8, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.240, mp4a.40.2"' >
< source src = 'video.3gp' type = 'video/3gpp; codecs="mp4v.20.8, samr"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, speex"' >
< source src = 'audio.ogg' type = 'audio/ogg; codecs=vorbis' >
< source src = 'audio.spx' type = 'audio/ogg; codecs=speex' >
< source src = 'audio.oga' type = 'audio/ogg; codecs=flac' >
< source src = 'video.ogv' type = 'video/ogg; codecs="dirac, vorbis"' >
The srcset
, sizes
, and media
attributes must not be present.
If a source
element is inserted as a
child of a media element that has no src
attribute and whose networkState
has the value NETWORK_EMPTY
, the user agent must invoke the media
element's resource selection
algorithm.
The IDL attributes src
, type
, srcset
, sizes
and media
must reflect the respective
content attributes of the same name.
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 <video> with its contents
while ( video. hasChildNodes()) {
if ( video. firstChild instanceof HTMLSourceElement)
video. removeChild( video. firstChild);
else
video. parentNode. insertBefore( video. firstChild, video);
}
video. parentNode. removeChild( video);
}
</ script >
< video controls autoplay >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"'
onerror = "fallback(parentNode)" >
...
</ video >
img
elementSupport in all current engines.
Support in all current engines.
usemap
attribute: Interactive content.alt
— Replacement text for use when images are not availablesrc
— Address of the resourcesrcset
— Images to use in different situations, e.g., high-resolution displays, small monitors, etc.sizes
— Image sizes for different page layoutscrossorigin
— How the element handles crossorigin requestsusemap
— Name of image map to useismap
— Whether the image is a server-side image mapwidth
— Horizontal dimensionheight
— Vertical dimensionreferrerpolicy
— Referrer policy for fetches initiated by the elementdecoding
— Decoding hint to use when processing this image for presentationloading
— Used when determining loading deferralalt
attribute: for authors; for implementers.[Exposed =Window ,
LegacyFactoryFunction =Image (optional unsigned long width , optional unsigned long height )]
interface HTMLImageElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString alt ;
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute USVString srcset ;
[CEReactions ] attribute DOMString sizes ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions ] attribute DOMString useMap ;
[CEReactions ] attribute boolean isMap ;
[CEReactions ] attribute unsigned long width ;
[CEReactions ] 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 ;
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.
Support in all current engines.
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.
The src
attribute must be present, and 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 may also be present, and 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, and is a sizes attribute. The sizes
attribute contributes the source size to the source set (if no
source
element was selected).
Support in all current engines.
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.
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 > <!-- Everything after this div is below the viewport -->
< 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 an intrinsic 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
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.
src
attribute is set and the alt
attribute is set to the empty stringThe 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.
src
attribute is set and the alt
attribute is set to a value that isn't emptyThe 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.
src
attribute is set and the alt
attribute is notThe 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.)
src
attribute is not set and either the alt
attribute is set to the empty string or the alt
attribute is not set at allThe element represents nothing.
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 a
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 a
element.
The ismap
attribute is a
boolean attribute. The attribute must not be specified
on an element that does not have an ancestor a
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 img
element supports dimension
attributes.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The alt
, src
, srcset
and sizes
IDL attributes must
reflect the respective content attributes of the same name.
Support in all current engines.
The crossOrigin
IDL attribute must
reflect the crossorigin
content attribute,
limited to only known values.
Support in all current engines.
The useMap
IDL
attribute must reflect the usemap
content
attribute.
Support in all current engines.
The isMap
IDL
attribute must reflect the ismap
content
attribute.
HTMLImageElement/referrerPolicy
Support in all current engines.
The referrerPolicy
IDL attribute must
reflect the referrerpolicy
content
attribute, limited to only known values.
Support in all current engines.
The decoding
IDL attribute must reflect the decoding
content attribute, limited to only known values.
The loading
IDL attribute must reflect the loading
content
attribute, limited to only known values.
image.width [ = value ]
Support in all current engines.
image.height [ = value ]
Support in all current engines.
These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.
They can be set, to change the corresponding content attributes.
image.naturalWidth
Support in all current engines.
image.naturalHeight
HTMLImageElement/naturalHeight
Support in all current engines.
These attributes return the intrinsic dimensions of the image, or zero if the dimensions are not known.
image.complete
Support in all current engines.
Returns true if the image has been completely downloaded or if no image is specified; otherwise, returns false.
image.currentSrc
Support in all current engines.
Returns the image's absolute URL.
image.decode()
Support in all current engines.
Support in one engine only.
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 ] ])
Support in all current engines.
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, and
is being rendered to a visual medium; or else the density-corrected intrinsic width and
height of the image, in CSS pixels, if the image has
intrinsic dimensions and is available but not being
rendered to a visual medium; or else 0, if the image is not available or does not have intrinsic dimensions. [CSS]
On setting, they must act as if they reflected the respective content attributes of the same name.
The IDL attributes naturalWidth
and naturalHeight
must return
the density-corrected intrinsic width and height of the image, in CSS pixels, if the image has intrinsic dimensions and is available, or else 0. [CSS]
Since the intrinsic dimensions 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 IDL attribute complete
must return true if any of the following
conditions is true:
src
attribute and the srcset
attribute are omitted.
srcset
attribute is omitted and the src
attribute's value is the empty string.
img
element's current request's state is completely available and its
pending request is null.
img
element's current request's state is broken and its
pending request is null.
Otherwise, the attribute must 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.
If any of the following conditions are true about this img
element:
its node document is not an active document;
its 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:
img
element's node document stops being an active
documentimg
element's current request changes or is mutatedimg
element's current request's state becomes brokenReject promise with an "EncodingError
"
DOMException
.
img
element's current request's state becomes completely
availableDecode the image.
If decoding does not need to be performed for this image (for example because it is a vector graphic), resolve promise with undefined.
If decoding fails (for example due to invalid image data), reject promise with
an "EncodingError
" DOMException
.
If the decoding process completes successfully, resolve promise with undefined.
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:
< p > I lived in < img src = "carouge.svg" alt = "" > Carouge.</ p >
Here it is used as an icon representing the town:
< p > Home town: < img src = "carouge.svg" alt = "Carouge" ></ p >
Here it is used as part of a text on the town:
< p > Carouge has a coat of arms.</ p >
< p >< img src = "carouge.svg" alt = "The coat of arms depicts a lion, sitting in front of a tree." ></ p >
< p > It is used as decoration all over the town.</ p >
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:
< p > Carouge has a coat of arms.</ p >
< p >< img src = "carouge.svg" alt = "" ></ p >
< p > The coat of arms depicts a lion, sitting in front of a tree.
It is used as decoration all over the town.</ p >
Here it is used as part of a story:
< p > She picked up the folder and a piece of paper fell out.</ p >
< p >< 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." ></ p >
< p > 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...</ p >
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:
< p > The last user to have uploaded a coat of arms uploaded this one:</ p >
< p >< img src = "last-uploaded-coat-of-arms.cgi" title = "User-uploaded coat of arms." ></ p >
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 >
< p > Fluffy is my favorite.</ p >
< img src = "fluffy.jpg" alt = "She likes playing with a ball of yarn." >
< p > She's just too cute.</ p >
< h2 > Miles</ h2 >
< p > My other cat, Miles just eats and sleeps.</ p >
</ article >
< article >
< h1 > Photography</ h1 >
< h2 > Shooting moving targets indoors</ h2 >
< p > The trick here is to know how to anticipate; to know at what speed and
what distance the subject will pass by.</ p >
< 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 >
< p > To achieve this, you'll need either an extremely sensitive film, or
immense flash lights.</ p >
</ article >
< article >
< h1 > About me</ h1 >
< h2 > My pets</ h2 >
< p > I've got a cat named Fluffy and a dog named Miles.</ p >
< img src = "fluffy.jpg" alt = "Fluffy, my cat, tends to keep itself busy." >
< p > My dog Miles and I like go on long walks together.</ p >
< h2 > music</ h2 >
< p > After our walks, having emptied my mind, I like listening to Bach.</ p >
</ article >
< article >
< h1 > Fluffy and the Yarn</ h1 >
< p > Fluffy was a cat who liked to play with yarn. She also liked to jump.</ p >
< aside >< img src = "fluffy.jpg" alt = "" title = "Fluffy" ></ aside >
< p > She would play in the morning, she would play in the evening.</ p >
</ article >