This specification defines the Document Object Model Level 2 HTML, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content and structure of [HTML 4.01] and [XHTML 1.0] documents. The Document Object Model Level 2 HTML builds on the Document Object Model Level 2 Core [DOM Level 2 Core] and is not backward compatible with DOM Level 1 HTML [DOM Level 1].

1. Document Object Model HTML

Editors:: Johnny Stenback, Netscape; Philippe Le Hégaret, W3C; Arnaud Le Hors, W3C and IBM (until November 2000)

1.1. Introduction
1.2. HTML Application of Core DOM
- 1.2.1. Naming Conventions
1.3. XHTML and the HTML DOM
1.4. Miscellaneous Object Definitions
- HTMLCollection, HTMLOptionsCollection
1.5. Objects related to HTML documents
- HTMLDocument
1.6. HTML Elements

1.1. Introduction

This section extends the DOM Level 2 Core API [DOM Level 2 Core] to describe objects and methods specific to HTML documents [HTML 4.01], and XHTML documents [XHTML 1.0]. In general, the functionality needed to manipulate hierarchical document structures, elements, and attributes will be found in the core section; functionality that depends on the specific elements defined in HTML will be found in this section.

The goals of the HTML-specific DOM API are:

to specialize and add functionality that relates specifically to HTML documents and elements.
to address issues of backwards compatibility with the DOM Level 0.
to provide convenience mechanisms, where appropriate, for common and frequent operations on HTML documents.

The key differences between the core DOM and the HTML application of DOM is that the HTML Document Object Model exposes a number of convenience methods and properties that are consistent with the existing models and are more appropriate to script writers. In many cases, these enhancements are not applicable to a general DOM because they rely on the presence of a predefined DTD. The transitional or frameset DTD for HTML 4.01, or the XHTML 1.0 DTDs are assumed. Interoperability between implementations is only guaranteed for elements and attributes that are specified in the HTML 4.01 and XHTML 1.0 DTDs.

More specifically, this document includes the following specializations for HTML:

An HTMLDocument interface, derived from the core Document interface. HTMLDocument specifies the operations and queries that can be made on a HTML document.
An HTMLElement interface, derived from the core Element interface. HTMLElement specifies the operations and queries that can be made on any HTML element. Methods on HTMLElement include those that allow for the retrieval and modification of attributes that apply to all HTML elements.
Specializations for all HTML elements that have attributes that extend beyond those specified in the HTMLElement interface. For all such attributes, the derived interface for the element contains explicit methods for setting and getting the values.

The DOM Level 2 includes mechanisms to access and modify style specified through CSS and defines an event model that can be used with HTML documents.

The interfaces found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTML" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In addition to the feature string "HTML", the feature string "XHTML" (version string "2.0") can be used to check if the implementation supports XHTML (this is equivalent to checking the features "XML" and "HTML"). In order to fully support this module, an implementation must also support the "Core" feature defined [DOM Level 2 Core]. Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether they are supported or not. The feature string for all the interfaces listed in this section is "HTML" and the version is "2.0". In order to fully support this feature, an implementation needs also to support the "Core" feature defined in the Document Object Model Level 2 Core [DOM Level 2 Core] (see also Conformance).

The interfaces in this specification are designed for [HTML 4.01] documents, as well as for [XHTML 1.0] documents.

Note: This specification does not intend to define exactly how a user agent will respond to a change to any attribute on an element that directly or indirectly references external data, such elements are HTMLAppletElement, HTMLFrameElement, HTMLFrameSetElement, HTMLIFrameElement, HTMLImageElement, HTMLLinkElement, HTMLObjectElement, HTMLParamElement, and HTMLScriptElement.

1.2. HTML Application of Core DOM

1.2.1. Naming Conventions

The HTML DOM follows a naming convention for properties, methods, events, collections, and data types. All names are defined as one or more English words concatenated together to form a single string.

1.2.1.1. Properties and Methods

The property or method name starts with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a property that returns document meta information such as the date the file was created might be named "fileDateCreated". In the ECMAScript binding, properties are exposed as properties of a given object. In Java, properties are exposed with get and set methods.

1.2.1.2. Non-HTML 4.0 interfaces and attributes

While most of the interfaces defined below can be mapped directly to elements defined in the HTML 4.01 Recommendation, some of them cannot. Similarly, not all attributes listed below have counterparts in the HTML 4.01 specification (and some do, but have been renamed to avoid conflicts with scripting languages). Interfaces and attribute definitions that have links to the HTML 4.0 specification have corresponding element and attribute definitions there; all others are added by this specification, either for convenience or backwards compatibility with DOM Level 0 implementations.

1.3. XHTML and the HTML DOM

The DOM HTML Level 1 API [DOM Level 1] were originally intended to be used only for HTML 4.01 documents [HTML 4.01]. The APIs were defined well before XHTML 1.0 [XHTML 1.0] became a specification, or before it was worked on by the HTML Working Group.

