Section 25.156. HTMLElement: an element in an HTML document

25.156. HTMLElement: an element in an HTML document

DOM Level 2 HTML: Node Element HTMLElement

25.156.1. Properties

Each element of an HTML document has properties that correspond to the HTML attributes of the element. The properties supported by all HTML tags are listed here. Other properties, specific to certain kinds of HTML tags, are listed in the long table in the following Description section. HTMLElement objects inherit a number of useful standard properties from Node and Element, and also implement several nonstandard properties described here:

String className: The value of the class attribute of the element, which specifies zero or more space-separated CSS class names. Note that this property is not named "class" because that name is a reserved word in JavaScript.
CSS2Properties currentStyle: This IE-specific property represents the cascaded set of all CSS properties that apply to the element. It is an IE-only alternative to Window.getComputedStyle( ).
String dir: The value of the dir attribute of the element, which specifies the text direction for the document.
String id: The value of the id attribute. No two elements within the same document should have the same value for id.
String innerHTML: A read/write string that specifies the HTML text that is contained within the element, not including the opening and closing tags of the element itself. Querying this property returns the content of the element as a string of HTML text. Setting this property to a string of HTML text replaces the content of the element with the parsed representation of the HTML. You cannot set this property while the document is loading (for this ability, see HTMLDocument.write( )). This is a nonstandard property that originated in IE 4. It has been implemented by all modern browsers.
String lang: The value of the lang attribute, which specifies the language code for the element's content.
int offsetHeight, offsetWidth: The height and width, in pixels, of the element and all its content, including the element's CSS padding and border, but not its margin. These are nonstandard but well-supported properties.
int offsetLeft, offsetTop: The X and Y coordinates of the upper-left corner of the CSS border of the element relative to the offsetParent container element. These are nonstandard but well-supported properties.
Element offsetParent: Specifies the container element that defines the coordinate system in which offsetLeft and offsetTop are measured. For most elements, offsetParent is the Document object that contains them. However, if an element has a dynamically positioned container, the dynamically positioned element is the offsetParent. In some browsers, table cells are positioned relative to the row in which they are contained, rather than relative to the containing document. See Chapter 16 for an example that uses this property portably. This is a nonstandard but well-supported property.
int scrollHeight, scrollWidth: The overall height and width, in pixels, of an element. When an element has scrollbars (because of the CSS overflow attribute, for example) these properties differ from offsetHeight and offsetWidth, which simply report the size of the visible portion of the element. These are non-standard but well-supported properties.
int scrollLeft, scrollTop: The number of pixels that have scrolled off the left edge of the element or off the top edge of the element. These properties are useful only for elements with scrollbars, such as elements with the CSS overflow attribute set to auto. These properties are also defined on the <body> or <html> tag of the document (this is browser-dependent) and specify the amount of scrolling for the document as a whole. Note that these properties do not specify the amount of scrolling in an <iframe> tag. These are non-standard but well-supported properties.
CSS2Properties style: The value of the style attribute that specifies inline CSS styles for this element. Note that the value of this property is not a string. See CSS2Properties for details.
String title: The value of the title attribute of the element. Many browsers display the value of this attribute in a tool tip when the mouse hovers over the element.

25.156.2. Methods

HTMLElement objects inherit the standard methods of Node and Element. Certain types of elements implement tag-specific methods, which are listed in the long table in the Description section and documented in other reference pages such as Form, Input, and Table. Most modern browsers also implement the following nonstandard method as well:

scrollIntoView( ): Scrolls the document so the element is visible at the top or bottom of the window.

25.156.3. Event Handlers

All HTML elements respond to raw mouse and key events and can trigger the event handlers listed here. Some elements, such as links and buttons, perform default actions when these events occur. For elements like these, further details are available on the element-specific reference page; see Input and Link, for example:

