Adding and Removing CSS Classes with JavaScript

Learn how to add and remove CSS classes with JavaScript using classList methods. Master add, remove, toggle, contains, and replace for dynamic UI styling.

JavaScriptbeginner
RuneHub Team
RuneHub Team
9 min read

Toggling CSS classes is the cleanest way to create interactive web pages. Instead of setting inline styles with JavaScript, you define your visual states in CSS and use JavaScript only to switch classes on and off. This keeps your styles maintainable and your JavaScript code short. The classList API provides five methods for managing an element's classes: add, remove, toggle, contains, and replace.

The classList Property

Every DOM element has a classList property that returns a live DOMTokenList of the element's CSS classes. This object provides methods to manipulate classes without touching the raw className string.

javascriptjavascript
// HTML: <div id="card" class="card featured dark"></div>
 
const card = document.getElementById("card");
 
console.log(card.classList);       // DOMTokenList ["card", "featured", "dark"]
console.log(card.classList.length); // 3
console.log(card.classList[0]);     // "card"
console.log(card.classList[1]);     // "featured"

classList vs className

The older className property is a plain string. Modifying it is error-prone because you have to manage spaces and duplicates manually:

javascriptjavascript
const element = document.querySelector(".box");
 
// className: raw string manipulation (fragile)
element.className = "box active";           // Overwrites ALL classes!
element.className += " highlighted";        // Works but can add duplicates
element.className = element.className.replace("active", ""); // Leaves extra space
 
// classList: clean API (safe)
element.classList.add("active");            // Adds without duplicates
element.classList.add("highlighted");       // Adds alongside existing classes
element.classList.remove("active");         // Removes cleanly
FeatureclassNameclassList
TypeStringDOMTokenList
Add a classManual string concatenationclassList.add("class")
Remove a classManual string replacementclassList.remove("class")
Check for classclassName.includes("class") (unreliable)classList.contains("class")
Toggle a classManual if/else logicclassList.toggle("class")
Replace a classManual string replaceclassList.replace("old", "new")
Risk of duplicatesYesNo (automatically prevented)
Risk of overwritingYes (className = "...")No (methods are additive)

Adding Classes with classList.add()

The add() method adds one or more classes to the element. If a class already exists, it is silently ignored (no duplicates).

javascriptjavascript
const button = document.querySelector(".btn");
 
// Add a single class
button.classList.add("active");
 
// Add multiple classes at once
button.classList.add("highlighted", "pulse", "large");
 
// Adding a class that already exists does nothing (no duplicates)
button.classList.add("active"); // No effect, "active" already present

Practical Examples

javascriptjavascript
// Show a modal
function openModal(modalId) {
  const modal = document.getElementById(modalId);
  const overlay = document.getElementById("overlay");
 
  modal.classList.add("visible");
  overlay.classList.add("visible");
  document.body.classList.add("no-scroll");
}
 
// Highlight form input on focus
const inputs = document.querySelectorAll("input, textarea");
inputs.forEach(input => {
  input.addEventListener("focus", () => {
    input.parentElement.classList.add("focused");
  });
});
 
// Add loading state to a button
function startLoading(button) {
  button.classList.add("loading", "disabled");
  button.disabled = true;
}

Removing Classes with classList.remove()

The remove() method removes one or more classes. If a class does not exist, the call is silently ignored.

javascriptjavascript
const card = document.querySelector(".card");
 
// Remove a single class
card.classList.remove("highlighted");
 
// Remove multiple classes at once
card.classList.remove("expanded", "animating", "selected");
 
// Removing a non-existent class does nothing (no error)
card.classList.remove("nonexistent"); // Silent, no error

Practical Examples

javascriptjavascript
// Close a modal
function closeModal(modalId) {
  const modal = document.getElementById(modalId);
  const overlay = document.getElementById("overlay");
 
  modal.classList.remove("visible");
  overlay.classList.remove("visible");
  document.body.classList.remove("no-scroll");
}
 
// Remove error state after user starts typing
const emailInput = document.getElementById("email");
emailInput.addEventListener("input", () => {
  emailInput.classList.remove("input-error");
  document.getElementById("email-error").classList.remove("visible");
});
 
// End loading state
function stopLoading(button) {
  button.classList.remove("loading", "disabled");
  button.disabled = false;
}

