getElementsByTagName (W3C DOM Core method)

Share this article

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.

Frequently Asked Questions (FAQs) about getElementsByTagName Method

What is the getElementsByTagName method in JavaScript?

The getElementsByTagName method is a powerful tool in JavaScript that allows you to access and manipulate HTML elements based on their tag name. This method returns a live HTMLCollection of elements with the given tag name. The returned collection is live, meaning it updates itself automatically to stay in sync with the DOM tree. Therefore, changes in the DOM will be reflected in the collection.

How does the getElementsByTagName method differ from other DOM selection methods?

Unlike methods such as getElementById or getElementsByClassName, getElementsByTagName selects elements based on their tag name, such as ‘p’ for paragraph tags or ‘div’ for div tags. This makes it a versatile method for selecting multiple elements of the same type, rather than those with a specific ID or class.

Can I use getElementsByTagName on elements other than the document?

Yes, you can. While it’s common to use getElementsByTagName on the document object, you can also use it on any element node. This allows you to narrow down your selection to a specific section of the document.

How can I access individual elements from the collection returned by getElementsByTagName?

The getElementsByTagName method returns a live HTMLCollection, which is an array-like object. You can access individual elements in this collection using bracket notation, just like you would with an array. For example, if you want to access the first element, you can use collection[0].

Can I use array methods on the collection returned by getElementsByTagName?

While the collection returned by getElementsByTagName is array-like, it’s not a true array. This means you can’t directly use array methods like push, pop, or slice on it. However, you can convert it to a true array using Array.from() or the spread operator (…).

What does it mean that the collection returned by getElementsByTagName is live?

A live collection means that it automatically updates to reflect changes in the DOM. If elements are added or removed from the document, the collection will update to include or exclude these elements.

Can I use getElementsByTagName with XML documents?

Yes, you can. The getElementsByTagName method is part of the W3C DOM Core, which means it’s applicable to any document that uses the DOM, including XML documents.

How does case sensitivity affect the getElementsByTagName method?

In HTML documents, the getElementsByTagName method is case-insensitive, meaning it doesn’t matter whether you use uppercase or lowercase letters. However, in XML documents, it is case-sensitive.

Can I use getElementsByTagName to select elements in a specific namespace?

For that, you would need to use the getElementsByTagNameNS method, which allows you to specify both a namespace and a local name.

How can I loop through the elements returned by getElementsByTagName?

You can loop through the elements using a for loop or a for…of loop. Remember that the collection is live, so if you’re adding or removing elements in the loop, you may need to take this into account to avoid unexpected results.

Adam RobertsAdam Roberts
View Author

Adam is SitePoint's head of newsletters, who mainly writes Versioning, a daily newsletter covering everything new and interesting in the world of web development. He has a beard and will talk to you about beer and Star Wars, if you let him.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week