Introduction

In JavaScript, you can change an element's class either by replacing the whole class attribute or by adding and removing individual class names. The modern and usually better tool is classList, because it lets you work with classes one at a time without accidentally overwriting unrelated styling hooks. The older className property still works, but it is best used only when you truly want to replace the entire class string.

Use classList for Targeted Class Changes

The classList API is the standard way to manipulate classes on a DOM element.

1const element = document.getElementById("message");
2
3element.classList.add("visible");
4element.classList.remove("hidden");

This is usually preferable because it preserves any other existing classes on the element.

The most common classList methods are:

• 'add()'
• 'remove()'
• 'toggle()'
• 'replace()'
• 'contains()'

These methods make your intent explicit and reduce bugs caused by manual string editing.

Replace All Classes with className

If you really want to replace the entire class attribute, use className.

const element = document.getElementById("message");
element.className = "box success";

This works, but it overwrites everything that was already on the element. That can be useful when you want one complete known class set, but it is risky if other code also depends on existing classes.

So the question is not “which API exists.” The question is “do I want to replace the entire class string or adjust only part of it.”

Toggle a Class for State Changes

toggle() is especially useful for UI state changes such as opening menus, highlighting selections, or switching themes.

1const button = document.getElementById("menuButton");
2const menu = document.getElementById("menu");
3
4button.addEventListener("click", () => {
5  menu.classList.toggle("open");
6});

You can also pass a boolean to control the result explicitly:

menu.classList.toggle("open", true);  // ensure it exists
menu.classList.toggle("open", false); // ensure it is removed

That form is often cleaner than writing separate if logic.

Replace One Class with Another

If the element already has one class and you want to swap it for another, replace() is convenient.

const badge = document.getElementById("statusBadge");
badge.classList.replace("pending", "approved");

This is clearer than manually removing one class and adding another in separate lines when the intent is a one-for-one state swap.

Full Example with a Button

A small end-to-end example makes the differences clearer.

<div id="card" class="card inactive">Account</div>
<button id="activateBtn">Activate</button>

1const card = document.getElementById("card");
2const activateBtn = document.getElementById("activateBtn");
3
4activateBtn.addEventListener("click", () => {
5  card.classList.remove("inactive");
6  card.classList.add("active");
7});

This changes only the relevant state class and leaves card intact.

Avoid Editing the Raw Attribute String Manually

You can manipulate the class attribute as text, but that is usually the least safe option.

For example, code like this is brittle:

element.className = element.className.replace("old", "new");

String replacement can accidentally touch partial matches or produce spacing issues. classList exists specifically to avoid that kind of low-level string handling.

Remember That CSS and JavaScript Must Agree on Class Names

Changing classes only matters if the rest of the app actually uses those class names consistently. If the CSS expects is-active but your JavaScript toggles active, nothing visible will happen even though the DOM change succeeded.

That is why class manipulation bugs are often naming-contract bugs rather than JavaScript API bugs.

Common Pitfalls

The most common mistake is using className when the real goal was only to add or remove one class. That can wipe out unrelated classes unexpectedly.

Another mistake is toggling the wrong class name and assuming the API failed when the real mismatch is between JavaScript and CSS naming.

Developers also manually edit class strings instead of using classList, which creates fragile code for no real benefit.

Summary

• Use classList when you want to add, remove, toggle, or replace specific classes.
• Use className only when you intentionally want to replace the entire class attribute.
• 'toggle() is useful for state-driven UI behavior.'
• Avoid manual string editing of class names when classList already provides safe DOM-aware methods.
• Make sure the class names used in JavaScript match the class names your CSS or component logic expects.