From the DOM point of view, The biggest difference between HTML 4.01 (and earlier) and XHTML 1.0 is that XHTML is case sensitive, whereas HTML 4.01 is case insensitive. The HTML case insensitivity is also reflected in the DOM HTML API. For instance, element and attribute names are exposed as all uppercase (for consistency) when used on an HTML document, regardless of the character case used in the markup. Since XHTML is based on XML, in XHTML everything is case sensitive, and element and attribute names must be lowercase in the markup.

Developers need to take two things into account when writing code that works on both HTML and XHTML documents. When comparing element or attribute names to strings, the string compare needs to be case insensitive, or the element or attribute name needs to be converted into lowercase before comparing against a lowercase string. Second, when calling methods that are case insensitive when used on a HTML document (such as getElementsByTagName() and namedItem()), the string that is passed in should be lowercase.

Note: The interfaces provided in this document are only for [HTML 4.01] and [XHTML 1.0] documents and are not guaranteed to work with any future version of XHTML.

1.4. Miscellaneous Object Definitions

Interface HTMLCollection

An HTMLCollection is a list of nodes. An individual node may be accessed by either ordinal index or the node's name or id attributes.

Note: Collections in the HTML DOM are assumed to be live meaning that they are automatically updated when the underlying document is changed.

IDL Definition

interface HTMLCollection {
  readonly attribute unsigned long   length;
  Node               item(in unsigned long index);
  Node               namedItem(in DOMString name);
};

Attributes

length of type unsigned long, readonly: This attribute specifies the length or size of the list.

Methods

item

This method retrieves a node specified by ordinal index. Nodes are numbered in tree order (depth-first traversal order).

Parameters

index of type unsigned long: The index of the node to be fetched. The index origin is 0.

Return Value

Node

The Node at the corresponding position upon success. A value of null is returned if the index is out of range.

No Exceptions

namedItem

This method retrieves a Node using a name. With [HTML 4.01] documents, it first searches for a Node with a matching id attribute. If it doesn't find one, it then searches for a Node with a matching name attribute, but only on those elements that are allowed a name attribute. With [XHTML 1.0] documents, this method only searches for Nodes with a matching id attribute. This method is case insensitive in HTML documents and case sensitive in XHTML documents.

Parameters

name of type DOMString: The name of the Node to be fetched.

Return Value

Node

The Node with a name or id attribute whose value corresponds to the specified string. Upon failure (e.g., no node with this name exists), returns null.

No Exceptions

Interface HTMLOptionsCollection (introduced in DOM Level 2)

An HTMLOptionsCollection is a list of nodes representing HTML option element. An individual node may be accessed by either ordinal index or the node's name or id attributes.

Note: Collections in the HTML DOM are assumed to be live meaning that they are automatically updated when the underlying document is changed.

IDL Definition

// Introduced in DOM Level 2:
interface HTMLOptionsCollection {
           attribute unsigned long   length;
                                        // raises(DOMException) on setting

  Node               item(in unsigned long index);
  Node               namedItem(in DOMString name);
};

Attributes

length of type unsigned long

This attribute specifies the length or size of the list.

Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: if setting the length is not allowed by the implementation.

Methods

item

This method retrieves a node specified by ordinal index. Nodes are numbered in tree order (depth-first traversal order).

Parameters

index of type unsigned long: The index of the node to be fetched. The index origin is 0.

Return Value

Node

The Node at the corresponding position upon success. A value of null is returned if the index is out of range.

No Exceptions

namedItem

This method retrieves a Node using a name. It first searches for a Node with a matching id attribute. If it doesn't find one, it then searches for a Node with a matching name attribute, but only on those elements that are allowed a name attribute. This method is case insensitive in HTML documents and case sensitive in XHTML documents.

Parameters

name of type DOMString: The name of the Node to be fetched.

Return Value

Node

The Node with a name or id attribute whose value corresponds to the specified string. Upon failure (e.g., no node with this name exists), returns null.

No Exceptions

1.5. Objects related to HTML documents

Interface HTMLDocument

An HTMLDocument is the root of the HTML hierarchy and holds the entire content. Besides providing access to the hierarchy, it also provides some convenience methods for accessing certain sets of information from the document.

The following properties have been deprecated in favor of the corresponding ones for the BODY element:

alinkColor
background
bgColor
fgColor
linkColor
vlinkColor

Note: In DOM Level 2, the method getElementById is inherited from the Document interface where it was moved to.

IDL Definition

