HTML::O...t::Image(3)

📦 version 0.6.0, in alpine 3.24

🎀 NAME

HTML::Object::DOM::Element::Image — HTML Object DOM Image Class. In the User Contributed Perl Documentation it shows up as HTML::O...t::Image(3) — same class, same energy, bestie. 💖

✨ SYNOPSIS

okay so the bare-minimum vibe check is literally this:

use HTML::Object::DOM::Element::Image;
my $img = HTML::Object::DOM::Element::Image->new ||
    die( HTML::Object::DOM::Element::Image->error, "\n" );

Load the module, call new, and if it fails, die with ->error plus a newline. Slay. 💅

🌈 VERSION

v0.2.0 — that's the version, periodt.

💅 DESCRIPTION

okay so this interface represents an HTML "<img"> element, and it provides the properties and methods used to manipulate image elements. It's literally the image-element glow-up in object form. ✨

🦋 INHERITANCE

the family tree is a whole chain, no cap:

+-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+
| HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Element::Image |
+-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+

that's HTML::Object::Element → HTML::Object::EventTarget → HTML::Object::DOM::Node → HTML::Object::DOM::Element → HTML::Object::DOM::Element::Image, bestie. 💜

🔥 PROPERTIES

Inherits properties from its parent HTML::Object::DOM::Element — yes, all the parent-property inheritance is happening.

alt

alt is a string that reflects the alt HTML attribute. It's the alternate fallback content to be displayed if the image has not been loaded. The way that's literally the "in case of no image" text, y'know? 🫶

Example:

<img src="/some/file/image.png" alt="Great Picture" />

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt

complete

Under perl, complete does nothing and always returns true. Not me being dramatic — that's the behavior. Under JavaScript environment, it returns a boolean value that is true if the browser has finished fetching the image, whether successful or not. That means this value is also true if the image has no src value indicating an image to load. Vibe check: true either way, bestie. 💀

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/complete

crossOrigin

