Definition and Usage
The classList.toggle() method adds the specified class attribute value to a DOM element if it does not exist, and removes it if it does. It returns true if the class value is added, and false if it is removed.
Note
Strictly speaking, it should not be described as adding a value to the class attribute if it does not exist and removing it if it does, but rather as adding a class name to the list of class names if it is not present, and removing it if it is present. The class attribute specifies one or more class names for an element, and its value is a list of class names separated by spaces. Although classList.toggle() should technically be described as adding a class name to the list of class names that is the value of the element's class attribute if it is not present and removing it if it is present, for consistency, this document uses the expression "add a class value if it does not exist, and remove it if it does".
Syntax
element.classList.toggle(className)
element.classList.toggle(className, force)
The toggle() function is a method of the classList object.
Parameters
className |
Required. The class value to be toggled on the element (a string). |
|---|---|
force |
Optional. A Boolean value (true or false) that forces the class value to be added or removed.
|
Return Value
- Returns
trueif the specified class value is added. - Returns
falseif the specified class value is removed.
Examples
The following three examples demonstrate how to use the classList.toggle() method.
Basic Usage
<style>
.bold {
font-weight: 600;
}
.bg-red {
background-color: red;
}
</style>
<p class="bold">The background color is added or removed.</p>
<button type="button">Add/Remove Background Color</button>
const elem = document.querySelector("p");
const button = document.querySelector("button");
button.addEventListener("click", () => { // Button click event
// Adds the "bg-red" class value if it does not exist; otherwise removes it
elem.classList.toggle("bg-red");
});
Code Explanation
The querySelector() function returns the first element that matches the specified CSS selector within the HTML document or a specific element.
Adding the "bg-red" class value to the <p> element with the classList.toggle() method adds a red background color. Conversely, removing it removes the background color.
"Add/Remove Background Color" button!
The background color is added or removed.
Using the Return Value
This example demonstrates how to use the return value of the classList.toggle() method.
It returns true when the specified class value is added, and false when it is removed.
The following example adds or removes the specified class value from an <input> element when the "Add/Remove Background Color" button is clicked, causing the background color to be added or removed.
<style>
.bg-red {
background-color: red;
}
</style>
<input type="text">
<button type="button">Add/Remove Background Color</button>
<p style="color: red;">
The status of the "bg-red" class value will be displayed here.
</p>
const inputElem = document.querySelector("input");
const button = document.querySelector("button");
const msgElem = document.querySelector("p");
button.addEventListener("click", () => { // Button click event
if (inputElem.classList.toggle("bg-red")) { // If the "bg-red" class value is added
msgElem.textContent = 'The "bg-red" class value has been added.';
} else { // If the "bg-red" class value is removed
msgElem.textContent = 'The "bg-red" class value has been removed.';
}
});
Adding the "bg-red" class value returns true, while removing it returns false.
"Add/Remove Background Color" button!
The status of the "bg-red" class value will be displayed here.
Using the Second Parameter (force)
The second parameter (force) of the classList.toggle() method is optional and can have a value of true or false.
- If set to
true, the specified class value is forcibly added regardless of whether it already exists on the element. - If set to
false, the specified class value is forcibly removed regardless of whether it already exists on the element.
The following example adds the "bg-red" class value only to the even-numbered <li> elements in an ordered list when the "Add Background Color to Even Items" button is clicked.
<style>
.bg-red {
background-color: red;
}
</style>
<ol>
<li>List Item</li>
<li>List Item</li>
<li>List Item</li>
<li>List Item</li>
<li>List Item</li>
</ol>
<button type="button">Add Background Color to Even Items</button>
const items = document.querySelectorAll("li");
const button = document.querySelector("button");
const itemsLength = items.length;
button.addEventListener("click", () => { // Button click event
for (let i = 0; i < itemsLength; i++) {
items[i].classList.toggle("bg-red", i % 2 === 1);
/* i % 2 === 1
: Evaluates to true for even-numbered list items and false for odd-numbered list items
: The "bg-red" class value is forcibly added to even-numbered list items
*/
}
});
Code Explanation
The querySelectorAll() function returns all elements that match the specified CSS selector within the HTML document or a specific element.
In this example, when the second parameter (i % 2 === 1) evaluates to true, the specified "bg-red" class value is added.
"Add Background Color to Even Items" button!
- List Item
- List Item
- List Item
- List Item
- List Item
Browser Compatibility
| Method |
Desktop Chrome
|
Desktop Edge
|
Desktop Firefox
|
Safari
|
|---|---|---|---|---|
classList.toggle()
|
24 | 12 | 24 | 7 |
Specifications
| Specification | |
|---|---|
classList.toggle()
|
DOM Standard #ref-for-dom-domtokenlist-toggle① |
See Also
- JavaScript classList Object – Manipulating the Class Attribute of DOM Elements
- JavaScript classList.add() – Add Class Values to an Element
- JavaScript classList.remove() – Remove Class Values from an Element
- JavaScript classList.contains() – Check Class Values of an Element
- JavaScript toggleAttribute() Function – Toggling a Boolean Attribute on an Element