interface HTMLDocument : Document {
           attribute DOMString       title;
  readonly attribute DOMString       referrer;
  readonly attribute DOMString       domain;
  readonly attribute DOMString       URL;
           attribute HTMLElement     body;
  readonly attribute HTMLCollection  images;
  readonly attribute HTMLCollection  applets;
  readonly attribute HTMLCollection  links;
  readonly attribute HTMLCollection  forms;
  readonly attribute HTMLCollection  anchors;
           attribute DOMString       cookie;
                                        // raises(DOMException) on setting

  void               open();
  void               close();
  void               write(in DOMString text);
  void               writeln(in DOMString text);
  NodeList           getElementsByName(in DOMString elementName);
};

Attributes

URL of type DOMString, readonly

The absolute URI [IETF RFC 2396] of the document.

anchors of type HTMLCollection, readonly

A collection of all the anchor (A) elements in a document with a value for the name attribute.

Note: For reasons of backward compatibility, the returned set of anchors only contains those anchors created with the name attribute, not those created with the id attribute. Note that in [XHTML 1.0], the name attribute (see section 4.10) has no semantics and is only present for legacy user agents: the id attribute is used instead. Users should prefer the iterator mechanisms provided by [DOM Level 2 Traversal] instead.

applets of type HTMLCollection, readonly

A collection of all the OBJECT elements that include applets and APPLET (deprecated) elements in a document.

body of type HTMLElement

The element that contains the content for the document. In documents with BODY contents, returns the BODY element. In frameset documents, this returns the outermost FRAMESET element.

cookie of type DOMString

This mutable string attribute denotes persistent state information that (1) is associated with the current frame or document and (2) is composed of information described by the cookies non-terminal of [IETF RFC 2965], Section 4.2.2.
If no persistent state information is available for the current frame or document document, then this property's value is an empty string.
When this attribute is read, all cookies are returned as a single string, with each cookie's name-value pair concatenated into a list of name-value pairs, each list item being separated by a ';' (semicolon).
When this attribute is set, the value it is set to should be a string that adheres to the cookie non-terminal of [IETF RFC 2965]; that is, it should be a single name-value pair followed by zero or more cookie attribute values. If no domain attribute is specified, then the domain attribute for the new value defaults to the host portion of an absolute URI [IETF RFC 2396] of the current frame or document. If no path attribute is specified, then the path attribute for the new value defaults to the absolute path portion of the URI [IETF RFC 2396] of the current frame or document. If no max-age attribute is specified, then the max-age attribute for the new value defaults to a user agent defined value. If a cookie with the specified name is already associated with the current frame or document, then the new value as well as the new attributes replace the old value and attributes. If a max-age attribute of 0 is specified for the new value, then any existing cookies of the specified name are removed from the cookie storage.

Note: See [IETF RFC 2965] for the semantics of persistent state item attribute value pairs.

Note: The precise nature of a user agent session is not defined by this specification.

Exceptions on setting

DOMException

SYNTAX_ERR: If the new value does not adhere to the cookie syntax specified by [IETF RFC 2965].

domain of type DOMString, readonly

The domain name of the server that served the document, or null if the server cannot be identified by a domain name.

forms of type HTMLCollection, readonly

A collection of all the forms of a document.

images of type HTMLCollection, readonly

A collection of all the IMG elements in a document. The behavior is limited to IMG elements for backwards compatibility.

Note: As suggested by [HTML 4.01], to include images, authors may use the OBJECT element or the IMG element. Therefore, it is recommended not to use this attribute to find the images in the document but getElementsByTagName with HTML 4.01 or getElementsByTagNameNS with XHTML 1.0.

links of type HTMLCollection, readonly

A collection of all AREA elements and anchor (A) elements in a document with a value for the href attribute.

referrer of type DOMString, readonly

Returns the URI [IETF RFC 2396] of the page that linked to this page. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, via a bookmark).

title of type DOMString

The title of a document as specified by the TITLE element in the head of the document.

Methods

close

Closes a document stream opened by open() and forces rendering.

No Parameters

No Return Value

No Exceptions

getElementsByName

With [HTML 4.01] documents, this method returns the (possibly empty) collection of elements whose name value is given by elementName. In [XHTML 1.0] documents, this methods only return the (possibly empty) collection of form controls with matching name. This method is case sensitive.

Parameters

elementName of type DOMString: The name attribute value for an element.

Return Value

NodeList

The matching elements.

No Exceptions

open

Open a document stream for writing. If a document exists in the target, this method clears it.

Note: This method and the ones following allow a user to add to or replace the structure model of a document using strings of unparsed HTML. At the time of writing alternate methods for providing similar functionality for both HTML and XML documents were being considered (see [DOM Level 3 Load and Save]).

No Parameters

No Return Value

No Exceptions

write

Write a string of text to a document stream opened by open(). Note that the function will produce a document which is not necessarily driven by a DTD and therefore might be produce an invalid result in the context of the document.

Parameters

text of type DOMString: The string to be parsed into some structure in the document structure model.

No Return Value

No Exceptions

writeln

