JavaScript

.getElementsByClassName()

Getting a list of elements with a specified class.

Time to read: less than 5 min

Briefly

The method is defined for the document object and any HTML element (Element) on the page. It allows you to find all elements with a specified class or classes among children.

The method takes one parameter — the name of the class or a list of classes in the form of a string. If you pass a list of classes, separate their names with spaces: class1 class2. An element matches if it has all the classes from the specified list.

Returns an array-like HTMLCollection with the found elements. If no elements were found, the collection will be empty, that is, with a size of 0.

Example

        
          
          <body>  <div id="title">    <h1>Hello, stranger!</h1>    <div class="paragraph subtitle">      div with classes paragraph and subtitle    </div>  </div>  <p class="paragraph">    Paragraph with class paragraph  </p></body>
          <body>
  <div id="title">
    <h1>Hello, stranger!</h1>
    <div class="paragraph subtitle">
      div with classes paragraph and subtitle
    </div>
  </div>
  <p class="paragraph">
    Paragraph with class paragraph
  </p>
</body>

        
        
          
        
      
        
          
          const paragraphs = document.getElementsByClassName('paragraph')console.log(paragraphs.length)// 2const divEl = document.getElementById('title')// Looking for paragraphs inside <div>const paragraphsFromDiv = divEl.getElementsByClassName('paragraph')console.log(paragraphsFromDiv.length)// 1, as there is only one element with class paragraph inside <div>const subtitleParagraphs = document.getElementsByClassName(  'paragraph subtitle')console.log(subtitleParagraphs.length)// 1, as there is only one element on the page,// which has both class paragraph and class subtitle// Looking for a non-existent elementconst spanFromBody = document.getElementsByClassName('hello')console.log(spanFromBody.length)// 0
          const paragraphs = document.getElementsByClassName('paragraph')
console.log(paragraphs.length)
// 2

const divEl = document.getElementById('title')
// Looking for paragraphs inside <div>
const paragraphsFromDiv = divEl.getElementsByClassName('paragraph')
console.log(paragraphsFromDiv.length)
// 1, as there is only one element with class paragraph inside <div>

const subtitleParagraphs = document.getElementsByClassName(
  'paragraph subtitle'
)
console.log(subtitleParagraphs.length)
// 1, as there is only one element on the page,
// which has both class paragraph and class subtitle

// Looking for a non-existent element
const spanFromBody = document.getElementsByClassName('hello')
console.log(spanFromBody.length)
// 0

How to understand

The method works with DOM, which is associated with the HTML markup. Each HTML element has parent and child elements.

  • Parent elements are the elements inside which the element is located. In the example above, the <h1> element has two parent elements — <div> and <body>.
  • Child elements are the elements contained within the current element. They may or may not exist. For example, for the <body> tag, all elements on the page are children. The <h1> has a child element — the text inside the tag.

If you are working with the root of the page, the document object, the search goes through all the elements on the page, starting from <body>. If the search is from a specific element, it only goes through its child elements.

Since we do not know in advance how many elements with the sought tag will be found, the method returns a collection of elements.

Each HTML element can have one or more classes. When using getElementsByClassName(), the search is only through classes (the class attribute). Tag names and all other attributes are ignored.

In practice

Advice 1

🛠 The method returns a live collection. This means that the collection will be automatically updated if matching elements appear on the page. If it’s unclear how it works, check the example in the material about the method getElementsByTagName().

🛠 Be careful when writing loops over HTMLCollection. Since the collection is live, the loop may become infinite in cases where matching elements are added and removed on the page.

🛠 Scripts that work with HTML only see the markup that the browser has already parsed. The browser parses HTML from top to bottom. If your script is at the top of the page, it will not find elements below — the browser has not seen them yet and knows nothing about them. Therefore, scripts are either included at the end of the page, or subscribe to the DOMContent​Loaded event, which signals that the browser has parsed all the HTML.

Read also

We use cookies for the analytics