getElementById (W3C DOM Core method)

Spec
Version Depr. Static
DOM2 No No
Browser support (more…)
IE5.5+ FF1.5+ SA1.3+ OP9+
Buggy Full Full Full
Returns
Element

Example

var element = document.getElementById('foo');

The example above gets a reference to an element with the ID, foo and saves it to the variable element. In HTML that would correspond with something like this:

<div id="foo"> ... </div>
Tip: null always evaluates to false

If the element doesn't exist then this method will return null. Therefore a condition that depends on the existence of an element can be written like this:

if(document.getElementById('foo')) { ... }

Because the ECMAScript specification requires that null evaluates to false.

Arguments

ID (DOMString) required

The unique ID value for the element to retrieve.

Description

Get an Element node with the specified ID.

This is not necessarily an element that has an Attr called id of the specified value — implementations define which attributes are of type ID within the DTD or Schema; in HTML this is the id attribute, but an implementation may define different attributes, or no attributes, as being of type ID1. If no attributes are so defined, or the implementation doesn't know, then this method should return null.

Return value

The element with the matching ID; or null if no matching element is found.

Compatibility

Internet Explorer Firefox Safari Opera
5.5 6.0 7.0 1.5 2.0 3.0 1.3 2.0 3.0 9.0 9.5
Buggy Buggy Buggy Full Full Full Full Full Full Full Full
CAUTION: May not work as expected in XML

Remember that this method is only certain to work in HTML, not in other forms of XML, because in other XML an id attribute won't necessarily be of type ID.

Internet Explorer in HTML also returns elements with the specified name attribute (as though the name attribute were of type ID).

In Internet Explorer in HTML, Opera in HTML or XHTML and Safari in HTML, all elements with an id attribute are mapped to objects in the global script scope (ie. as properties of window), so in those environments the following statements are all equivalent (if the element with the specified ID exists):

var element = document.getElementById('foo');

var element = window.foo;

var element = foo;
: Hmm…

I reckon this is a bad idea, because it pollutes the global scope and wastes memory. However it is still considered an additional feature rather than a bug, because the specification doesn't consider such things.

Internet Explorer in HTML and Opera in HTML or XHTML both map elements with a name attribute to objects in the global scope, but only Internet Explorer returns them for getElementById.

Internet Explorer in XML throws an error when using this method on documents it doesn't understand (where it doesn't know which elements are of type ID, or no elements are of type ID).

: When multiple elements share the same ID

The behavior of this method when more than one element of the specified ID exists is not standardized, because a document is not allowed to contain more than one element with the same ID. But for reference, in this situation all browsers return the first element found.

Tip: Defining an attribute as being of type ID

We can use DTD to define an attribute as being of type ID, so that getElementById will work. The following example defines a partial doctype for RSS so that the id attribute of an <item> element is of type ID:

<!DOCTYPE rss SYSTEM "-//CAKE//DTD RSS Test//EN"
[
    <!ATTLIST item id ID #IMPLIED>
]>

This approach works in Opera and Firefox, but not Safari or Internet Explorer.

Footnotes

1 The W3C has published a recommendation for an XML attribute called xml:id, which is universally of type ID, and therefore if used would remove the need for implementations to perform validation, or rely on resource lookups or internal subsets. However only Opera 9 currently implements this attribute.

User-contributed notes

Related Products