JS getElementsByClassName vs querySelector Guide

Compare getElementsByClassName and querySelector in JavaScript. Learn when to use each method, their performance differences, and how live vs static collections affect your DOM code.

JavaScriptbeginner

RuneHub Team

February 28, 2026

9 min read

RuneHub Team

Feb 28, 2026

9 min read

JavaScript gives you multiple ways to grab elements from the DOM, and two of the most common are getElementsByClassName and querySelector. They look similar on the surface, but they behave differently in ways that can introduce subtle bugs if you pick the wrong one. This guide breaks down every difference so you always know which method to reach for.

How getElementsByClassName Works

The getElementsByClassName method returns a live HTMLCollection of every element that has the specified class name. "Live" means the collection updates automatically when the DOM changes.

javascript

// Select all elements with the class "card"
const cards = document.getElementsByClassName("card");
 
console.log(cards.length); // 3
 
// Add a new card to the DOM
const newCard = document.createElement("div");
newCard.className = "card";
document.body.appendChild(newCard);
 
console.log(cards.length); // 4 (auto-updated!)

You can also pass multiple class names separated by spaces. The method returns elements that have all of the specified classes:

javascript

// Only elements with BOTH "card" and "featured" classes
const featuredCards = document.getElementsByClassName("card featured");
 
console.log(featuredCards.length);

Key Characteristics

Feature	Detail
Return type	Live HTMLCollection
Parameter	Space-separated class names (AND logic)
Supports CSS selectors	No, class names only
Available on	`document` and any element
Performance	Very fast (optimized hash lookup)

How querySelector Works

The querySelector method accepts any valid CSS selector string and returns the first matching element. Its sibling querySelectorAll returns a static NodeList of all matches.

javascript

// Select first element with class "card"
const firstCard = document.querySelector(".card");
 
// Select ALL elements with class "card"
const allCards = document.querySelectorAll(".card");
 
console.log(allCards.length); // 3
 
// Add a new card to the DOM
const newCard = document.createElement("div");
newCard.className = "card";
document.body.appendChild(newCard);
 
console.log(allCards.length); // Still 3 (static snapshot!)

The real power of querySelector is its CSS selector support:

javascript

// Compound selectors
const activeNavLink = document.querySelector("nav a.active");
 
// Attribute selectors
const emailInput = document.querySelector('input[type="email"]');
 
// Pseudo-class selectors
const firstItem = document.querySelector("li:first-child");
 
// Descendant combinators
const nestedSpan = document.querySelector(".card > .header span");

Key Characteristics

Feature	Detail
Return type	Element (querySelector) or static NodeList (querySelectorAll)
Parameter	Any valid CSS selector string
Supports CSS selectors	Yes, full CSS3 selector engine
Available on	`document` and any element
Performance	Slightly slower (parses CSS selector)

Live vs Static Collections: The Critical Difference

This is the most important distinction between the two methods. Understanding it prevents a whole category of bugs.

Live Collection Behavior

A live HTMLCollection from getElementsByClassName reflects DOM changes in real time:

javascript

const items = document.getElementsByClassName("item");
 
console.log(items.length); // 5
 
// Remove the first item's class
items[0].classList.remove("item");
 
console.log(items.length); // 4 (element left the collection!)
console.log(items[0]);     // Now points to what was items[1]

This shifting behavior causes a classic bug when looping:

javascript

const items = document.getElementsByClassName("highlight");
 
// BUG: Skips every other element!
for (let i = 0; i < items.length; i++) {
  items[i].classList.remove("highlight");
  // After removing class, collection shrinks and indexes shift
}
 
// FIX 1: Loop backwards
for (let i = items.length - 1; i >= 0; i--) {
  items[i].classList.remove("highlight");
}
 
// FIX 2: Convert to array first
const itemsArray = Array.from(items);
itemsArray.forEach(item => item.classList.remove("highlight"));

Static Collection Behavior

A static NodeList from querySelectorAll is a snapshot. It never changes after creation:

javascript

const items = document.querySelectorAll(".item");
 
console.log(items.length); // 5
 
// Remove the first item's class
items[0].classList.remove("item");
 
console.log(items.length); // Still 5
console.log(items[0]);     // Still the same element

This makes querySelectorAll safer to iterate:

javascript

const items = document.querySelectorAll(".highlight");
 
// Works perfectly, no shifting issues
items.forEach(item => item.classList.remove("highlight"));

Performance Comparison

For simple class-based selection, getElementsByClassName is generally faster because browsers maintain internal hash tables for class names. The querySelector methods must parse the CSS selector string before searching.