Write a string of text followed by a newline character to a document stream opened by open(). Note that the function will produce a document which is not necessarily driven by a DTD and therefore might be produce an invalid result in the context of the document

Parameters

text of type DOMString: The string to be parsed into some structure in the document structure model.

No Return Value

No Exceptions

1.6. HTML Elements

1.6.1. Property Attributes

HTML attributes are exposed as properties on the element object. The DOM naming conventions always determine the name of the exposed property, and are independent of the case of the attribute in the source document. The data type of the property is in general determined by the type of the attribute as determined by the HTML 4.01 (transitional and frameset) and XHTML 1.0 DTDs. The attributes have the semantics (including case-sensitivity) given in the [HTML 4.01] and [XHTML 1.0] specifications.

The attributes are exposed as properties for compatibility with DOM Level 0. This usage is deprecated because it can not be generalized to all possible attribute names for XML. We recommend the use of generic methods on the core Element interface for setting, getting and removing attributes.

DTD Data Type	Object Model Data Type
CDATA	DOMString
Value list (e.g., (left \| right \| center))	DOMString
one-value Value list (e.g., (disabled))	boolean
Number	long int

In an HTML document the return value of an attribute that has a data type that is a value list is normalized to lowercase (independent of the case of the value in the source document).

For example, if the value of the align attribute on a P element is "Left" (which is not a valid value in XHTML due to the case sensitivity of XHTML) then the value is returned as "left". For attributes with the CDATA data type, the case of the return value is that given in the source document.

The return value of an attribute that is unspecified and does not have a default value is the empty string if the return type is a DOMString, false if the return type is a boolean and 0 if the return type is a number.

1.6.2. Naming Exceptions

To avoid namespace conflicts, two attributes with the same name as a keyword in one of our chosen binding languages were prefixed. The for attribute of the LABEL and SCRIPT elements collides with loop construct naming conventions and is renamed htmlFor. The class attribute of the HTML elements collides with class definitions naming conventions and is renamed className.

1.6.3. Exposing Element Type Names (`tagName`, (`nodeName`))

If the document is an HTML 4.01 document the element type names exposed through a property are in uppercase. For example, the body element type name is exposed through the tagName property as BODY. If the document is an XHTML 1.0 document the element name is exposed as it is written in the XHTML file. This means that the element type names are exposed in lowercase for XHTML documents since the XHTML 1.0 DTDs defines element type names as lowercase, and XHTML, being derived from XML, is case sensitive.

1.6.4. The HTMLElement interface

Interface HTMLElement

All HTML element interfaces derive from this class. Elements that only expose the HTML core attributes are represented by the base HTMLElement interface. These elements are as follows:

special: SUB, SUP, SPAN, BDO
font: TT, I, B, U, S, STRIKE, BIG, SMALL
phrase: EM, STRONG, DFN, CODE, SAMP, KBD, VAR, CITE, ACRONYM, ABBR
list: DD, DT
NOFRAMES, NOSCRIPT
ADDRESS, CENTER

Note: The style attribute of an HTML element is accessible through the ElementCSSInlineStyle interface which is defined in the CSS module [DOM Level 2 Style Sheets and CSS].

IDL Definition

interface HTMLElement : Element {
           attribute DOMString       id;
           attribute DOMString       title;
           attribute DOMString       lang;
           attribute DOMString       dir;
           attribute DOMString       className;
};

Attributes

className of type DOMString: The class attribute of the element. This attribute has been renamed due to conflicts with the "class" keyword exposed by many languages. See the class attribute definition in HTML 4.01.
dir of type DOMString: Specifies the base direction of directionally neutral text and the directionality of tables. See the dir attribute definition in HTML 4.01.
id of type DOMString: The element's identifier. See the id attribute definition in HTML 4.01.
lang of type DOMString: Language code defined in RFC 1766. See the lang attribute definition in HTML 4.01.
title of type DOMString: The element's advisory title. See the title attribute definition in HTML 4.01.

1.6.5. Object definitions

Interface HTMLHtmlElement

Root of an HTML document. See the HTML element definition in HTML 4.01.

IDL Definition

interface HTMLHtmlElement : HTMLElement {
           attribute DOMString       version;
};

Attributes

version of type DOMString: Version information about the document's DTD. See the version attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.

Interface HTMLHeadElement

Document head information. See the HEAD element definition in HTML 4.01.

IDL Definition

interface HTMLHeadElement : HTMLElement {
           attribute DOMString       profile;
};

Attributes

profile of type DOMString: URI [IETF RFC 2396] designating a metadata profile. See the profile attribute definition in HTML 4.01.

Interface HTMLLinkElement

The LINK element specifies a link to an external resource, and defines this document's relationship to that resource (or vice versa). See the LINK element definition in HTML 4.01 (see also the LinkStyle interface in the StyleSheet module [DOM Level 2 Style Sheets and CSS]).

