Availability

JavaScript 1.1

Inherits from/Overrides

Inherits from HTMLElement

Synopsis

document.images[i] 
document.images.length
document.image-name

Constructor

new Image(width, height)

Arguments

width, height

An optionally specified width and height for the image.

Properties

Image inherits properties from HTMLElement and defines the following properties, most of which correspond to the HTML attributes of the <img> tag. In JavaScript 1.1 and later, the src and lowsrc properties are read/write and may be set to change the displayed image. In browsers that do not allow document reflow, such as IE 3 and Netscape 4, the other properties are read-only.

border

An integer that specifies the width, in pixels, of the border around an image. Its value is set by the border attribute. Images have borders only when they are within hyperlinks.

complete

A read-only boolean value that specifies whether an image is completely loaded or, more accurately, whether the browser has completed its attempt to load the image. If an error occurs during loading, or if the load is aborted, the complete property is still set to true.

height

An integer that specifies the height, in pixels, of the image. Its value is set by the height attribute.

hspace

An integer that specifies the amount of extra horizontal space, in pixels, inserted on the left and right of the image. Its value is set by the hspace attribute.

lowsrc

A read/write string that specifies the URL of an alternate image (usually a smaller one) to display when the user's browser is running on a low-resolution monitor. The initial value is specified by the lowsrc attribute of the <img> tag.

Setting this property has no immediate effect. If the src property is set, however, a new image is loaded, and on low-resolution systems, the current value of the lowsrc property is used instead of the newly updated value of src.

name

A string value, specified by the HTML name attribute, that specifies the name of the image. When an image is given a name with the name attribute, a reference to the image is placed in the image-name property of the document in addition to being placed in the document.images[] array.

src

A read/write string that specifies the URL of the image to be displayed by the browser. The initial value of this property is specified by the src attribute of the <img> tag. When you set this property to the URL of a new image, the browser loads and displays that new image (or, on low-resolution systems, the image specified by the lowsrc property). This is useful for updating the graphical appearance of your web pages in response to user actions and can also be used to perform simple animation.

vspace

An integer that specifies the amount of extra vertical space, in pixels, inserted above and below the image. Its value is set by the vspace attribute.

width

An integer that specifies the width, in pixels, of the image. Its value is set by the width attribute.

Event Handlers

Image inherits event handlers from HTMLElement and defines the following:

onabort

Invoked if the user aborts the download of an image.

onerror

Invoked if an error occurs while downloading the image.

onload

Invoked when the image successfully finishes loading.

HTML Syntax

The Image object is created with a standard HTML <img> tag. Some <img> attributes have been omitted from the following syntax because they are not used by or accessible from JavaScript:

<img src="url"              // The image to display
     width="pixels"         // The width of the image
     height="pixels"        // The height of the image
     [ name="image_name" ]  // A property name for the image
     [ lowsrc="url" ]       // Alternate low-resolution image
     [ border="pixels" ]    // Width of image border
     [ hspace="pixels" ]    // Extra horizontal space around image
     [ vspace="pixels" ]    // Extra vertical space around image
     [ onload="handler" ]   // Invoked when image is fully loaded
     [ onerror="handler" ]  // Invoked if error in loading
     [ onabort="handler" ]  // Invoked if user aborts load
>

Description

The Image objects in the document.images[] array represent the images embedded in an HTML document using the <img> tag. The src property is the most interesting one; when you set this property, the browser loads and displays the image specified by the new value.

You can create Image objects dynamically in your JavaScript code using the Image( ) constructor function. Note that this constructor method does not have an argument to specify the image to be loaded. As with images created from HTML, you tell the browser to load an image by setting the src property of any images you create explicitly. There is no way to display an Image object in the web browser. All you can do is force the Image object to download an image by setting the src property. This is useful, however, because it loads an image into the browser's cache. Later, if that same image URL is specified for one of the images in the images[] array, it is preloaded and displays quickly. You can do this with the following lines:

document.images[2].src = preloaded_image.src;
document.toggle_image.src = toggle_off.src; 

Usage

Setting the src property of an Image object is a way to implement simple animations in your web pages. It is also an excellent technique for changing the graphics on a page as the user interacts with the page. For example, you can create your own Submit button using an image and a hypertext link. The button will start out with a disabled graphic and remain that way until the user correctly enters all the required information into the form, at which point the graphic changes, and the user is able to submit the form.