javascript

// Performance test: selecting 10,000 elements
const iterations = 100000;
 
// getElementsByClassName
console.time("getElementsByClassName");
for (let i = 0; i < iterations; i++) {
  document.getElementsByClassName("test-item");
}
console.timeEnd("getElementsByClassName");
 
// querySelectorAll
console.time("querySelectorAll");
for (let i = 0; i < iterations; i++) {
  document.querySelectorAll(".test-item");
}
console.timeEnd("querySelectorAll");

Typical results on a modern browser:

Method	100,000 iterations	Relative Speed
`getElementsByClassName`	~15ms	1x (baseline)
`querySelectorAll`	~120ms	~8x slower
`getElementById`	~10ms	Fastest (single ID lookup)

However, this difference only matters when you run selections in tight loops. For typical application code where you select elements a few times per user interaction, the difference is negligible.

When Performance Actually Matters

javascript

// Scenario: Filtering a table with 5,000 rows on every keystroke
function filterTable(searchTerm) {
  // Prefer getElementsByClassName here for speed
  const rows = document.getElementsByClassName("table-row");
 
  for (let i = 0; i < rows.length; i++) {
    const text = rows[i].textContent.toLowerCase();
    rows[i].style.display = text.includes(searchTerm) ? "" : "none";
  }
}
 
// For a one-time setup, querySelector is perfectly fine
const header = document.querySelector(".table-header .sort-button");
header.addEventListener("click", handleSort);

Selector Capability Comparison

Task	getElementsByClassName	querySelector / querySelectorAll
Select by single class	`getElementsByClassName("card")`	`querySelectorAll(".card")`
Select by multiple classes (AND)	`getElementsByClassName("card featured")`	`querySelectorAll(".card.featured")`
Select by class + tag	Not possible	`querySelectorAll("div.card")`
Select by attribute	Not possible	`querySelectorAll('[data-id="5"]')`
Select nested elements	Not possible	`querySelectorAll(".card .title")`
Select by pseudo-class	Not possible	`querySelectorAll("li:nth-child(odd)")`
Select first match only	Not possible (returns all)	`querySelector(".card")`

Best Practices for Choosing the Right Method

Use querySelector / querySelectorAll When

You need complex CSS selectors (attributes, pseudo-classes, combinators)
You want a static snapshot that won't change during iteration
You need only the first matching element
Code readability matters more than micro-optimization
You are selecting elements based on multiple criteria

javascript

// Complex selectors: querySelector wins
const activeTab = document.querySelector(".tabs > .tab.active");
const checkedBoxes = document.querySelectorAll('input[type="checkbox"]:checked');
const oddRows = document.querySelectorAll("tr:nth-child(odd)");

Use getElementsByClassName When

You need a live collection that auto-updates with DOM changes
Performance is critical (tight loops, large DOM, frequent selections)
You only need to select by class name(s)
You are building a real-time filtering or search feature

javascript

// Live collection: getElementsByClassName wins
const notifications = document.getElementsByClassName("unread");
 
// Check count updates automatically as notifications are read
function updateBadge() {
  badge.textContent = notifications.length;
}

Common Mistakes to Avoid

Mistake 1: Forgetting the Dot in querySelector

javascript

// WRONG: Missing the dot prefix
const cards = document.querySelectorAll("card"); // Selects <card> elements!
 
// CORRECT: Dot prefix for class names
const cards = document.querySelectorAll(".card");

Mistake 2: Treating HTMLCollection Like an Array

javascript

const items = document.getElementsByClassName("item");
 
// WRONG: forEach doesn't exist on HTMLCollection
items.forEach(item => console.log(item)); // TypeError!
 
// CORRECT: Convert to array first
Array.from(items).forEach(item => console.log(item));
 
// CORRECT: Use a for loop
for (let i = 0; i < items.length; i++) {
  console.log(items[i]);
}
 
// CORRECT: Use spread operator
[...items].forEach(item => console.log(item));

Mistake 3: Caching Length in Live Collections

javascript

const items = document.getElementsByClassName("removable");
 
// BUG: length changes as items are removed
const len = items.length;
for (let i = 0; i < len; i++) {
  items[i].remove(); // After first removal, indexes shift!
}
 
// FIX: Loop backwards or convert to array
while (items.length > 0) {
  items[0].remove();
}

Real-World Example: Dynamic Tag Filter

Here is a complete example that uses both methods strategically:

javascript