crossOrigin is a string specifying the CORS setting for this image element. See CORS settings attributes for further details. This may be "undef" if CORS is not used. (Yes, the docs put "undef" in quotes — we're keeping it exactly like that.) 💅

Example:

my $image = $doc->createElement( 'img' );
$image->crossOrigin = "anonymous";

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/crossOrigin

currentSrc

Under perl environment, currentSrc returns the same value as src. Under JavaScript environment, it returns a string representing the URL from which the currently displayed image was loaded. This may change as the image is adjusted due to changing conditions, as directed by any media queries which are in place. Media-query girlies, this one's for you. 🌸

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/currentSrc

decoding

decoding is an optional string representing a hint given to the browser on how it should decode the image. If this value is provided, it must be one of the possible permitted values: "sync" to decode the image synchronously, "async" to decode it asynchronously, or "auto" to indicate no preference — and "auto" is the default. Read the decoding page for details on the implications of this property's values. Obsessed with an explicit hint. ✨

Example:

my $img = $doc->createElement( 'img' );
$img->decoding = 'sync';
$img->src = '/some/where/logo.png';

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding

height

height is an integer value that reflects the height HTML attribute, indicating the rendered height of the image in CSS pixels. It's giving dimensions, no cap. 📏

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/height

isMap

isMap is provided with a boolean value, and it sets or gets the HTML attribute "ismap" that indicates the image is part of a server-side image map. This is different from a client-side image map, specified using an "<img"> element and a corresponding "<map"> which contains "<area"> elements indicating the clickable areas in the image. The image must be contained within an "<a"> element; see the ismap page for details. Server-side map realness. 🗺️

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/isMap

loading

loading is provided with a string ("eager" or "lazy") and it sets or gets the "loading" HTML attribute that provides a hint to the browser to optimize loading the document by determining whether to load the image immediately ("eager") or on an as-needed basis ("lazy"). Lazy loading is iconic, tbh. 🦋

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading

naturalHeight

Under perl environment, naturalHeight always returns 0, but you can change this value. Under JavaScript environment, it returns an integer value representing the intrinsic height of the image in CSS pixels, if it is available; else, it shows 0. This is the height the image would be if it were rendered at its natural full size. Intrinsic-height tea. ☕

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalHeight

naturalWidth

Under perl environment, naturalWidth always returns 0, but you can change this value. Under JavaScript environment, it returns an integer value representing the intrinsic width of the image in CSS pixels, if it is available; otherwise, it will show 0. This is the width the image would be if it were rendered at its natural full size. Twin flame to naturalHeight, honestly. 💖

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalWidth

referrerPolicy

referrerPolicy is a string that reflects the referrerpolicy HTML attribute, which tells the user agent how to decide which referrer to use in order to fetch the image.

You can use whatever value you want, but the values supported by web browser are:

  • "no-referrer" — this means that the "Referer" HTTP header will not be sent.
  • "origin" — this means that the referrer will be the origin of the page, that is roughly the scheme, the host and the port.
  • "unsafe-url" — this means that the referrer will include the origin and the path (but not the fragment, password, or username). This case is unsafe as it can leak path information that has been concealed to third-party by using TLS.
🚨 bestie, "unsafe-url" is literally named unsafe for a reason: the docs say it can leak path information that has been concealed to third-party by using TLS. Be careful with that one.

Example:

my $img = $doc->createElement( 'img' );
$img->src = '/some/where/logo.png';
$img->referrerPolicy = 'origin';

my $div = $doc->getElementById('divAround');
$div->appendChild( $img ); # Fetch the image using the origin as the referrer

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/referrerPolicy

sizes

sizes is a string reflecting the "sizes" HTML attribute. This string specifies a list of comma-separated conditional sizes for the image; that is, for a given viewport size, a particular image size is to be used. Read the documentation on the "sizes" page for details on the format of this string. Responsive image sizing? We love to see it. 🎀

Example:

<img src="/files/16870/new-york-skyline-wide->jpg"
     srcset="/files/16870/new-york-skyline-wide->jpg 3724w,
                             /files/16869/new-york-skyline-4by3->jpg 1961w,
                             /files/16871/new-york-skyline-tall->jpg 1060w"
     sizes="((min-width: 50em) and (max-width: 60em)) 50em,
                            ((min-width: 30em) and (max-width: 50em)) 30em,
                            (max-width: 30em) 20em">

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes

src

src is a string that reflects the src HTML attribute, which contains the full URL of the image including base URI. Link it, bestie. 🔗

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/src

srcset

srcset is a string reflecting the srcset HTML attribute. This specifies a list of candidate images, separated by commas (',', U+002C COMMA). Each candidate image is a URL followed by a space, followed by a specially-formatted string indicating the size of the image. The size may be specified either the width or a size multiple. Read the Mozilla srcset documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset> for specifics on the format of the size substring. Candidate images are giving options, periodt. 🌈

Example:

"images/team-photo.jpg 1x, images/team-photo-retina.jpg 2x, images/team-photo-full 2048w"

Another example:

"header640.png 640w, header960.png 960w, header1024.png 1024w, header.png"

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset

useMap

useMap is a string reflecting the usemap HTML attribute, containing the page-local URL of the "<map"> element describing the image map to use. The page-local URL is a pound (hash) symbol (#) followed by the ID of the "<map"> element, such as #my-map-element. The "<map"> in turn contains "<area"> elements indicating the clickable areas in the image. Clickable-area realness. 🗺️

Example:

<map name="mainmenu-map">
    <area shape="circle" coords="25, 25, 75" href="/index.html" alt="Return to home page">
    <area shape="rect" coords="25, 25, 100, 150" href="/index.html" alt="Shop">
</map>

<img src="menubox->png" usemap="#mainmenu-map" />

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/useMap

width

width is an integer value that reflects the width HTML attribute, indicating the rendered width of the image in CSS pixels. Sister property to height, we stan. 💖

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/width

x

x is provided with an integer, and it sets or gets the horizontal offset of the left border edge of the image's CSS layout box relative to the origin of the "<html"> element's containing block.

Since this is a perl environment, this has no effect, but you can still set whatever value you want. Setting it for the plot, honestly. 🙈

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/x

y

y is provided with an integer, and it sets or gets the vertical offset of the top border edge of the image's CSS layout box relative to the origin of the "<html"> element's containing block.

Since this is a perl environment, this has no effect, but you can still set whatever value you want. Vertical-offset twin to x. 💜

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/y

🌟 METHODS

Inherits methods from its parent HTML::Object::DOM::Element — yes, the method inheritance is also a thing.

decode

Since this is a perl environment, there is no decoding of the image, and decode always returns "undef".

Under a JavaScript environment, it returns a Promise that resolves when the image is decoded and it's safe to append the image to the DOM. This prevents rendering of the next frame from having to pause to decode the image, as would happen if an undecoded image were added to the DOM. Promise girlie behavior, but in JavaScript. ✨

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decode

🫶 AUTHOR 🫶

Okay so the icon behind this whole thing is Jacques Deguest — you can hit him up at jack@deguest.jp. Respect the author, bestie. 💖

👀 SEE ALSO 👀

If you wanna keep vibing with the source material — and honestly, same — go check these out:

No cap, reading the docs is self-care. ✨

Okay legal moment, but make it cute:

  • Copyright(c) 2021 DEGUEST Pte. Ltd.
  • All rights reserved
  • This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. periodt. 💀

💖 that’s the whole page, bestie. shoutout to perl v5.42.2, dated 2026-02-15 — iconic behavior fr fr. 🫶

📦 where this page comes from