getElementsByTagName (W3C DOM Core method)

Tweet

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 descendents 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.

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.

Learn HTML5 Online

Get all SitePoint books and courses with a Learnable membership. Start building future-proof websites that are faster, more powerful, and easier to maintain.

No Reader comments