Document: getElementsByClassName() method
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
ThegetElementsByClassName method ofDocument interface returns an array-like objectof all child elements which have all of the given class name(s).
When called onthedocument object, the complete document is searched, including theroot node. You may also callgetElementsByClassName() on any element; it will return only elements which are descendants of the specified root element with the given class name(s).
Warning:This is a liveHTMLCollection. Changes in the DOM willreflect in the array as the changes occur. If an element selected by this array nolonger qualifies for the selector, it will automatically be removed. Be aware of thisfor iteration purposes.
Syntax
getElementsByClassName(names)Parameters
namesA string representing the class name(s) to match; multiple class names are separated by whitespace.
Return value
A liveHTMLCollection of found elements.
Examples
Get all elements that have a class of 'test':
document.getElementsByClassName("test");Get all elements that have both the 'red' and 'test' classes:
document.getElementsByClassName("red test");Get all elements that have a class of 'test', inside of an element that has the ID of'main':
document.getElementById("main").getElementsByClassName("test");Get the first element with a class of 'test', orundefined if there is nomatching element:
document.getElementsByClassName("test")[0];We can also use methods of Array.prototype on anyHTMLCollection bypassing theHTMLCollection as the method'sthis value. Herewe'll find all div elements that have a class of 'test':
const testElements = document.getElementsByClassName("test");const testDivs = Array.prototype.filter.call( testElements, (testElement) => testElement.nodeName === "DIV",);Get the first element whose class is 'test'
This is the most commonly used method of operation.
<div> <p>hello world 1</p> <p>hello world 2</p> <p>hello world 3</p> <p>hello world 4</p></div>const parentDOM = document.getElementById("parent-id");const test = parentDOM.getElementsByClassName("test"); // a list of matching elements, *not* the element itselfconsole.log(test); // HTMLCollection[1]const testTarget = parentDOM.getElementsByClassName("test")[0]; // the first element, as we wantedconsole.log(testTarget); // <p>hello world 2</p>Multiple Classes Example
document.getElementsByClassName works very similarly todocument.querySelector anddocument.querySelectorAll. Onlyelements with ALL of the classNames specified are selected.
HTML
<span>Orange Fruit</span><span>Orange Juice</span><span>Apple Juice</span><span>Something Random</span><textarea></textarea>#resultArea { width: 98%; height: 7em;}JavaScript
// getElementsByClassName only selects elements that have both given classesconst allOrangeJuiceByClass = document.getElementsByClassName("orange juice");let result = "document.getElementsByClassName('orange juice')";for (const el of allOrangeJuiceByClass) { result += `\n ${el.textContent}`;}// querySelector only selects full complete matchesconst allOrangeJuiceQuery = document.querySelectorAll(".orange.juice");result += "\n\ndocument.querySelectorAll('.orange.juice')";for (const el of allOrangeJuiceQuery) { result += `\n ${el.textContent}`;}document.getElementById("resultArea").value = result;Result
Specifications
| Specification |
|---|
| DOM # ref-for-dom-document-getelementsbyclassname① |