JavaScript Element getElementsByClassName() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word GETELEMENTSBYCLASSNAME

Definition

In JavaScript, the getElementsByClassName() method returns a live HTMLCollection of every descendant that has the given class name or names (MDN). Calling it on an element scopes the search to that element’s subtree.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call el.getElementsByClassName. Start with this line.

JavaScript
el.getElementsByClassName(names)
CallWhat it does
el.getElementsByClassName(names)Primary signature.
el.getElementsByClassName(...)Call with the arguments your case needs.

Built into the browser. Call getElementsByClassName(...) on an Element — no import required.

Library declarations
JavaScript
el.getElementsByClassName(names)

Parameters

This member has no parameters beyond those shown in the signature.

Return Value

Return ValueDescription
*Live HTMLCollection

JavaScript Examples

Example 1 — Scoped Search

MDN pattern: search for test only under #main.

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

console.log(matches.length);
console.log(matches[0].textContent);
Try It Yourself

How It Works

  1. Pick a root. Only descendants of #main are searched.
  2. Pass one class name. Elements that include test match.
  3. Read length. Outside matches under another parent are ignored.
  4. Index into the collection. matches[0] is the first hit.

Example 2 — Multiple Classes (AND)

Elements must include every listed class (MDN).

JavaScript
const root = document.getElementById("list");
const matches = root.getElementsByClassName("red test");

console.log(matches.length);
Try It Yourself

How It Works

  1. Pass a space-separated string. Example: "red test".
  2. AND match. The element must have both red and test.
  3. Order in the string doesn’t matter. Class order on the element doesn’t either.
  4. Missing one class → no match. Only full intersections are returned.

Example 3 — Live Collection

Length updates when you add another matching descendant.

JavaScript
const root = document.getElementById("box");
const matches = root.getElementsByClassName("item");

console.log(matches.length); // before

const p = document.createElement("p");
p.className = "item";
p.textContent = "new";
root.appendChild(p);

console.log(matches.length); // after — same collection, updated
Try It Yourself

How It Works

  1. Capture the collection once. You don’t need to call the method again.
  2. Mutate the DOM. Append a new element with the same class.
  3. Length updates automatically. That is what “live” means (MDN).
  4. Contrast with querySelectorAll. A NodeList snapshot would stay at the old length.
Compatibility

Browser Support

Element.getElementsByClassName() is Baseline Widely available (MDN: across browsers since October 2017). Safe to use in modern evergreen browsers.

✓ Baseline · Widely available

getElementsByClassName()

Live HTMLCollection of descendant elements matching one or more class names.

99% Widely available
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
getElementsByClassName() Excellent

Bottom line: Use for fast class lookups in a subtree; use querySelectorAll when you need CSS selectors or a static snapshot.

Frequently Asked Questions

It returns a live HTMLCollection of descendant elements whose class list includes the specified class name or names. The search is limited to the subtree of the element you call it on (MDN).
No. MDN marks Element.getElementsByClassName() as Baseline Widely available (across browsers since October 2017). It is not Deprecated, Experimental, or Non-standard.
A string with one or more class names separated by whitespace. With multiple names, elements must include every listed class (MDN).
getElementsByClassName() returns a live HTMLCollection that updates when the DOM changes. querySelectorAll() returns a static NodeList snapshot.
Yes. MDN: matching elements are added or removed from the collection immediately when the DOM subtree changes.
Yes. Document.getElementsByClassName() works the same way but searches from the document root. Element.getElementsByClassName() searches only descendants of that element.

Next: getElementsByTagName()

Learn how to collect descendants by tag name.

getElementsByTagName tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Element getClientRects() Method JavaScript Element getElementsByTagName() Method