Toggling Classes with classList.toggle()

The toggle() method adds the class if it is absent, or removes it if it is present. It returns true if the class was added, false if removed.

javascriptjavascript
const nav = document.querySelector(".mobile-nav");
 
// Basic toggle
nav.classList.toggle("open"); // Adds "open" (returns true)
nav.classList.toggle("open"); // Removes "open" (returns false)
 
// Use the return value
const isOpen = nav.classList.toggle("open");
console.log(isOpen); // true if "open" was added, false if removed

Force Parameter

The optional second parameter forces a specific state:

javascriptjavascript
const element = document.querySelector(".item");
 
// Force add (equivalent to classList.add)
element.classList.toggle("active", true);  // Always adds
 
// Force remove (equivalent to classList.remove)
element.classList.toggle("active", false); // Always removes
 
// Conditional toggle based on a condition
const isLoggedIn = checkAuthStatus();
element.classList.toggle("authenticated", isLoggedIn);
element.classList.toggle("guest", !isLoggedIn);

Practical Examples

javascriptjavascript
// Dark mode toggle
const themeToggle = document.getElementById("theme-toggle");
themeToggle.addEventListener("click", () => {
  const isDark = document.body.classList.toggle("dark-mode");
  themeToggle.textContent = isDark ? "Light Mode" : "Dark Mode";
  localStorage.setItem("darkMode", isDark);
});
 
// Accordion section
function setupAccordion() {
  const headers = document.querySelectorAll(".accordion-header");
 
  headers.forEach(header => {
    header.addEventListener("click", () => {
      const section = header.parentElement;
      const isExpanding = section.classList.toggle("expanded");
 
      // Close other sections (optional: single-open behavior)
      if (isExpanding) {
        headers.forEach(other => {
          if (other !== header) {
            other.parentElement.classList.remove("expanded");
          }
        });
      }
    });
  });
}
 
// Sidebar collapse
const collapseBtn = document.getElementById("collapse-sidebar");
collapseBtn.addEventListener("click", () => {
  document.querySelector(".sidebar").classList.toggle("collapsed");
  document.querySelector(".main-content").classList.toggle("full-width");
});

Checking Classes with classList.contains()

The contains() method returns true if the element has the specified class, false otherwise.

javascriptjavascript
const card = document.querySelector(".card");
 
if (card.classList.contains("featured")) {
  console.log("This is a featured card");
}
 
if (!card.classList.contains("archived")) {
  console.log("Card is not archived");
}

Practical Examples

javascriptjavascript
// Conditional logic based on current state
function handleCardClick(card) {
  if (card.classList.contains("disabled")) {
    return; // Do nothing if card is disabled
  }
 
  if (card.classList.contains("selected")) {
    card.classList.remove("selected");
    removeFromSelection(card.dataset.id);
  } else {
    card.classList.add("selected");
    addToSelection(card.dataset.id);
  }
}
 
// Validate form before submission
function validateForm() {
  const fields = document.querySelectorAll(".form-field");
  let isValid = true;
 
  fields.forEach(field => {
    if (field.classList.contains("input-error")) {
      isValid = false;
    }
  });
 
  return isValid;
}

Replacing Classes with classList.replace()

The replace() method swaps one class for another in a single operation. It returns true if the old class was found and replaced, false if the old class was not present.

javascriptjavascript
const badge = document.querySelector(".badge");
 
// Replace "status-pending" with "status-approved"
const wasReplaced = badge.classList.replace("status-pending", "status-approved");
console.log(wasReplaced); // true if "status-pending" existed
 
// If the old class doesn't exist, nothing happens
badge.classList.replace("nonexistent", "something"); // Returns false

Practical Examples

javascriptjavascript
// Update status indicator
function updateOrderStatus(orderId, newStatus) {
  const statusBadge = document.querySelector(`[data-order="${orderId}"] .status`);
  const statuses = ["pending", "processing", "shipped", "delivered"];
 
  // Remove any existing status class and add the new one
  statuses.forEach(status => {
    if (statusBadge.classList.contains(`status-${status}`)) {
      statusBadge.classList.replace(`status-${status}`, `status-${newStatus}`);
    }
  });
 
  statusBadge.textContent = newStatus.charAt(0).toUpperCase() + newStatus.slice(1);
}
 
