JavaScript Document getElementsByClassName() Method

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

Definition

document.getElementsByClassName(names) returns a live HTMLCollection of elements that have all of the given class name(s). On document it searches the whole tree; you can also call it on an element to limit the search (MDN).

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

Syntax

Call document.getElementsByClassName. Start with this line.

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

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

Library declarations
JavaScript
document.getElementsByClassName(names)

Parameters

ParameterDescription
namesRequired. Whitespace-separated class name string
Multiple namesOptional. Element must include all listed classes

Return Value

Return ValueDescription
*Live HTMLCollection

JavaScript Examples

Example 1 — Match One Class

Collect every element with class test and read the first one.

JavaScript
// HTML: <p class="test">A</p><p class="test">B</p>
const list = document.getElementsByClassName("test");

console.log(list.length);           // 2
console.log(list[0].textContent);   // "A"
console.log(list.constructor.name); // "HTMLCollection"
Try It Yourself

How It Works

  1. Pass one class. No leading dot — just the name string.
  2. Get a collection. Not a single Element (unless you index it).
  3. Read length. Count matches without converting to an array.
  4. Index [0]. First match, or undefined if empty.

Example 2 — Require Multiple Classes

Only elements that include every listed class are returned.

JavaScript
// <span class="orange fruit">...</span>
// <span class="orange juice">...</span>
const both = document.getElementsByClassName("orange juice");

console.log(both.length);         // 1
console.log(both[0].textContent); // "Orange Juice" (example)
Try It Yourself

How It Works

  1. Space-separate names. "orange juice" means both classes.
  2. AND logic. Having only orange is not enough.
  3. Same idea as CSS. Like .orange.juice in querySelectorAll.
  4. Order in the string. Class order in the argument does not matter.

Example 3 — Search Under One Parent

Call the method on an element to limit matches to its descendants.

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

console.log(inside.length); // only .test under #main
// document.getElementsByClassName("test") would search the whole page
Try It Yourself

How It Works

  1. Find the root. Often via getElementById.
  2. Call on that element. Search is limited to its subtree.
  3. Still a live collection. Same return type as the document method.
  4. Useful for widgets. Avoid grabbing matching nodes from other sections.
Compatibility

Browser Support

Document.getElementsByClassName() is a long-standing DOM lookup API. MDN lists it as Baseline Widely available (since July 2015).

✓ Baseline · DOM

Document.getElementsByClassName()

Supported in Chrome, Firefox, Safari, Edge, and other evergreen browsers. Safe for live class-based collections.

99% Universal API
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: Safe everywhere. Prefer querySelectorAll when you need static lists or richer selectors. See the MDN getElementsByClassName() reference.

Frequently Asked Questions

It returns an array-like object of all child elements that have all of the given class name(s). On document, it searches the complete document.
No. MDN marks Document.getElementsByClassName() as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
A live HTMLCollection of found elements. Changes in the DOM are reflected in the collection as they occur.
Pass a whitespace-separated string. Only elements that have ALL of those classes are selected (similar to .orange.juice in querySelectorAll).
Yes. You may call getElementsByClassName() on any element; it returns only matching descendants of that root.
Prefer querySelectorAll when you need more complex CSS selectors, a static NodeList snapshot, or easy Array methods without Array.prototype.call tricks.

Next: getElementsByName()

Learn document.getElementsByName() for form controls and elements with a name attribute.

getElementsByName() 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 Document getElementById() Method JavaScript Document getElementsByName() Method