When building web apps, applying CSS classes via JavaScript is one of the simplest but most powerful techniques to control UI appearance. But while most devs know that classList.add can attach a new class, they often overlook dynamic class management during user interactions or animations. How can you efficiently add, remove, or toggle classes across modern and legacy browsers without causing layout thrashing?

Using the right approach—whether classList methods or fallback to className—not only simplifies your code but makes your UI more responsive and maintainable. Understanding these APIs helps you avoid common pitfalls and keep your styles in sync with state changes smoothly.

Add Class Basics

The simplest way to add a CSS class to an element in JavaScript is through the classList API. It is part of the JavaScript DOM and gives us high-level methods. Rather than juggling with strings, classList lets you work with classes directly. To get started, select the target element.

You can use document.querySelector or getElementById to find your element. Then call classList.add with one or more class names. This will not overwrite existing classes, making it safer than direct assignments. For example:

const box = document.querySelector('.box');
box.classList.add('highlight');

In the snippet above, 'highlight' is added without affecting other classes on the element. You can also pass multiple class names in one call:

box.classList.add('active', 'visible');

Under the hood, classList acts like a live DOMTokenList and updates the element’s className automatically. Other useful methods include remove, toggle, contains, and replace. Each provides a clear and semantic way to update styles based on logic.

Using classList.add is especially helpful when working with interactive elements. You can add hover effects, animation triggers, or error indicators by simply toggling classes. It keeps style logic in CSS and behavior in JavaScript.

Using className Approach

Before classList existed, developers relied on element.className to set or get classes. It reads and writes the entire class attribute as a string. While this works, it can overwrite existing classes if not handled carefully.

For example, setting className directly replaces all current classes:

const btn = document.getElementById('submit');
btn.className = 'btn primary';

Notice this wipes out any other classes on the element. To append rather than replace, you might do:

btn.className = btn.className + ' disabled';

This manual parsing requires extra checks for spaces and duplicates. You would split, filter, and join the string yourself:

let classes = btn.className.split(' ');
if (!classes.includes('disabled')) {
  classes.push('disabled');
}
btn.className = classes.join(' ');

Manually handling className is more verbose and error prone compared to classList. However, className has universal browser support (even IE6+), making it a reliable fallback in legacy environments. Use it when you need full control over the class string or when supporting very old browsers.

Dynamic Class Toggle

Toggling a CSS class based on user action is a common pattern. You can use classList.toggle to add the class if it’s missing or remove it if it’s present. This method simplifies event-driven style changes.

Here’s a basic toggle example bound to a button click:

const box = document.querySelector('.box');
const btn = document.querySelector('.toggle-btn');

btn.addEventListener('click', () => {
  const added = box.classList.toggle('highlight');
  console.log('Highlight added?', added);
});

In this snippet, clicking the button alternates the highlight class on the box. classList.toggle returns a boolean indicating whether the class was added. You can force add or remove by passing a second argument:

// Always add
box.classList.toggle('visible', true);
// Always remove
box.classList.toggle('visible', false);

Tip: Avoid inline style changes if you can use CSS classes. It keeps your design consistent and easier to maintain.

By relying on toggle, you reduce conditional code around contains and add/remove calls, making your scripts concise and intentional.

Multiple Element Adds

Often you need to add a class to a group of elements, like all buttons in a navbar. You can select multiple elements via document.querySelectorAll, which returns a NodeList. To iterate over that list:

const items = document.querySelectorAll('.nav-item');
items.forEach(item => {
  item.classList.add('active');
});

If you need broader support or prefer a classic loop:

const items = document.querySelectorAll('.nav-item');
for (let i = 0; i < items.length; i++) {
  items[i].classList.add('active');
}

Another option is a polyfill-ready method from our JavaScript forEach guide.

Common use cases include:

When working with large node lists, consider batching DOM updates to avoid layout thrashing:

Batching updates reduces reflows and repaints, resulting in smoother user experiences.

Browser Support Tips

While classList is well supported in modern browsers, you may still encounter edge cases in older environments. IE9+ supports classList, but IE8 and below do not. For full support, include a polyfill:

// Simple classList polyfill
if (!('classList' in document.documentElement)) {
  Object.defineProperty(Element.prototype, 'classList', {
    get() {
      return this.className.split(/\s+/);
    }
  });
}

Alternatively, use feature detection and fall back to className:

if (element.classList) {
  element.classList.add('highlight');
} else {
  element.className += ' highlight';
}

Tip: Automate polyfills with services like polyfill.io or tools like Babel. This keeps your bundle size minimal and your code resilient.

By planning for compatibility and using feature detection, you make your code more robust across environments.

Conclusion

Adding CSS classes via JavaScript is a foundational skill for modern front-end developers. Whether you choose classList methods or className fallback, understanding both APIs ensures you can support all browsers. Use classList.add and toggle for clear, atomic operations, and rely on className when you need full control or legacy support.

Remember to batch updates when dealing with multiple elements, and keep your UI logic in HTML/CSS classes instead of inline styles. Feature detection and polyfills will make your code resilient. With these techniques, you can build dynamic interfaces, enhance accessibility, and maintain clean code. Start applying them today to prevent surprises and deliver engaging user experiences.

The next time you need to change an element’s style dynamically, reach for classList or className as appropriate. Your future self—and other devs—will thank you for readable and reliable code.