// Switch between tabs
function switchTab(tabGroup, activeTabId) {
  const tabs = document.querySelectorAll(`${tabGroup} .tab`);
 
  tabs.forEach(tab => {
    if (tab.id === activeTabId) {
      tab.classList.replace("tab-inactive", "tab-active");
    } else {
      tab.classList.replace("tab-active", "tab-inactive");
    }
  });
}

CSS for JavaScript Class Toggling

Define visual states in CSS that JavaScript toggles:

csscss
/* Modal visibility */
.modal {
  opacity: 0;
  visibility: hidden;
  transform: translateY(-20px);
  transition: all 0.3s ease;
}
 
.modal.visible {
  opacity: 1;
  visibility: visible;
  transform: translateY(0);
}
 
/* Form validation */
.form-input {
  border: 2px solid #e5e7eb;
  transition: border-color 0.2s;
}
 
.form-input.input-error {
  border-color: #ef4444;
  background-color: #fef2f2;
}
 
.form-input.input-success {
  border-color: #22c55e;
  background-color: #f0fdf4;
}
 
/* Button loading state */
.btn.loading {
  position: relative;
  color: transparent;
  pointer-events: none;
}
 
.btn.loading::after {
  content: "";
  position: absolute;
  width: 16px;
  height: 16px;
  border: 2px solid white;
  border-top-color: transparent;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}
 
@keyframes spin {
  to { transform: translate(-50%, -50%) rotate(360deg); }
}

Common Mistakes to Avoid

Mistake 1: Using className When You Mean classList

javascriptjavascript
// WRONG: Overwrites all existing classes
element.className = "active"; // Removes "card", "featured", everything else
 
// CORRECT: Adds "active" alongside existing classes
element.classList.add("active");

Mistake 2: Checking for Classes with includes()

javascriptjavascript
// WRONG: Can match partial class names
element.className.includes("active"); // Also matches "inactive"!
 
// CORRECT: Exact match only
element.classList.contains("active"); // Matches only "active"

Mistake 3: Passing Spaces Inside Class Names

javascriptjavascript
// WRONG: Throws an error (spaces not allowed in a single class name)
element.classList.add("my class"); // DOMException!
 
// CORRECT: Each class is a separate argument
element.classList.add("my-class");
element.classList.add("class-one", "class-two"); // Multiple as separate args

Mistake 4: Toggling Without Checking Dependencies

javascriptjavascript
// WRONG: Toggling independently can create invalid states
element.classList.toggle("expanded");
element.classList.toggle("collapsed"); // Both could end up true!
 
// CORRECT: Use replace or explicit add/remove
if (element.classList.contains("collapsed")) {
  element.classList.replace("collapsed", "expanded");
} else {
  element.classList.replace("expanded", "collapsed");
}

Real-World Example: Multi-Select Card Grid

javascriptjavascript
function createSelectableGrid(containerId) {
  const container = document.getElementById(containerId);
  const selectedIds = new Set();
  const counter = document.getElementById("selection-count");
 
  container.addEventListener("click", (event) => {
    const card = event.target.closest(".selectable-card");
    if (!card || card.classList.contains("disabled")) return;
 
    const id = card.dataset.id;
    const isSelected = card.classList.toggle("selected");
 
    if (isSelected) {
      selectedIds.add(id);
      card.querySelector(".check-icon").classList.add("visible");
    } else {
      selectedIds.delete(id);
      card.querySelector(".check-icon").classList.remove("visible");
    }
 
    // Update counter and action bar
    counter.textContent = `${selectedIds.size} selected`;
 
    const actionBar = document.getElementById("action-bar");
    actionBar.classList.toggle("visible", selectedIds.size > 0);
 
    // Update "Select All" button state
    const allCards = container.querySelectorAll(".selectable-card:not(.disabled)");
    const selectAllBtn = document.getElementById("select-all");
    const allSelected = selectedIds.size === allCards.length;
    selectAllBtn.classList.toggle("all-selected", allSelected);
    selectAllBtn.textContent = allSelected ? "Deselect All" : "Select All";
  });
 
  // Select All / Deselect All
  document.getElementById("select-all").addEventListener("click", () => {
    const cards = container.querySelectorAll(".selectable-card:not(.disabled)");
    const allSelected = selectedIds.size === cards.length;
 
    cards.forEach(card => {
      const id = card.dataset.id;
      if (allSelected) {
        card.classList.remove("selected");
        card.querySelector(".check-icon").classList.remove("visible");
        selectedIds.delete(id);
      } else {
        card.classList.add("selected");
        card.querySelector(".check-icon").classList.add("visible");
        selectedIds.add(id);
      }
    });
 
    counter.textContent = `${selectedIds.size} selected`;
    document.getElementById("action-bar").classList.toggle("visible", selectedIds.size > 0);
  });
 
  return {
    getSelected: () => Array.from(selectedIds),
    clearSelection: () => {
      container.querySelectorAll(".selected").forEach(card => {
        card.classList.remove("selected");
        card.querySelector(".check-icon").classList.remove("visible");
      });
      selectedIds.clear();
      counter.textContent = "0 selected";
      document.getElementById("action-bar").classList.remove("visible");
    }
  };
}
 