onclick: Invoked when the user clicks on the element.
ondblclick: Invoked when the user double-clicks on the element.
onkeydown: Invoked when the user presses a key.
onkeypress: Invoked when the user presses and releases a key.
onkeyup: Invoked when the user releases a key.
onmousedown: Invoked when the user presses a mouse button.
onmousemove: Invoked when the user moves the mouse.
onmouseout: Invoked when the user moves the mouse off the element.
onmouseover: Invoked when the user moves the mouse over an element.
onmouseup: Invoked when the user releases a mouse button.

25.156.4. Description

Each tag in an HTML document is represented by an HTMLElement object. HTMLElement defines properties that represent the attributes shared by all HTML elements. The following HTML tags do not have any properties other than those listed previously and are fully described by the HTMLElement interface:

`<abbr>`	`<acronym>`	`<address>`	`<b>`
`<bdo>`	`<big>`	`<center>`	`<cite>`
`<code>`	`<dd>`	`<dfn>`	`<dt>`
`<em>`	`<i>`	`<kbd>`	`<noframes>`
`<noscript>`	`<s>`	`<samp>`	`<small>`
`<span>`	`<strike>`	`<strong>`	`<sub>`
`<sup>`	`<tt>`	`<u>`	`<var>`

Most HTML tags define properties other than those explicitly listed previously. The DOM Level 2 HTML specification defines tag-specific interfaces for these tags, so that all standard HTML attributes have a corresponding standard JavaScript property. Typically, a tag named T has a tag-specific interface named HTMLTElement. For example, the <head> tag is represented by the HTMLHeadElement interface. In a few cases, two or more related tags share a single interface, as in the case of the <h1> through <h6> tags, which are all represented by the HTMLHeadingElement interface.

Most of these tag-specific interfaces do nothing more than define a JavaScript property for each attribute of the HTML tag. The JavaScript properties have the same names as the attributes and use lowercase (e.g., id) or, when the attribute name consists of multiple words, mixed case (e.g., longDesc). When an HTML attribute name is a reserved word in Java or JavaScript, the property name is changed slightly. For example, the for attribute of <label> and <script> tags becomes the htmlFor property of the HTMLLabelElement and HTMLScriptElement interfaces because for is a reserved word. The meanings of those properties that correspond directly to HTML attributes are defined by the HTML specification, and documenting each one is beyond the scope of this book.

The following table lists all the HTML tags that have a corresponding subinterface of HTMLElement. For each tag, the table lists the DOM interface name and the names of the properties and methods it defines. All properties are read/write strings unless otherwise specified. For properties that are not read/write strings, the property type is specified in square brackets before the property name. Quite a few tags and attributes are deprecated in HTML 4 and are marked with an * in this table.

Because these interfaces and their properties map so directly to HTML elements and attributes, most interfaces do not have reference pages of their own in this book, and you should consult an HTML reference for details. The exceptions are interfaces that represent tags that are particularly important to client-side JavaScript programmers, such as the <form> and <input> tags. Those tags are documented in this book, under names that do not include the "HTML" prefix or the "Element" suffix. See, for example, the entries for Anchor, Applet, Canvas, Form, Image, Input, Link, Option, Select, Table, and Textarea:

HTML tag	DOM interface, properties, and methods
all tags	HTMLElement: `id`, `title`, `lang`, `dir`, `className`
`<a>`	HTMLAnchorElement: `accessKey`, `charset`, `coords`, `href`, `HReflang`, `name`, `rel`, `rev`, `shape`, `[long] tabIndex`, `target`, `type`, `blur( )`, `focus( )`
`<applet>`	HTMLAppletElement^[]: `align`^[], `alt`^[], `archive`^[], `code`^[], `codeBase`^[], `height`^[], `hspace`^[], `name`^[], `object`^[], `vspace`^[], `width`^[]
`<area>`	HTMLAreaElement: `accessKey`, `alt`, `coords`, `href`, `[boolean] noHref`, `shape`, `[long] tabIndex`, `target`
`<base>`	HTMLBaseElement: `href`, `target`
`<basefont>`	HTMLBaseFontElement^[]: `color`^[], `face`^[], `size`^[]
`<blockquote>`, `<q>`	HTMLQuoteElement: `cite`
`<body>`	HTMLBodyElement: `aLink`^[], `background`^[], `bgColor`^[], `link`^[], `text`^[], `vLink`^[]
	HTMLBRElement: `clear`^[*]
