Availability

DOM Level 2 Core; in DOM Level 1, defined by HTMLDocument

Synopsis

Element getElementById(String elementId);

Arguments

elementId

The value of the id attribute of the desired element.

Returns

The Element node that represents the document element with the specified id attribute, or null if no such element is found.

Description

This method searches the document for an Element node with an id attribute whose value is elementId, and returns that Element. If no such Element is found, it returns null. The value of the id attribute is intended to be unique within a document, and if this method finds more than one Element with the specified elementId, it may return one at random or it may return null.

In HTML documents, this method always searches for attributes named id. In XML documents, however, it searches for any attribute whose type is id, regardless of what the attribute name is. If XML attribute types are not known (because, for example, the XML parser could not locate the document's DTD), this method always returns null.

This is an important and commonly used method since it provides a simple way to obtain the Element object that represents a specific document element. Note that it provides functionality similar to the nonstandard document.all[] array defined by Internet Explorer 4 and later. Finally, note that the name of this method ends with "Id", not with "ID"; be careful not to misspell it.

See Also

Document.getElementsByTagName( ), Element.getElementsByTagName( ), HTMLDocument.getElementsByName( )