IDL Definition

interface HTMLLinkElement : HTMLElement {
           attribute boolean         disabled;
           attribute DOMString       charset;
           attribute DOMString       href;
           attribute DOMString       hreflang;
           attribute DOMString       media;
           attribute DOMString       rel;
           attribute DOMString       rev;
           attribute DOMString       target;
           attribute DOMString       type;
};

Attributes

charset of type DOMString: The character encoding of the resource being linked to. See the charset attribute definition in HTML 4.01.
disabled of type boolean: Enables/disables the link. This is currently only used for style sheet links, and may be used to activate or deactivate style sheets.
href of type DOMString: The URI [IETF RFC 2396] of the linked resource. See the href attribute definition in HTML 4.01.
hreflang of type DOMString: Language code of the linked resource. See the hreflang attribute definition in HTML 4.01.
media of type DOMString: Designed for use with one or more target media. See the media attribute definition in HTML 4.01.
rel of type DOMString: Forward link type. See the rel attribute definition in HTML 4.01.
rev of type DOMString: Reverse link type. See the rev attribute definition in HTML 4.01.
target of type DOMString: Frame to render the resource in. See the target attribute definition in HTML 4.01.
type of type DOMString: Advisory content type. See the type attribute definition in HTML 4.01.

Interface HTMLTitleElement

The document title. See the TITLE element definition in HTML 4.01.

IDL Definition

interface HTMLTitleElement : HTMLElement {
           attribute DOMString       text;
};

Attributes

text of type DOMString: The specified title as a string.

Interface HTMLMetaElement

This contains generic meta-information about the document. See the META element definition in HTML 4.01.

IDL Definition

interface HTMLMetaElement : HTMLElement {
           attribute DOMString       content;
           attribute DOMString       httpEquiv;
           attribute DOMString       name;
           attribute DOMString       scheme;
};

Attributes

content of type DOMString: Associated information. See the content attribute definition in HTML 4.01.
httpEquiv of type DOMString: HTTP response header name [IETF RFC 2616]. See the http-equiv attribute definition in HTML 4.01.
name of type DOMString: Meta information name. See the name attribute definition in HTML 4.01.
scheme of type DOMString: Select form of content. See the scheme attribute definition in HTML 4.01.

Interface HTMLBaseElement

Document base URI [IETF RFC 2396]. See the BASE element definition in HTML 4.01.

IDL Definition

interface HTMLBaseElement : HTMLElement {
           attribute DOMString       href;
           attribute DOMString       target;
};

Attributes

href of type DOMString: The base URI [IETF RFC 2396]. See the href attribute definition in HTML 4.01.
target of type DOMString: The default target frame. See the target attribute definition in HTML 4.01.

Interface HTMLIsIndexElement

This element is used for single-line text input. See the ISINDEX element definition in HTML 4.01. This element is deprecated in HTML 4.01.

IDL Definition

interface HTMLIsIndexElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString       prompt;
};

Attributes

form of type HTMLFormElement, readonly: Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
prompt of type DOMString: The prompt message. See the prompt attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.

Interface HTMLStyleElement

Style information. See the STYLE element definition in HTML 4.01, the CSS module [DOM Level 2 Style Sheets and CSS] and the LinkStyle interface in the StyleSheets module [DOM Level 2 Style Sheets and CSS].

IDL Definition

interface HTMLStyleElement : HTMLElement {
           attribute boolean         disabled;
           attribute DOMString       media;
           attribute DOMString       type;
};

Attributes

disabled of type boolean: Enables/disables the style sheet.
media of type DOMString: Designed for use with one or more target media. See the media attribute definition in HTML 4.01.
type of type DOMString: The content type of the style sheet language. See the type attribute definition in HTML 4.01.

Interface HTMLBodyElement

The HTML document body. This element is always present in the DOM API, even if the tags are not present in the source document. See the BODY element definition in HTML 4.01.

IDL Definition

interface HTMLBodyElement : HTMLElement {
           attribute DOMString       aLink;
           attribute DOMString       background;
           attribute DOMString       bgColor;
           attribute DOMString       link;
           attribute DOMString       text;
           attribute DOMString       vLink;
};

Attributes

aLink of type DOMString: Color of active links (after mouse-button down, but before mouse-button up). See the alink attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
background of type DOMString: URI [IETF RFC 2396] of the background texture tile image. See the background attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
bgColor of type DOMString: Document background color. See the bgcolor attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
link of type DOMString: Color of links that are not active and unvisited. See the link attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
text of type DOMString: Document text color. See the text attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
vLink of type DOMString: Color of links that have been visited by the user. See the vlink attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.

Interface HTMLFormElement

The FORM element encompasses behavior similar to a collection and an element. It provides direct access to the contained form controls as well as the attributes of the form element. See the FORM element definition in HTML 4.01.

