Element: getElementsByClassName() method
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
js
getElementsByClassName(names)
Parameters
names
-
A string 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.
Note: 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()
:
js
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
:
js
document.getElementById("main").getElementsByClassName("test");
Matching multiple classes
To find elements whose class lists include both the red
and
test
classes:
js
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. However, the following code will not
work as one might expect because "matches"
will change as
soon as any "colorbox"
class is removed.
js
const matches = element.getElementsByClassName("colorbox");
for (let i = 0; i < matches.length; i++) {
matches[i].classList.remove("colorbox");
matches.item(i).classList.add("hueframe");
}
Instead, use another method, such as:
js
const matches = element.getElementsByClassName("colorbox");
while (matches.length > 0) {
matches.item(0).classList.add("hueframe");
matches[0].classList.remove("colorbox");
}
This code finds descendant elements with the "colorbox"
class, adds the
class "hueframe"
, by calling item(0)
, then removes
"colorbox"
(using array notation). Another element (if any are left) will
then become item(0)
.
Filtering the results using array methods
We can also use Array
methods 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
:
js
const testElements = document.getElementsByClassName("test");
const testDivs = Array.prototype.filter.call(
testElements,
(testElement) => testElement.nodeName === "DIV"
);
Specifications
Specification |
---|
DOM Standard # ref-for-dom-element-getelementsbyclassname |
Browser compatibility
BCD tables only load in the browser