Class HTMLImageElement
- Namespace
- CSharpToJavaScript.APIs.JS
- Assembly
- CSharpToJavaScript.dll
The HTMLImageElement interface represents an HTML img element, providing the properties and methods used to manipulate image elements.
[Value("HTMLImageElement")]
public class HTMLImageElement : HTMLElement, Region, GeometryUtils, ParentNode, NonDocumentTypeChildNode, ChildNode, Slottable, ARIAMixin, Animatable, ElementCSSInlineStyle, GlobalEventHandlers, ElementContentEditable, HTMLOrSVGElement, HTMLAttributionSrcElementUtils, HTMLSharedStorageWritableElementUtils- Inheritance
-
HTMLImageElement
- Implements
- Inherited Members
Remarks
-The HTML element implementing this interface: img
Constructors
HTMLImageElement()
public HTMLImageElement()Properties
Align
IMPORTANT
Deprecatedalign property of the HTMLImageElement interface is a string which indicates how to position the image relative to its container. It reflects the <img> element's align content attribute.
[Value("align")]
public string Align { get; set; }Property Value
- string
A string whose value is one of
top,middle,bottom,left, orright. For their meanings, see the HTML<img>reference.
Remarks
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.
Alt
The alt property of the HTMLImageElement interface provides fallback (alternate) text to display when the image specified by the {{HTMLElement("img")}} element is not displayed, whether because of an error, because the user has disabled the loading of images, or because the image hasn't finished loading yet. It reflects the <img> element's alt content attribute.
[Value("alt")]
public string Alt { get; set; }Property Value
- string
A string.
Remarks
There are important accessibility implications of providing appropriate alt text, and the requirements may differ based on the purpose of the image. See the HTML <img> reference for more information.
Border
IMPORTANT
Deprecatedborder property of the HTMLImageElement interface 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. It reflects the <img> element's border content attribute.
[Value("border")]
public string Border { get; set; }Property Value
- string
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 ofborderis0.When set to thenullvalue, thatnullvalue is converted to the empty string (""), soelt.border = nullis equivalent toelt.border = "".
Remarks
You should instead use the CSS property border or its longhand properties to not only set the thickness of the border but also to potentially apply a wide variety of other styling options to it.
Complete
The complete read-only property of the HTMLImageElement interface is a Boolean value indicating whether or not the image has completely loaded.
[Value("complete")]
public bool Complete { get; }Property Value
- bool
A Boolean value which is
trueif the image has completely loaded; otherwise, the value isfalse.The image is considered completely loaded if any of the following are true:It's worth noting that due to the image potentially being received asynchronously, the value ofcompletemay change while your script is running.
Remarks
CrossOrigin
The crossOrigin property of the HTMLImageElement interface is a string which specifies the Cross-Origin Resource Sharing ({{Glossary("CORS")}}) setting to use when retrieving the image. It reflects the <img> element's crossorigin content attribute.
[Value("crossOrigin")]
public string? CrossOrigin { get; set; }Property Value
- string
A string whose value is one of
anonymousoruse-credentials. For their meanings, see the HTMLcrossoriginattribute reference.
Remarks
CurrentSrc
The currentSrc read-only property of the HTMLImageElement interface indicates the URL of the image selected by the browser to load.
[Value("currentSrc")]
public string CurrentSrc { get; }Property Value
- string
A string indicating the full URL of the image currently selected by the browser to load. If the image uses the Srcset attribute,
currentSrclets you determine which image from the set of provided images was selected by the browser. The property's value is unrelated to whether the image has successfully loaded or not.
Remarks
-Src
-HTMLImageElement.SrcSet
Decoding
The decoding property of the HTMLImageElement interface provides a hint to the browser as to how it should decode the image. More specifically, whether it should wait for the image to be decoded before presenting other content updates or not. It reflects the <img> element's decoding content attribute.
[Value("decoding")]
public string Decoding { get; set; }Property Value
- string
A string whose value is one of
sync,async, orauto. For their meanings, see the HTML<img>reference.
Remarks
-The Decode() method
-The img element decoding attribute
-What does the image decoding attribute actually do? on tunetheweb.com (2023)
FetchPriority
The fetchPriority property of the HTMLImageElement interface represents a hint to the browser indicating how it should prioritize fetching a particular image relative to other images. It reflects the <img> element's fetchpriority content attribute.
[Value("fetchPriority")]
public string FetchPriority { get; set; }Property Value
- string
A string whose value is one of
high,low, orauto. For their meanings, see the HTMLfetchpriorityattribute.
Remarks
-FetchPriority
-FetchPriority
-HTTP Link header
-Optimize resource loading with the Fetch Priority API for information about how this API affects priorities on Chrome.
Height
The height property of the HTMLImageElement interface indicates the height at which the image is drawn, in {{Glossary("CSS pixel", "CSS pixels")}}, if the image is being drawn or rendered to any visual medium such as a screen or printer. Otherwise, it's the natural, pixel density-corrected height of the image.
[Value("height")]
public ulong Height { get; set; }Property Value
- ulong
An integer value indicating the height of the image. The way the height is defined depends on whether the image is being rendered to a visual medium or not.
Remarks
Hspace
IMPORTANT
Deprecatedhspace property of the HTMLImageElement interface specifies the number of pixels of empty space to leave empty on the left and right sides of the {{HTMLElement("img")}} element when laying out the page. It reflects the <img> element's hspace content attribute.
[Value("hspace")]
public ulong Hspace { get; set; }Property Value
- ulong
An integer value specifying the width, in pixels, of the horizontal margin to apply to the left and right sides of the image.
Remarks
You should instead use the CSS property margin or its longhand properties to establish margin space around an image.
IsMap
The isMap property of the HTMLImageElement interface 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. It reflects the <img> element's ismap content attribute. This attribute is allowed only if the <img> element is a descendant of an a element with a valid href attribute.
[Value("isMap")]
public bool IsMap { get; set; }Property Value
- bool
A Boolean value which is
trueif the image is being used for a server-side image map; otherwise, the value isfalse.
Remarks
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.
Loading
The loading property of the HTMLImageElement interface provides a hint to the {{Glossary("user agent")}} on how to handle the loading of the image which is currently outside the window's {{Glossary("visual viewport")}}. This helps to optimize the loading of the document's contents by postponing loading the image until it's expected to be needed, rather than immediately during the initial page load. It reflects the <img> element's loading content attribute.
[Value("loading")]
public string Loading { get; set; }Property Value
- string
A string whose value is one of
eagerorlazy. For their meanings, see the HTML<img>reference.
Remarks
-The img element
-Web performance in the MDN Learning Area
-Lazy loading in the MDN web performance guide
LongDesc
IMPORTANT
DeprecatedlongDesc property of 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. It reflects the <img> element's longdesc content attribute.
[Value("longDesc")]
public string LongDesc { get; set; }Property Value
- string
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.
Remarks
This attribute is considered obsolete in the HTML spec. It has an uncertain future; authors should use a WAI-ARIA alternative such as aria-describedby or aria-details. You can also encapsulate the image within a link using the a element.
Lowsrc
[Value("lowsrc")]
public string Lowsrc { get; set; }Property Value
Name
IMPORTANT
Deprecatedname property of the HTMLImageElement interface specifies a name for the element. It reflects the <img> element's name content attribute. It has been replaced by the Id property available on all elements, and is kept only for compatibility reasons.
[Value("name")]
public string Name { get; set; }Property Value
- string
A string providing a name by which the image can be referenced.
Remarks
NaturalHeight
The read-only naturalHeight property of the HTMLImageElement interface returns the intrinsic (natural), density-corrected height of the image in {{Glossary("CSS pixel", "CSS pixels")}}.
[Value("naturalHeight")]
public ulong NaturalHeight { get; }Property Value
- ulong
An integer value indicating the intrinsic height of the image, in CSS pixels. This is the height at which the image is naturally drawn when no constraint or specific value is established for the image. This natural height is corrected for the pixel density of the device on which it's being presented, unlike Height.If the intrinsic height is not available—either because the image does not specify an intrinsic height or because the image data is not available in order to obtain this information,
naturalHeightreturns 0.
Remarks
This is the height the image is if drawn with nothing constraining its height; if you neither specify a height for the image nor place the image inside a container that limits or expressly specifies the image height, it will be rendered this tall.
NOTE
Most of the time the natural height is the actual height of the image sent by the server. Nevertheless, browsers can modify an image before pushing it to the renderer. For example, Chrome degrades the resolution of images on low-end devices. In such cases,
naturalHeightwill consider the height of the image modified by such browser interventions as the natural height, and returns this value.
NaturalWidth
The read-only naturalWidth property of the HTMLImageElement interface returns the intrinsic (natural), density-corrected width of the image in {{Glossary("CSS pixel", "CSS pixels")}}.
[Value("naturalWidth")]
public ulong NaturalWidth { get; }Property Value
- ulong
An integer value indicating the intrinsic width of the image, in CSS pixels. This is the width at which the image is naturally drawn when no constraint or specific value is established for the image. This natural width is corrected for the pixel density of the device on which it's being presented, unlike Width.If the intrinsic width is not available—either because the image does not specify an intrinsic width or because the image data is not available in order to obtain this information,
naturalWidthreturns 0.
Remarks
This is the width the image is if drawn with nothing constraining its width; if you neither specify a width for the image nor place the image inside a container that limits or expressly specifies the image width, it will be rendered this wide.
NOTE
Most of the time the natural width is the actual width of the image sent by the server. Nevertheless, browsers can modify an image before pushing it to the renderer. For example, Chrome degrades the resolution of images on low-end devices. In such cases,
naturalWidthwill consider the width of the image modified by such browser interventions as the natural width, and returns this value.
ReferrerPolicy
The referrerPolicy property of the HTMLImageElement interface defining which referrer is sent when fetching the resource. It reflects the <img> element's referrerpolicy content attribute.
[Value("referrerPolicy")]
public string ReferrerPolicy { get; set; }Property Value
- string
A string whose value is one of
no-referrer,no-referrer-when-downgrade,origin,origin-when-cross-origin,same-origin,strict-origin,strict-origin-when-cross-origin, orunsafe-url. For their meanings, see the HTML<img>reference.
Remarks
Sizes
The sizes property of the HTMLImageElement interface allows you to specify the layout width of the image for each of a list of media queries. This provides the ability to automatically select among different images—even images of different orientations or aspect ratios—as the document state changes to match different media conditions. It reflects the <img> element's sizes content attribute.
[Value("sizes")]
public string Sizes { get; set; }Property Value
- string
A string. For more information about the syntax of the
sizesattribute, see the HTML<img>reference.
Remarks
-Media queries
-Using media queries
-HTML images
-Responsive images
-Using the srcset and sizes attributes
-CurrentSrc
-Src
-Srcset
Src
The src property of the HTMLImageElement interface specifies the image to display in the {{HTMLElement("img")}} element. It reflects the <img> element's src content attribute.
[Value("src")]
public string Src { get; set; }Property Value
- string
A string. For more information about the syntax of the
srcattribute, see the HTML<img>reference.
Remarks
Srcset
The srcset property of the HTMLImageElement interface identifies one or more image candidate strings, separated using commas (,), each specifying image resources to use under given circumstances. Each image candidate string contains an image URL and an optional width or pixel density descriptor that indicates the conditions under which that candidate should be used instead of the image specified by the Src property. It reflects the <img> element's srcset content attribute.
[Value("srcset")]
public string Srcset { get; set; }Property Value
- string
A string. For more information about the syntax of the
srcsetattribute, see the HTML<img>reference.
Remarks
The srcset property, along with the Sizes property, are a crucial component in designing responsive websites, as they can be used together to make pages that use appropriate images for the rendering situation.
-HTML images
-Responsive images
-Image file type and format guide
-CurrentSrc
-Sizes
-Src
UseMap
The useMap property of the HTMLImageElement interface providing the name of the client-side image map to apply to the image. It reflects the <img> element's usemap content attribute.
[Value("useMap")]
public string UseMap { get; set; }Property Value
- string
A string containing the hash
#symbol followed by thenameof the map element which defines the image map to apply to the image.
Remarks
Vspace
IMPORTANT
Deprecatedvspace property of the HTMLImageElement interface specifies the number of pixels of empty space to leave empty on the top and bottom sides of the {{HTMLElement("img")}} element when laying out the page. It reflects the <img> element's vspace content attribute.
[Value("vspace")]
public ulong Vspace { get; set; }Property Value
- ulong
An integer value specifying the height, in pixels, of the vertical margin to apply to the top and bottom sides of the image.
Remarks
You should instead use the CSS property margin or its longhand properties to establish margin space around an image.
Width
The width property of the HTMLImageElement interface indicates the width at which the image is drawn, in {{Glossary("CSS pixel", "CSS pixels")}}, if the image is 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("width")]
public ulong Width { get; set; }Property Value
- ulong
An integer value indicating the width of the image. The way the width is defined depends on whether the image is being rendered to a visual medium or not.
Remarks
X
The read-only x property of the HTMLImageElement interface indicates the x-coordinate of the {{HTMLElement("img")}} element's left border edge relative to the root element's origin.
[Value("x")]
public long X { get; }Property Value
- long
An integer value indicating the distance in pixels from the left edge of the element's nearest root element and the left 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
xis relative to that frame.In the diagram below, the left border edge is the left edge of the blue padding area. So the value returned byxwould be the distance from that point to the left edge of the content area.Diagram showing the relationships between the various boxes associated with an element
Remarks
The x and Y properties are only valid for an image if its {{cssxref("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.
Y
The read-only y property of the HTMLImageElement interface indicates the y-coordinate of the {{HTMLElement("img")}} element's top border edge relative to the root element's origin.
[Value("y")]
public long Y { get; }Property Value
- long
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
yis 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 byywould 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
Remarks
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.
Methods
Decode()
The decode() method of the HTMLImageElement interface returns a {{jsxref("Promise")}} that resolves once the image is decoded and is safe to be appended to the DOM.
[Value("decode")]
public Task<GlobalObject.Undefined> Decode()Returns
- Task<GlobalObject.Undefined>
A 'Promise' that fulfills with
undefinedonce the image data is ready to be used.
Remarks
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.
-What does the image decoding attribute actually do? on tunetheweb.com (2023)
-The Decoding property