IDL Definition

interface HTMLFormElement : HTMLElement {
  readonly attribute HTMLCollection  elements;
  readonly attribute long            length;
           attribute DOMString       name;
           attribute DOMString       acceptCharset;
           attribute DOMString       action;
           attribute DOMString       enctype;
           attribute DOMString       method;
           attribute DOMString       target;
  void               submit();
  void               reset();
};

Attributes

acceptCharset of type DOMString: List of character sets supported by the server. See the accept-charset attribute definition in HTML 4.01.
action of type DOMString: Server-side form handler. See the action attribute definition in HTML 4.01.
elements of type HTMLCollection, readonly: Returns a collection of all form control elements in the form.
enctype of type DOMString: The content type of the submitted form, generally "application/x-www-form-urlencoded". See the enctype attribute definition in HTML 4.01.
Note: The onsubmit even handler is not guaranteed to be triggered when invoking this method. The behavior is inconsistent for historical reasons and authors should not rely on a particular one.
length of type long, readonly: The number of form controls in the form.
method of type DOMString: HTTP method [IETF RFC 2616] used to submit form. See the method attribute definition in HTML 4.01.
name of type DOMString: Names the form.
target of type DOMString: Frame to render the resource in. See the target attribute definition in HTML 4.01.

Methods

reset: Restores a form element's default values. It performs the same action as a reset button.
No Parameters

No Return Value

No Exceptions
submit: Submits the form. It performs the same action as a submit button.
No Parameters

No Return Value

No Exceptions

Interface HTMLSelectElement

The select element allows the selection of an option. The contained options can be directly accessed through the select element as a collection. See the SELECT element definition in HTML 4.01.

IDL Definition

interface HTMLSelectElement : HTMLElement {
  readonly attribute DOMString       type;
           attribute long            selectedIndex;
           attribute DOMString       value;
  // Modified in DOM Level 2:
           attribute unsigned long   length;
                                        // raises(DOMException) on setting

  readonly attribute HTMLFormElement form;
  // Modified in DOM Level 2:
  readonly attribute HTMLOptionsCollection options;
           attribute boolean         disabled;
           attribute boolean         multiple;
           attribute DOMString       name;
           attribute long            size;
           attribute long            tabIndex;
  void               add(in HTMLElement element, 
                         in HTMLElement before)
                                        raises(DOMException);
  void               remove(in long index);
  void               blur();
  void               focus();
};

Attributes

disabled of type boolean

The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.

form of type HTMLFormElement, readonly

Returns the FORM element containing this control. Returns null if this control is not within the context of a form.

length of type unsigned long, modified in DOM Level 2

The number of options in this SELECT.

Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: if setting the length is not allowed by the implementation.

multiple of type boolean

If true, multiple OPTION elements may be selected in this SELECT. See the multiple attribute definition in HTML 4.01.

name of type DOMString

Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.

options of type HTMLOptionsCollection, readonly, modified in DOM Level 2

The collection of OPTION elements contained by this element.

selectedIndex of type long

The ordinal index of the selected option, starting from 0. The value -1 is returned if no element is selected. If multiple options are selected, the index of the first selected option is returned.

size of type long

Number of visible rows. See the size attribute definition in HTML 4.01.

tabIndex of type long

Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.

type of type DOMString, readonly

The type of this form control. This is the string "select-multiple" when the multiple attribute is true and the string "select-one" when false.

value of type DOMString

The current form control value (i.e. the value of the currently selected option), if multiple options are selected this is the value of the first selected option.

Methods

add

Add a new element to the collection of OPTION elements for this SELECT. This method is the equivalent of the appendChild method of the Node interface if the before parameter is null. It is equivalent to the insertBefore method on the parent of before in all other cases. This method may have no effect if the new element is not an OPTION or an OPTGROUP.

Parameters

element of type HTMLElement: The element to add.
before of type HTMLElement: The element to insert before, or null for the tail of the list.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if before is not a descendant of the SELECT element.

No Return Value

blur

Removes keyboard focus from this element.

No Parameters

No Return Value

No Exceptions

focus

Gives keyboard focus to this element.

No Parameters

No Return Value

No Exceptions

remove

Remove an element from the collection of OPTION elements for this SELECT. Does nothing if no element has the given index.

Parameters

index of type long: The index of the item to remove, starting from 0.

No Return Value

No Exceptions

Interface HTMLOptGroupElement

Group options together in logical subdivisions. See the OPTGROUP element definition in HTML 4.01.

IDL Definition

interface HTMLOptGroupElement : HTMLElement {
           attribute boolean         disabled;
           attribute DOMString       label;
};

Attributes

disabled of type boolean: The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
label of type DOMString: Assigns a label to this option group. See the label attribute definition in HTML 4.01.

Interface HTMLOptionElement

