JavaScript Element getElementsByClassName() Method

What You’ll Learn

Element.getElementsByClassName() is an instance method that finds descendant elements matching one or more class names and returns a live HTMLCollection. Learn scoped searches, multiple classes, live-collection pitfalls, comparison with querySelectorAll(), and five try-it labs aligned with MDN.

Introduction

When you need every element with a certain CSS class inside a section of the page, getElementsByClassName() is a direct, readable option. It searches only descendants of the element you call it on—not the element itself.

The return value is a live HTMLCollection. If matching elements are added or removed from the subtree, the collection updates automatically (MDN).

This page is part of JavaScript Element. Document.getElementsByClassName() works the same way from the document root (MDN).

Understanding the getElementsByClassName() Method

Calling el.getElementsByClassName(names) walks the subtree under el and collects every descendant whose class list matches names.

• It is an instance method on Element.
• names — one or more class names, whitespace-separated (MDN).
• Returns a live HTMLCollection.
• Multiple classes mean the element must include all of them.
• Case-sensitive in standards mode; case-insensitive in quirks mode (MDN).
• Also available on Document for whole-page searches (MDN).

📝 Syntax

General form of Element.getElementsByClassName (MDN):

getElementsByClassName(names)

Parameters

names — a string containing one or more class names to match, separated by whitespace.

Return value

A live HTMLCollection of every descendant element that is a member of every class in names (MDN).

Common patterns

// Single class
const items = container.getElementsByClassName("item");

// Multiple classes (must have both)
const cards = container.getElementsByClassName("card featured");

// Scoped under #main (MDN)
const tests = document.getElementById("main")
  .getElementsByClassName("test");

// Access items
console.log(items.length);
console.log(items[0]);

Examples Gallery

Examples follow MDN Element.getElementsByClassName() patterns. Use View Output or Try It Yourself for each case.

const container = document.getElementById("list");
const items = container.getElementsByClassName("item");

console.log(items.length);
console.log(items[0].textContent);

3
First item

const main = document.getElementById("main");
const tests = main.getElementsByClassName("test");

console.log(tests.length);
// Only .test elements inside #main

2
(only inside #main)

const boxes = container.getElementsByClassName("red test");

console.log(boxes.length);
// Elements with class="red test" (both required)

1
(both red and test)

const matches = element.getElementsByClassName("color-box");

while (matches.length > 0) {
  matches.item(0).classList.add("hue-frame");
  matches[0].classList.remove("color-box");
}

All .color-box elements updated

const testElements = document.getElementsByClassName("test");

const testDivs = Array.prototype.filter.call(
  testElements,
  (el) => el.nodeName === "DIV"
);

console.log(testDivs.length);

2
(DIV elements only)

🚀 Common Use Cases

• Selecting all cards, list items, or buttons sharing a CSS class.
• Scoped queries inside a widget or component root element.
• Live dashboards that react when matching nodes are added dynamically.
• Bulk class toggling on a set of descendant elements.
• Teaching the difference between live collections and static NodeLists.
• Legacy codebases that predate widespread querySelectorAll usage.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available, October 2017).
• Returns a live HTMLCollection, not a static snapshot.
• Multiple class names must all be present on the element.
• Searches descendants only—the element you call it on is not included.
• Case-sensitive in standards mode; case-insensitive in quirks mode (MDN).
• Related: closest(), getClientRects(), JavaScript hub.

💡 Best Practices