DOM Node to String Serializer

2.2.1 · maintenance · verified Sun Apr 19

dom-serialize is a JavaScript library designed to convert various types of DOM nodes into an HTML string representation. Unlike the standard `outerHTML` property, it provides robust serialization capabilities for a broader range of DOM entities, including DOM elements, text nodes, attribute nodes, comment nodes, documents, document fragments, doctypes, NodeLists, and arrays of nodes. The current stable version is 2.2.1, released approximately 10 years ago, suggesting a mature and stable, though not actively developed, state. A key differentiator is its extensible serialization logic through a custom 'serialize' event, allowing developers to intercept and override default serialization for specific nodes or even use a one-time serializer function. This provides fine-grained control over the output, making it suitable for scenarios requiring custom HTML generation or specific content filtering. It supports both browser and Node.js environments, though Node.js usage requires a virtual DOM implementation.

Common errors

```
ReferenceError: document is not defined
```
cause Attempting to create or manipulate DOM nodes (e.g., `document.createElement`, `document.createTextNode`) in a non-browser environment like Node.js without a virtual DOM.

fix Install and configure a virtual DOM library like `jsdom`. For example: `const { JSDOM } = require('jsdom'); const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>'); global.document = dom.window.document;`
```
TypeError: serialize is not a function
```
cause The `dom-serialize` library exports its main function as a default export. This error typically occurs when attempting to use named imports (`import { serialize } from 'dom-serialize';`) or incorrectly destructuring the `require` call.

fix For ES Modules, use `import serialize from 'dom-serialize';`. For CommonJS, use `const serialize = require('dom-serialize');` to correctly import the default function.

Warnings

gotcha Custom serialization via the 'serialize' event bubbles up the DOM tree. An event listener on a parent node can inadvertently intercept and override serialization for its children. Always check `event.serializeTarget` to ensure you're modifying the intended node's serialization.
Fix: When using the 'serialize' event, always check `event.serializeTarget` against the specific node you intend to customize, or use `event.stopPropagation()` if appropriate, to prevent unintended overrides.
gotcha The README example contains a typo when setting the custom serialization value: `event.detail.serialze = '…'` should be `event.detail.serialize = '…'`. Using the misspelled property will result in the custom serialization being ignored.
Fix: Correct the typo in `event.detail.serialze` to `event.detail.serialize` when providing custom serialization values.
gotcha When using `dom-serialize` in a Node.js environment, a global DOM implementation (like `document`) is not available by default. Direct DOM manipulation (e.g., `document.createElement`) will fail without a virtual DOM library.
Fix: In Node.js, use a library such as `jsdom` to set up a virtual DOM environment before creating or manipulating DOM nodes that `dom-serialize` will process.
maintenance The `dom-serialize` package has not seen active development or releases in approximately 10 years, with its latest version 2.2.1 published in November 2015. While stable, it may not receive updates for new DOM features, security vulnerabilities, or modern JavaScript syntax/module systems.
Fix: Assess the suitability of this library for new projects requiring active maintenance or modern browser/Node.js features. Consider alternatives like `@quatico/dom-serializer` or `dom-serializer` (from CheerioJS) if active development, ESM support, or specific features like Shadow DOM serialization are needed.

Install

npm install dom-serialize npm
yarn add dom-serialize yarn
pnpm add dom-serialize pnpm

Imports

serialize
wrong:
```
import { serialize } from 'dom-serialize';
```
correct:
```
import serialize from 'dom-serialize';
```
The library exports a default function. Named imports like `{ serialize }` will not work.
serialize
```
const serialize = require('dom-serialize');
```
This is the CommonJS `require` syntax, commonly used in Node.js environments. ES Modules can import CJS default exports using `import serialize from 'dom-serialize';`.

Quickstart

This quickstart demonstrates how to serialize various DOM nodes (text, elements) and implement custom serialization logic using both event listeners and one-time functions.

const serialize = require('dom-serialize');

// Example 1: Serializing a text node
let textNode = document.createTextNode('Hello & <World>!');
console.log('Text Node:', serialize(textNode));

// Example 2: Serializing a DOM element with nested content
let bodyElement = document.createElement('body');
let strongElement = document.createElement('strong');
strongElement.appendChild(document.createTextNode('This is strong text.'));
bodyElement.appendChild(strongElement);
console.log('DOM Element:', serialize(bodyElement));

// Example 3: Custom serialization using the 'serialize' event
bodyElement.firstChild.addEventListener('serialize', function (event) {
  // Override the serialization for the 'strong' tag
  event.detail.serialize = '[CUSTOM-STRONG]';
}, false);
console.log('Custom Event Serialization:', serialize(bodyElement));

// Example 4: One-time custom serializer function
const customSerializedOutput = serialize(bodyElement, function (event) {
  if (event.serializeTarget === bodyElement.firstChild) {
    // For the first child (the 'strong' tag), output an ellipsis
    event.detail.serialize = '...';
  } else if (event.serializeTarget !== bodyElement) {
    // Prevent serialization of any other child elements if present
    event.preventDefault();
  }
});
console.log('One-time Function Serialization:', customSerializedOutput);

view raw JSON →