JavaScript Document getElementsByClassName() Method

What You’ll Learn

document.getElementsByClassName() is an instance method that returns every element with the given class name(s) (see MDN Document: getElementsByClassName()). Learn the live HTMLCollection, multiple class matching, element-scoped searches, how it compares to querySelectorAll, and five try-it labs.

Introduction

When several elements share a class — cards, buttons, list items — getElementsByClassName collects them all in one array-like list.

MDN: the method returns an array-like object of all child elements that have all of the given class name(s). On document, the whole document is searched (including the root). You can also call it on any element to search only that subtree.

Related tutorials: getElementById(), getAnimations(), getElementsByName().

Understanding document.getElementsByClassName()

An instance method on document (and also on elements) from the Document interface (MDN).

• names — string of one or more class names, separated by whitespace (MDN).
• Return value — a live HTMLCollection of found elements (MDN).
• All classes required — with multiple names, the element must have every class (MDN).
• Document scope — searches the complete document when called on document (MDN).
• Element scope — on an element, only descendants of that root match (MDN).
• Not a real Array — array-like; use Array.from or Array.prototype helpers when needed (MDN).

📝 Syntax

General form of Document.getElementsByClassName (MDN):

getElementsByClassName(names)

Parameters

• names — a string representing the class name(s) to match; multiple class names are separated by whitespace (MDN).

Return value

A live HTMLCollection of found elements (MDN).

MDN quick samples

document.getElementsByClassName("test");
document.getElementsByClassName("red test");
document.getElementById("main").getElementsByClassName("test");
document.getElementsByClassName("test")[0];

⚖️ getElementsByClassName vs querySelectorAll

Examples Gallery

Examples follow MDN Document: getElementsByClassName() and practical beginner patterns.

const list = document.getElementsByClassName("test");
console.log(list.length);
console.log(list[0] && list[0].textContent);

2
hello world 2
(depends on the page markup)

const matches = document.getElementsByClassName("orange juice");
for (const el of matches) {
  console.log(el.textContent);
}
// Similar idea: document.querySelectorAll(".orange.juice")

Orange Juice

const parentDOM = document.getElementById("parent-id");
const test = parentDOM.getElementsByClassName("test");
const testTarget = test[0];
console.log(test.length);
console.log(testTarget && testTarget.textContent);

1
hello world 2

const cards = document.getElementsByClassName("card");
console.log("before:", cards.length);

cards[0].classList.remove("card");
console.log("after:", cards.length); // live list updated (MDN)

before: 2
after: 1

const testElements = document.getElementsByClassName("test");
const testDivs = Array.prototype.filter.call(
  testElements,
  (testElement) => testElement.nodeName === "DIV",
);
console.log(testDivs.length);
// Or: Array.from(testElements).filter(...)

1
(number of DIV nodes with class test)

🚀 Common Use Cases

• Style batches — highlight every .active item.
• Event wiring — attach listeners to all .btn elements.
• Scoped widgets — search only inside a panel with an element root.
• Multi-class filters — require both tag and selected.
• Prefer querySelectorAll — for complex selectors or static snapshots.
• Not unique ids — use getElementById() for one id.

📝 Notes

• MDN: Baseline Widely available since July 2015.
• MDN: returns a live HTMLCollection — watch iteration while mutating.
• MDN: multiple class names require all of them on the element.
• MDN: callable on document or on any element for a scoped search.
• Not a true Array — use Array.from or borrowed Array methods (MDN).
• Related: getElementById(), getAnimations(), getElementsByName().

💡 Best Practices