A selectable choice. See the OPTION element definition in HTML 4.01.

IDL Definition

interface HTMLOptionElement : HTMLElement {
  readonly attribute HTMLFormElement form;
  // Modified in DOM Level 2:
           attribute boolean         defaultSelected;
  readonly attribute DOMString       text;
  // Modified in DOM Level 2:
  readonly attribute long            index;
           attribute boolean         disabled;
           attribute DOMString       label;
           attribute boolean         selected;
           attribute DOMString       value;
};

Attributes

defaultSelected of type boolean, modified in DOM Level 2: Represents the value of the HTML selected attribute. The value of this attribute does not change if the state of the corresponding form control, in an interactive user agent, changes. See the selected attribute definition in HTML 4.01.
disabled of type boolean: The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly: Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
index of type long, readonly, modified in DOM Level 2: The index of this OPTION in its parent SELECT, starting from 0.
label of type DOMString: Option label for use in hierarchical menus. See the label attribute definition in HTML 4.01.
selected of type boolean: Represents the current state of the corresponding form control, in an interactive user agent. Changing this attribute changes the state of the form control, but does not change the value of the HTML selected attribute of the element.
text of type DOMString, readonly: The text contained within the option element.
value of type DOMString: The current form control value. See the value attribute definition in HTML 4.01.

Interface HTMLInputElement

Form control.

Note: Depending upon the environment in which the page is being viewed, the value property may be read-only for the file upload input type. For the "password" input type, the actual value returned may be masked to prevent unauthorized use. See the INPUT element definition in [HTML 4.01].

IDL Definition

interface HTMLInputElement : HTMLElement {
           attribute DOMString       defaultValue;
           attribute boolean         defaultChecked;
  readonly attribute HTMLFormElement form;
           attribute DOMString       accept;
           attribute DOMString       accessKey;
           attribute DOMString       align;
           attribute DOMString       alt;
           attribute boolean         checked;
           attribute boolean         disabled;
           attribute long            maxLength;
           attribute DOMString       name;
           attribute boolean         readOnly;
  // Modified in DOM Level 2:
           attribute unsigned long   size;
           attribute DOMString       src;
           attribute long            tabIndex;
  // Modified in DOM Level 2:
           attribute DOMString       type;
           attribute DOMString       useMap;
           attribute DOMString       value;
  void               blur();
  void               focus();
  void               select();
  void               click();
};

Attributes

accept of type DOMString: A comma-separated list of content types that a server processing this form will handle correctly. See the accept attribute definition in HTML 4.01.
accessKey of type DOMString: A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
align of type DOMString: Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
alt of type DOMString: Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.01.
checked of type boolean: When the type attribute of the element has the value "radio" or "checkbox", this represents the current state of the form control, in an interactive user agent. Changes to this attribute change the state of the form control, but do not change the value of the HTML checked attribute of the INPUT element.
Note: During the handling of a click event on an input element with a type attribute that has the value "radio" or "checkbox", some implementations may change the value of this property before the event is being dispatched in the document. If the default action of the event is canceled, the value of the property may be changed back to its original value. This means that the value of this property during the handling of click events is implementation dependent.
defaultChecked of type boolean: When type has the value "radio" or "checkbox", this represents the HTML checked attribute of the element. The value of this attribute does not change if the state of the corresponding form control, in an interactive user agent, changes. See the checked attribute definition in HTML 4.01.
defaultValue of type DOMString: When the type attribute of the element has the value "text", "file" or "password", this represents the HTML value attribute of the element. The value of this attribute does not change if the contents of the corresponding form control, in an interactive user agent, changes. See the value attribute definition in HTML 4.01.
disabled of type boolean: The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly: Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
maxLength of type long: Maximum number of characters for text fields, when type has the value "text" or "password". See the maxlength attribute definition in HTML 4.01.
name of type DOMString: Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.
readOnly of type boolean: This control is read-only. Relevant only when type has the value "text" or "password". See the readonly attribute definition in HTML 4.01.
size of type unsigned long, modified in DOM Level 2: Size information. The precise meaning is specific to each type of field. See the size attribute definition in HTML 4.01.
src of type DOMString: When the type attribute has the value "image", this attribute specifies the location of the image to be used to decorate the graphical submit button. See the src attribute definition in HTML 4.01.
tabIndex of type long: Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
type of type DOMString, modified in DOM Level 2: The type of control created (all lower case). See the type attribute definition in HTML 4.01.
useMap of type DOMString: Use client-side image map. See the usemap attribute definition in HTML 4.01.
value of type DOMString: When the type attribute of the element has the value "text", "file" or "password", this represents the current contents of the corresponding form control, in an interactive user agent. Changing this attribute changes the contents of the form control, but does not change the value of the HTML value attribute of the element. When the type attribute of the element has the value "button", "hidden", "submit", "reset", "image", "checkbox" or "radio", this represents the HTML value attribute of the element. See the value attribute definition in HTML 4.01.

