getElementsByTagName (W3C DOM Core method)
var paragraphs = document.getElementByTagName('p');
The example above gets a reference to the collection of
p elements within the current document, and saves it to
the variable paragraphs. The returned collection is
live, which means that changes to the HTML it
represents are immediately reflected in the collection, without having to
retrieve it again.
This method can also be used contextually, to get a reference to the elements that are inside a specific element, for example:
var items = list.getElementByTagName('li');
So if the list in that example were a
ul element, the items variable would
refer to a collection of all the
li elements that are
inside that list.
The elements are retrieved in the linear order in which they appear in the document, ie. they correspond to a flattened view of the DOM. So if, in the previous example, the list corresponded with this HTML:
<ul> <li>Cheeses <ul> <li>Edam</li> <li>Gouda</li> <li>Cheddar</li> </ul> </li> <li>Hams <ul> <li>Prosciutto</li> <li>Parma</li> <li>Salami</li> </ul> </li> </ul>
The returned collection would be in the following order:
Get an ordered list of all elements with a given tag name, that are descendants of this document or element, in the linear order in which they appear in the DOM tree.
The returned collection is a
NodeList — an ordered
collection of nodes, indexed numerically starting from zero. If there are
no matching elements then it's a collection with zero members.
Even though a collection looks like an array, it isn't an array —
although you can iterate through it and refer to its members like an
array, you can't use
Array methods like
pop on it.
NodeList containing all the matched elements; if no
elements are found this will be a list with zero members.
Internet Explorer 5.5 in HTML doesn't support
* collection (all elements) — it returns a
collection with zero members.
Some developers use the proprietary
document.all collection as an equivalent for
IE 5.5, however great care should be taken when doing so, because it
isn't equivalent — the
all collection may
also include objects that are not elements, such as text nodes.
In Safari 1.3 and 2 in any XML which is not
XHTML, a search for a named element which just happens to
have the same name as an XHTML element will not match any such elements,
unless they're in the HTML namespace. So for example, if we were searching
title elements within an RSS document, the
following operation would return zero elements:
var titles = rssdoc.getElementsByTagName('title');
Because there's also an XHTML
title element, and this
seems to confuse Safari.
Those elements will show up in the
collection of all elements, and can also be found using a
getElementsByTagNameNS search in all namespaces:
var titles = rssdoc.getElementsByTagNameNS('*', 'title');
Opera in XHTML mode or
XML1, Safari in
XHTML mode or XML and Firefox 1.5 and 2 in
XHTML mode or XML ignore any namespace
prefix when matching elements; for example a search
div would include elements with the
foo:div. Of course the specification does not define
how this method should handle namespaces (whether it should be looking for
elements in the default namespace, or in no namespace, or both), but since
the argument specifies the
tagName of the element to
search, and the
tagName property returns a name that
includes any namespace
prefix, this behavior
is considered a bug.
Internet Explorer in HTML cannot see
namespace prefixes, so elements with the
html:div would also be included, because IE would
see them as elements with the
div; in this situation it will return an element
nodeName in the specified case, rather than the
canonical uppercase form. Since HTML is not supposed to contain
namespaced elements, this cannot be considered a bug, and the support
table above does not take account of it.
1 On XHTML pages served as