Skip to: content, navigation

getElementsByTagName (W3C DOM Core method)

Spec
Version Depr. Static
DOM1 No No
Browser support (more…)
IE6+ FF3+ SA1.3+ OP9+
Full Full Buggy Buggy
Returns
NodeList

Example

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:

  1. [0] Cheeses
  2. [1] Edam
  3. [2] Gouda
  4. [3] Cheddar
  5. [4] Hams
  6. [5] Prosciutto
  7. [6] Parma
  8. [7] Salami

Arguments

name (DOMString) required

The tagName of the elements to match. The value * matches all elements.

Description

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.

Note: A collection is not an array

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 push or pop on it.

Return value

A NodeList containing all the matched elements; if no elements are found this will be a list with zero members.

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
Partial Full Full Buggy Buggy Full Buggy Buggy Buggy Buggy Buggy

Internet Explorer 5.5 in HTML doesn't support the * collection (all elements) — it returns a collection with zero members.

CAUTION: Be careful with document.all

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 for RSS 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.

Tip: But there is a workaround…

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 for div would include elements with the tagName html:div or 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.

: Namespace behavior with Internet Explorer in HTML

Internet Explorer in HTML cannot see namespace prefixes, so elements with the tagName html:div would also be included, because IE would see them as elements with the tagName div; in this situation it will return an element with the tagName and 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.

Footnotes

1 On XHTML pages served as application/xhtml+xml.

Previous / Next page

  1. Previous
  2. Next

Related reference material

  • NodeList
    The NodeList interface represents an ordered collection of nodes, indexed by number.
  • getElementById
    Returns the Element node with the specified ID.
  • getElementsByTagNameNS
    Retrieves an ordered list of all elements with a given localName and namespaceURI, that are descendants of this document or element, in the linear order in which they appear in the DOM tree.

User-contributed notes

There are no comments yet.

Add a note

To post a note on this topic, please log in with your SitePoint username and password. If you don't have an account yet, you can create a new account for free.

Related Products

Search