Methods

blur: Removes keyboard focus from this element.
No Parameters

No Return Value

No Exceptions
click: Simulate a mouse-click. For INPUT elements whose type attribute has one of the following values: "button", "checkbox", "radio", "reset", or "submit".
No Parameters

No Return Value

No Exceptions
focus: Gives keyboard focus to this element.
No Parameters

No Return Value

No Exceptions
select: Select the contents of the text area. For INPUT elements whose type attribute has one of the following values: "text", "file", or "password".
No Parameters

No Return Value

No Exceptions

Interface HTMLTextAreaElement

Multi-line text field. See the TEXTAREA element definition in HTML 4.01.

IDL Definition

interface HTMLTextAreaElement : HTMLElement {
  // Modified in DOM Level 2:
           attribute DOMString       defaultValue;
  readonly attribute HTMLFormElement form;
           attribute DOMString       accessKey;
           attribute long            cols;
           attribute boolean         disabled;
           attribute DOMString       name;
           attribute boolean         readOnly;
           attribute long            rows;
           attribute long            tabIndex;
  readonly attribute DOMString       type;
           attribute DOMString       value;
  void               blur();
  void               focus();
  void               select();
};

Attributes

accessKey of type DOMString: A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
cols of type long: Width of control (in characters). See the cols attribute definition in HTML 4.01.
defaultValue of type DOMString, modified in DOM Level 2: Represents the contents of the element. The value of this attribute does not change if the contents of the corresponding form control, in an interactive user agent, changes.
disabled of type boolean: The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly: Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
name of type DOMString: Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.
readOnly of type boolean: This control is read-only. See the readonly attribute definition in HTML 4.01.
rows of type long: Number of text rows. See the rows attribute definition in HTML 4.01.
tabIndex of type long: Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
type of type DOMString, readonly: The type of this form control. This the string "textarea".
value of type DOMString: Represents the current contents of the corresponding form control, in an interactive user agent. Changing this attribute changes the contents of the form control, but does not change the contents of the element. If the entirety of the data can not fit into a single DOMString, the implementation may truncate the data.

Methods

blur: Removes keyboard focus from this element.
No Parameters

No Return Value

No Exceptions
focus: Gives keyboard focus to this element.
No Parameters

No Return Value

No Exceptions
select: Select the contents of the TEXTAREA.
No Parameters

No Return Value

No Exceptions

Interface HTMLButtonElement

Push button. See the BUTTON element definition in HTML 4.01.

IDL Definition

interface HTMLButtonElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString       accessKey;
           attribute boolean         disabled;
           attribute DOMString       name;
           attribute long            tabIndex;
  readonly attribute DOMString       type;
           attribute DOMString       value;
};

Attributes

accessKey of type DOMString: A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
disabled of type boolean: The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly: Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
name of type DOMString: Form control or object name when submitted with a form. See the

Document Object Model (DOM) Level 2 HTML Specification

Version 1.0

W3C Recommendation 09 January 2003

Abstract

Status of this document

Table of contents

Expanded Table of Contents

Copyright Notice

W3C Document Copyright Notice and License

W3C Software Copyright Notice and License

1. Document Object Model HTML

Table of contents

1.1. Introduction

1.2. HTML Application of Core DOM

1.2.1. Naming Conventions

1.2.1.1. Properties and Methods

1.2.1.2. Non-HTML 4.0 interfaces and attributes

1.3. XHTML and the HTML DOM

1.4. Miscellaneous Object Definitions

1.5. Objects related to HTML documents

1.6. HTML Elements

1.6.1. Property Attributes

1.6.2. Naming Exceptions

1.6.3. Exposing Element Type Names (`tagName`, (`nodeName`))

1.6.4. The HTMLElement interface

1.6.5. Object definitions

Document Object Model (DOM) Level 2 HTML Specification

Version 1.0

W3C Recommendation 09 January 2003

Abstract

Status of this document

Table of contents

Expanded Table of Contents

Copyright Notice

W3C Document Copyright Notice and License

W3C Software Copyright Notice and License

1. Document Object Model HTML

Table of contents

1.1. Introduction

1.2. HTML Application of Core DOM

1.2.1. Naming Conventions

1.2.1.1. Properties and Methods

1.2.1.2. Non-HTML 4.0 interfaces and attributes

1.3. XHTML and the HTML DOM

1.4. Miscellaneous Object Definitions

1.5. Objects related to HTML documents

1.6. HTML Elements

1.6.1. Property Attributes

1.6.2. Naming Exceptions

1.6.3. Exposing Element Type Names (tagName, (nodeName))

1.6.4. The HTMLElement interface

1.6.5. Object definitions

1.6.3. Exposing Element Type Names (`tagName`, (`nodeName`))