getElementsByTagName (W3C DOM Core method)

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