Manipulating the DOM
Now that you have learned the basics of using Cheerio and have gained some experience with loading and traversing documents, it's time to dive deeper into manipulating elements. Whether you want to modify element attributes and properties, add and remove classes, modify text and HTML content, or insert and remove elements, Cheerio provides a range of methods to help you do so.
In this guide, we will focus specifically on manipulating elements within a document using Cheerio. We will cover methods for modifying element attributes and properties, adding and removing classes, modifying text and HTML content, inserting and removing elements, and handling errors and debugging. By the end of this guide, you will have a good understanding of how to use these methods to manipulate elements within a document using Cheerio.
Modifying Element Attributes and Properties
To modify the attributes and properties of a single element, you can use the
attr() and
prop() methods, respectively. Both methods
take a key and a value as arguments, and allow you to get and set the attribute
or property. When setting, they apply to all elements in the selection; when
getting, they return a single value corresponding to the first element in the
selection.
// Set the 'src' attribute of an image element
$('img').attr('src', 'https://example.com/image.jpg');
// Set the 'checked' property of a checkbox element
$('input[type="checkbox"]').prop('checked', true);
// Get the 'href' attribute of a link element
const href = $('a').attr('href');
// Get the 'disabled' property of a button element
const isDisabled = $('button').prop('disabled');
prop() is not limited to simple values like strings and booleans. You can also
use it to get complex properties like the style object, or to resolve href
or src URLs of supported elements. You can also use it to get the tagName,
innerHTML, outerHTML, textContent, and innerText properties of a single
element.
// Get the `style` object of an element
const style = $('div').prop('style');
// Get the resolved `src` URL of an image element
$('img').prop('src');
// Get the outerHTML of an element
const outerHTML = $('div').prop('outerHTML');
// Get the innerText of an element
const innerText = $('div').prop('innerText');
Adding and Removing Classes
To add or remove classes from an element, you can use the
addClass(),
removeClass(), and
toggleClass() methods. All three
methods take a class name or a space-separated list of class names as an
argument. They modify all elements in the selection.
// Add a class to an element
$('div').addClass('new-class');
// Add multiple classes to an element
$('div').addClass('new-class another-class');
// Remove a class from an element
$('div').removeClass('old-class');
// Remove multiple classes from an element
$('div').removeClass('old-class another-class');
// Toggle a class on an element (add if it doesn't exist, remove if it does)
$('div').toggleClass('active');
Modifying the Text Content of an Element
To query or modify the text content of an element, you can use the
text() method. Given a string as an
argument, it sets the text content of every element in the selection to the
given string. Without arguments, it returns the text content of every element
(including its descendants) in the selection, concatenated together.
// Set the text content of an element
$('h1').text('Hello, World!');
// Get the text content of an element
const text = $('p').text();
text() returns the textContent of all passed elements. The result will
include the contents of <script> and <style> elements. To avoid this, use
.prop('innerText') instead.
Modifying the HTML Content of an Element
To query or modify the HTML content of an element, you can use the
html() method. Given an HTML string as an
argument, it sets the inner HTML of every element in the selection to the given
string. Without arguments, it returns the inner HTML of the first element in
the selection.
// Set the inner HTML of an element
$('div').html('<p>Hello, World!</p>');
// Get the inner HTML of an element
const html = $('div').html();
Inserting New Elements
To insert new elements into a document, you can use the
append(),
prepend(),
before(), and
after() methods. These modify every element
in the selection.
// Append an element to the end of a parent element
$('ul').append('<li>Item</li>');
// Prepend an element to the beginning of a parent element
$('ul').prepend('<li>Item</li>');
// Insert an element before a target element
$('li').before('<li>Item</li>');
// Insert an element after a target element
$('li').after('<li>Item</li>');
The insertAfter() and
insertBefore() methods allow you to
insert an element before or after a target element, respectively. Both methods
take a string or a Cheerio object as an argument and insert the given element
before or after the target element.
const $ = require('cheerio');
// Insert an element after a target element
$('<p>Inserted element</p>').insertAfter('h1');
// Insert an element before a target element
$('<p>Inserted element</p>').insertBefore('h1');
The prependTo() and
appendTo() methods allow you to prepend
or append an element to a parent element, respectively. Both methods take a
string or a Cheerio object as an argument and insert the element at the
beginning or end of the given parent element.
const $ = require('cheerio');
// Prepend an element to a parent element
$('<p>Inserted element</p>').prependTo('div');
// Append an element to a parent element
$('<p>Inserted element</p>').appendTo('div');
Wrapping and Unwrapping Elements
Sometimes you may want to wrap an element in another element, or remove the
element's parent element while keeping its children. To do this, you can use the
wrap(), wrapInner(), and unwrap() methods.
The wrap() method takes a string or a
Cheerio object as an argument and wraps the element in the given element.
// Wrap an element in a div
$('p').wrap('<div></div>');
The wrapInner() method works similar to
wrap(), but instead of wrapping the element itself, it wraps the element's inner
HTML in the given element.
// Wrap the inner HTML of an element in a div
$('div').wrapInner('<div></div>');
The unwrap() method removes the element's
parent element, while keeping the element and its children.
// Unwrap an element
$('p').unwrap();
Replacing Elements
To replace an element with another element, you can use the
replaceWith() method. It takes a
string or a Cheerio object as an argument and replaces each element in the
selection with the given element.
// Replace an element with another element
$('li').replaceWith('<li>Item</li>');
Note that the replaceWith() method removes the element from the document and
replaces it with the given element or HTML string. If you want to keep the
element and modify its contents, you can use the html() or text() methods
instead.
Removing Elements
To remove an element from a document, you can use the
remove() method. It removes each element
in the selection, and all of their children, from the document.
// Remove an element from the document
$('li').remove();
Alternatively, you can remove the children of an element from the document,
without removing the element itself, using the
empty() method. It removes the children
(but not text nodes or comments) of each element in the selection from the
document.
// Remove an element's children from the document
$('li').empty();
Conclusion
We learned how to manipulate elements within a document using Cheerio. We can modify element attributes and properties, add and remove classes, modify text and HTML content, insert and remove elements, and handle errors and debug our code. With these tools, you can easily manipulate a document to suit your needs.