Notes on the classList API

For me the classList API is one of the most useful parts of HTML5. Manipulating classes is an everyday part of JavaScript on the web, but is a cowpath that required a sure foot to tread before before getting the full treatment from the pavers in the form of classList.

The basic syntax is element.classList.method where method can be one of the following:

classList.add()

If all you need to do is add a class to an element use classList.add(). Let's say you have a div with an id of box and you want to add a class of "highlight" it would work like so: 

var box = document.getElementById('box');
box.classList.add('highlight');
The class is now added in the DOM and declarations in CSS for .highlight will be applied to the element.

More classes can be added the same way, so you can go ahead with box.classList.add(‘highlight–sidebar’) or box.classList.add(‘l-wide’) or any other classes you like.

You can only add one class at a time, so box.classList.add(‘class-1’,‘class-2’) doesn’t work.

classList.remove()

If we want to remove a class from the list it's just as simple: 

box.classList.remove('highlight');
The class has been removed in the DOM and any side effects of that will be applied.

classList.toggle()

The toggle method is useful for things like show/hide interfaces where the same action has opposite effects.

If there’s a button in our markup we can listen for clicks on it and use it to switch the highlight class on and off.

button = document.querySelector('button');
toggleBox = function() { box.classList.toggle('highlight'); };
button.addEventListener('click',toggleBox,false);

classList.contains()

If we need to check whether or not a particular class name is in the list we can use classList.contains() to return true or false.

It could be used to check if an image in a gallery has the class that makes it bigger than the rest or to check if a div has the class that makes it visually hidden for example.

if(box.classList.contains('highlight') {
    // do something
} else {
    // do something else
}

classList.item()

This method returns a string of the value of the item in the list at the index passed as an argument. That probably doesn't make sense so I'll it illustrate by using an example. If the HTML is <div class="highlight highlight--sidebar l-wide"> the following are all true: 

box.classList.item(0) === 'highlight';
box.classList.item(1) === 'highlight--sidebar';
box.classlist.item(2) === 'l-wide';
The number passed represents the position of the class name in the list, starting to count from 0.

Again it’s dead simple, although I have caught myself using square brackets as if it’s a normal array.

classList.length

This method does what it says on the tin and will be familiar to you if you have done any JavaScript before. It counts and returns how many classes are in the list.

In the example above console.log(box.classList.length) returns 3 as we currently have 3 class names on the element, highlight, highlight–sidebar and l-wide.

classList.toString()

If you ever need to turn the list of classes to a string use this method. console.log(typeof box.classList.toString()) will return "highlight highlight--sidebar l-wide" as a string.
Personally I find I'm using the classList API on pretty much every project now. If you're not too familiar or comfortable with JavaScript APIs its simplicity makes it a great place to start learning and its usefulness means you'll probably find a real world application on your current project.

Browser support is good and there are a couple of excellent polyfills I know of if you need to support older browsers. Bear in mind that JavaScript should be an enhancement in web pages so you should have a fallback in HTML and CSS that suffices for older browsers. Ask yourself do you need a polyfill before doing a copy/paste.

Resources

Tags