function createTagFilter(containerSelector) {
  const container = document.querySelector(containerSelector);
  const filterButtons = container.querySelectorAll(".filter-btn");
  
  // Live collection auto-updates when cards are added/removed
  const allCards = document.getElementsByClassName("product-card");
 
  filterButtons.forEach(button => {
    button.addEventListener("click", () => {
      const tag = button.dataset.tag;
 
      // Update active button (static selection is fine here)
      filterButtons.forEach(btn => btn.classList.remove("active"));
      button.classList.add("active");
 
      // Filter cards using the live collection
      for (let i = 0; i < allCards.length; i++) {
        const card = allCards[i];
        const cardTags = card.dataset.tags.split(",");
 
        if (tag === "all" || cardTags.includes(tag)) {
          card.style.display = "";
        } else {
          card.style.display = "none";
        }
      }
 
      // Update count (live collection length is always current)
      const visibleCount = container
        .querySelectorAll('.product-card:not([style*="display: none"])')
        .length;
      
      document.querySelector(".result-count").textContent =
        `${visibleCount} of ${allCards.length} products`;
    });
  });
}
 
createTagFilter("#shop");

Rune AI

Key Insights

Live vs static: getElementsByClassName returns live collections that auto-update; querySelectorAll returns static snapshots that never change
Selector power: querySelector supports any CSS selector while getElementsByClassName only accepts class names
Performance: getElementsByClassName is roughly 8x faster in micro-benchmarks, but the difference rarely matters in typical application code
Loop safety: Always loop backwards or convert to an array when modifying elements from a live HTMLCollection
Default choice: Use querySelector / querySelectorAll as your default; switch to getElementsByClassName only when live collections or performance optimization is needed

Frequently Asked Questions

Is querySelectorAll slower than getElementsByClassName?

Yes, `querySelectorAll` is measurably slower in micro-benchmarks because it must parse a CSS selector string and return a static copy. In real applications, the difference is usually a few microseconds per call and rarely affects user experience. Only optimize for this when doing thousands of selections in performance-critical loops.

Can I use forEach on getElementsByClassName results?

No, `getElementsByClassName` returns an HTMLCollection which does not have a built-in `forEach` method. You must convert it to an array first using `Array.from()` or the spread operator `[...collection]`. Alternatively, use a standard `for` loop to iterate.

What does "live collection" mean in practice?

live collection automatically reflects DOM changes without re-querying. If you add a new element with the matching class to the page, it appears in the collection immediately. If you remove an element's class, it disappears from the collection. This happens without calling `getElementsByClassName` again.

Should I always use querySelector for simplicity?

For most projects, yes. The `querySelector` and `querySelectorAll` methods offer a consistent API, support any CSS selector, and return static results that are easier to reason about. Reserve `getElementsByClassName` for performance-sensitive code paths where you need either raw speed or live collection behavior.

What happens if no elements match the selector?

The `querySelector` returns `null` when no element matches. The `querySelectorAll` returns an empty NodeList (length 0). The `getElementsByClassName` returns an empty HTMLCollection (length 0). Always check for `null` when using `querySelector` before accessing properties on the result.

Conclusion

Both getElementsByClassName and querySelector select elements from the DOM, but they serve different purposes. The querySelector family gives you full CSS selector power and returns static, predictable results. The getElementsByClassName method gives you raw speed and live collections that track DOM changes automatically. For everyday DOM manipulation, querySelector and querySelectorAll are the safer, more flexible choice. Switch to getElementsByClassName only when you need live behavior or are optimizing a measurable performance bottleneck.

JS getElementsByClassName vs querySelector Guide

How getElementsByClassName Works

Key Characteristics

How querySelector Works

Key Characteristics

Live vs Static Collections: The Critical Difference

Live Collection Behavior

Static Collection Behavior

Performance Comparison

When Performance Actually Matters

Selector Capability Comparison

Best Practices for Choosing the Right Method

Use querySelector / querySelectorAll When

Use getElementsByClassName When

Common Mistakes to Avoid

Mistake 1: Forgetting the Dot in querySelector

Mistake 2: Treating HTMLCollection Like an Array

Mistake 3: Caching Length in Live Collections

Real-World Example: Dynamic Tag Filter

Rune AI

Frequently Asked Questions

Is querySelectorAll slower than getElementsByClassName?

Can I use forEach on getElementsByClassName results?

What does "live collection" mean in practice?

Should I always use querySelector for simplicity?

What happens if no elements match the selector?

Conclusion

Tags

More in this topic

OffscreenCanvas API in JS for UI Performance

Advanced Web Workers for High Performance JS

JavaScript Macros and Abstract Code Generation

Stay Updated