`<button>`	HTMLButtonElement: `[readonly HTMLFormElement] form`, `accessKey`, `[boolean] disabled`, `name`, `[long] tabIndex`, `[readonly] type`, `value`
`<caption>`	HTMLTableCaptionElement: `align`^[*]
`<col>`, `<colgroup>`	HTMLTableColElement: `align`, `ch`, `chOff`, `[long] span`, `vAlign`, `width`
`<del>`, `<ins>`	HTMLModElement: `cite`, `dateTime`
`<dir>`	HTMLDirectoryElement^[]: `[boolean] compact`^[]
`<div>`	HTMLDivElement: `align`^[*]
`<dl>`	HTMLDListElement: `[boolean] compact`^[*]
`<fieldset>`	HTMLFieldSetElement: `[readonly HTMLFormElement] form`
`<font>`	HTMLFontElement^[]: `color`^[], `face`^[], `size`^[]
`<form>`	HTMLFormElement: `[readonly HTMLCollection] elements`, `[readonly long] length`, `name`, `acceptCharset`, `action`, `enctype`, `method`, `target`, `submit( )`, `reset( )`
`<frame>`	HTMLFrameElement: `frameBorder`, `longDesc`, `marginHeight`, `marginWidth`, `name`, `[boolean] noResize`, `scrolling`, `src`, `[readonly Document] contentDocument`
`<frameset>`	HTMLFrameSetElement: `cols`, `rows`
`<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>`	HTMLHeadingElement: `align`^[*]
`<head>`	HTMLHeadElement: `profile`
`<hr>`	HTMLHRElement: `align`^[], `[boolean] noShade`^[], `size`^[], `width`^[]
`<html>`	HTMLHtmlElement: `version`^[*]
`<iframe>`	HTMLIFrameElement: `align`^[*], `frameBorder`, `height`, `longDesc`, `marginHeight`, `marginWidth`, `name`, `scrolling`, `src`, `width`, `[readonly Document] contentDocument`
`<img>`	HTMLImageElement: `align`^[], `alt`, `[long] border`^[], `[long] height`, `[long] hspace`^[], `[boolean] isMap`, `longDesc`, `name`, `src`, `useMap`, `[long] vspace`^[], `[long] width`
`<input>`	HTMLInputElement: `defaultValue`, `[boolean] defaultChecked`, `[readonly HTMLFormElement] form`, `accept`, `accessKey`, `align`^[*], `alt`, `[boolean] checked`, `[boolean] disabled`, `[long] maxLength`, `name`, `[boolean] readOnly`, `size`, `src`, `[long] tabIndex`, `type`, `useMap`, `value`, `blur( )`, `focus( )`, `select( )`, `click( )`
`<ins>`	See `<del>`
`<isindex>`	HTMLIsIndexElement^[]: `[readonly HTMLFormElement] form`, `prompt`^[]
`<label>`	HTMLLabelElement: `[readonly HTMLFormElement] form`, `accessKey`, `htmlFor`
`<legend>`	HTMLLegendElement: `[readonly HTMLFormElement] form`, `accessKey`, `align`^[*]
`<li>`	HTMLLIElement: `type`^[], `[long] value`^[]
`<link>`	HTMLLinkElement: `[boolean] disabled`, `charset`, `HRef`, `HReflang`, `media`, `rel`, `rev`, `target`, `type`
`<map>`	HTMLMapElement: `[readonly HTMLCollection of HTMLAreaElement] areas`, `name`
`<menu>`	HTMLMenuElement^[]: `[boolean] compact`^[]
`<meta>`	HTMLMetaElement: `content`, `httpEquiv`, `name`, `scheme`
`<object>`	HTMLObjectElement: `code`, `align`^[], `archive`, `border`^[], `codeBase`, `codeType`, `data`, `[boolean] declare`, `height`, `hspace`^[], `name`, `standby`, `[long] tabIndex`, `type`, `useMap`, `vspace`^[], `width`, `[readonly Document] contentDocument`
`<ol>`	HTMLOListElement: `[boolean] compact`^[], `[long] start`^[], `type`^[*]
`<optgroup>`	HTMLOptGroupElement: `[boolean] disabled`, `label`
`<option>`	HTMLOptionElement: `[readonly HTMLFormElement] form`, `[boolean] defaultSelected`, `[readonly] text`, `[readonly long] index`, `[boolean] disabled`, `label`, `[boolean] selected`, `value`
`<p>`	HTMLParagraphElement: `align`^[*]
`<param>`	HTMLParamElement: `name`, `type`, `value`, `valueType`
`<pre>`	HTMLPreElement: `[long] width`^[*]
`<q>`	See `<blockquote>`
`<script>`	HTMLScriptElement: `text`, `html For`, `event`, `charset`, `[boolean] defer`, `src`, `type`
`<select>`	HTMLSelectElement: `[readonly] type`, `[long] selectedIndex`, `value`, `[readonlylong] length`, `[readonly HTMLFormElement] form`, `[readonly HTMLCollection of HTMLOptionElement] options`, `[boolean] disabled`, `[boolean] multiple`, `name`, `[long] size`, `[long] tabIndex`, `add( )`, `remove( )`, `blur( )`, `focus( )`
`<style>`	HTMLStyleElement: `[boolean] disabled`, `media`, `type`
`<table>`	HTMLTableElement: `[HTMLTableCaptionElement] caption`, `[HTMLTableSectionElement] tHead`, `[HTMLTableSectionElement] tFoot`, `[readonly HTMLCollection of HTMLTableRowElement] rows`, `[readonly HTMLCollection of HTMLTableSectionElement] tBodies`, `align`^[], `bgColor`^[], `border`, `cellPadding`, `cellSpacing`, `frame`, `rules`, `summary`, `width`, `createTHead( )`, `deleteTHead( )`, `createTFoot( )`, `deleteTFoot( )`, `createCaption( )`, `deleteCaption( )`, `insertRow( )`, `deleteRow( )`
`<tbody>`, `<tfoot>`, `<thead>`	HTMLTableSectionElement: `align`, `ch`, `chOff`, `vAlign`, `[readonly HTMLCollection of HTMLTableRowElement] rows`, `insertRow( )`, `deleteRow( )`
`<td>`, `<th>`	HTMLTableCellElement: `[readonly long] cellIndex`, `abbr`, `align`, `axis`, `bgColor`^[], `ch`, `chOff`, `[long] colSpan`, `headers`, `height`^[], `[boolean] noWrap`^[], `[long] rowSpan`, `scope`, `vAlign`, `width`^[]
`<textarea>`	HTMLTextAreaElement: `defaultValue`, `[readonly HTMLFormElement] form`, `accessKey`, `[long] cols`, `[boolean] disabled`, `name`, `[boolean] readOnly`, `[long] rows`, `[long] tabIndex`, `[readonly] type`, `value`, `blur( )`, `focus( )`, `select( )`
`<tfoot>`	See `<tbody>`
`<th>`	See `<td>`
`<thead>`	See `<tbody>`
`<title>`	HTMLTitleElement: `text`
`<tr>`	HTMLTableRowElement: `[readonly long] rowIndex`, `[readonly long] sectionRowIndex`, `[readonly HTMLCollection of HTMLTableCellElement] cells`, `align`, `bgColor`^[*], `ch`, `chOff`, `vAlign`, `insertCell( )`, `deleteCell( )`
`<ul>`	HTMLUListElement: `[boolean] compact`^[], `type`^[]
^[*]

^[*] Indicates deprecated elements and attributes.

25.156.5. See Also

Anchor, Element, Form, HTMLDocument, Image, Input, Link, Node, Option, Select, Table, TableCell, TableRow, TableSection, Textarea; Chapter 15