const grid = createSelectableGrid("photo-grid");
Rune AI

Rune AI

Key Insights

  • Five methods: add(), remove(), toggle(), contains(), and replace() cover all class manipulation needs
  • No duplicates: classList.add() automatically prevents duplicate class names, unlike className +=
  • Toggle return value: classList.toggle() returns a boolean indicating whether the class was added (true) or removed (false)
  • CSS separation: Define visual states in CSS and use JavaScript only to toggle classes for cleaner, more maintainable code
  • Avoid className: Never use className = to set classes as it overwrites all existing classes; use classList methods instead
RunePowered by Rune AI

Frequently Asked Questions

Does classList.add() create duplicate classes?

No. The `add` method checks whether the class already exists before adding it. If the element already has the class, the call does nothing and no duplicate appears. This is one of the main advantages over `className +=` which can add the same class multiple times.

Is classList supported in all browsers?

Yes. The `classList` property is supported in all modern browsers and has been since Internet Explorer 10. The `replace()` method was added later and is supported in all browsers since 2016. There is no need for polyfills in any current browser.

Can I iterate over classList?

Yes. The `DOMTokenList` returned by `classList` supports `forEach`, `for...of`, and index-based access. You can also convert it to an array with `Array.from(element.classList)` or the spread operator `[...element.classList]` to use array methods like `map`, `filter`, and `reduce`.

What is the performance difference between classList and className?

The `classList` methods are generally faster for single-class operations because they modify the class list internally without parsing the entire string. Using `className` to add or remove a single class requires building and assigning a new string. The difference is negligible for occasional operations but matters in tight loops over many elements.

How do I add a class to multiple elements at once?

Select all target elements with `querySelectorAll` and loop through them: `document.querySelectorAll(".item").forEach(el => el.classList.add("active"))`. There is no native method to add a class to a NodeList directly; you must iterate over each element individually.

Conclusion

The classList API is the standard way to manage CSS classes in JavaScript. Using add and remove for explicit state changes, toggle for on/off switches, contains for state checks, and replace for state transitions gives you a complete toolkit for building interactive UIs. Keep your visual styles in CSS files and use JavaScript only to switch classes. This separation makes your code easier to maintain, your styles easier to update, and your animations smoother because the browser can optimize CSS transitions better than inline style changes.

Tags

Web DevelopmentclassListJavaScriptCSSDOM
Previous
Building Beautiful JS UIs with Inter & Outfit
9 min read · beginner
Next
How to Use classList toggle in JavaScript DOM
8 min read · beginner

More in this topic

OffscreenCanvas API in JS for UI Performance

Master the OffscreenCanvas API to offload rendering from the main thread. Covers worker-based 2D and WebGL rendering, animation loops inside workers, bitmap transfer, double buffering, chart rendering pipelines, image processing, and performance measurement strategies.

Advanced Web Workers for High Performance JS

Master Web Workers for truly parallel JavaScript execution. Covers dedicated and shared workers, structured cloning, transferable objects, SharedArrayBuffer with Atomics, worker pools, task scheduling, Comlink RPC patterns, module workers, and performance profiling strategies.

JavaScript Macros and Abstract Code Generation

Master JavaScript code generation techniques for compile-time and runtime metaprogramming. Covers AST manipulation, Babel plugin authorship, tagged template literals as macros, code generation pipelines, source-to-source transformation, compile-time evaluation, and safe eval alternatives.