The Element method getElementsByClassName() returns a live HTMLCollection which contains every descendant element which has the specified class name or names.

The method getElementsByClassName() on the Document interface works essentially the same way, except it acts on the entire document, starting at the document root.

Syntax

var elements = element.getElementsByClassName(names);

Parameters

names
A DOMString containing one or more class names to match on, separated by whitespace.

Return value

An HTMLCollection providing a live-updating list of every element which is a member of every class in names.

Usage notes

As always, the returned collection is live, meaning that it always reflects the current state of the DOM tree rooted at the element on which the function was called. As new elements that match names are added to the subtree, they immediately appear in the collection. Similarly, if an existing element that doesn't match names has its set of classes adjusted so that it matches, it immediately appears in the collection.

The opposite is also true; as elements no longer match the set of names, they are immediately removed from the collection.

In quirks mode, the class names are compared in a case-insensitive fashion. Otherwise, they're case sensitive.

Examples

Matching a single class

To look for elements that include among their classes a single specified class, we just provide that class name when calling getElementsByClassName():

element.getElementsByClassName('test');

This example finds all elements that have a class of test, which are also a descendant of the element that has the id of main:

document.getElementById('main').getElementsByClassName('test');

Matching multiple classes

To find elements whose class lists include both the red and test classes:

element.getElementsByClassName('red test');

Examining the results

You can use either the item() method on the returned HTMLCollection or standard array syntax to examine individual elements in the collection:

var matches = element.getElementsByClassName('colorbox');

for (var i=0; i<matches.length; i++) {
  matches[i].classList.remove('colorbox');
  matches.item(i).classList.add('hueframe');
}

This code finds descendant elements with the "colorbox" class, removes it (using array notation), and then adds the class "hueframe", by calling item() on the element's entry in the list.

Filtering the results using array methods

We can also use methods of Array.prototype on any HTMLCollection by passing the HTMLCollection as the method's this value. Here we'll find all <div> elements that have a class of test:

var testElements = document.getElementsByClassName('test');
var testDivs = Array.prototype.filter.call(testElements, function(testElement) {
  return testElement.nodeName === 'DIV';
});

Specifications

Specification Status Comment
DOM
The definition of 'Element.getElementsByClassName()' in that specification.
Living Standard Initial definition

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Yes) (Yes) [1] 9 (Yes) (Yes) [2]
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? ? [1] ? ? ?

[1] Prior to Firefox 19, this method was returning a NodeList; it was then changed to reflect the change in the spec.

[2] Safari on iOS 8 and OS X 10.10 returns a NodeList.

Document Tags and Contributors

 Last updated by: Sheppy,