@chandq/html-diff

Framework-agnostic HTML visual diff renderer for rich text, inline markup, images, and editor previews.

It accepts two HTML strings and returns a mounted diff view, a DocumentFragment, or serialized diff HTML. It works with Vue, React, Svelte, Angular, or plain DOM because the input is just HTML strings.

Highlights

• Accurate inline text diff for mixed Chinese, English, numbers, punctuation, and rich text markup
• HTML-aware node matching to reduce cascading false positives in lists and repeated blocks
• Built-in image add, remove, and replace rendering
• shadow, scoped, and none render modes for different embedding needs
• Split ESM and CJS outputs for direct subpath imports and better tree-shaking

Install

npm install @chandq/html-diff

Usage

import { renderHtmlDiff } from '@chandq/html-diff';

renderHtmlDiff({
  container: document.getElementById('diff-root')!,
  oldHtml: '<p>Hello <strong>world</strong></p>',
  newHtml: '<p>Hello brave <strong>world</strong></p>',
  mode: 'shadow'
});

On-Demand Imports

import { renderHtmlDiff } from '@chandq/html-diff/render';
import { parseHtmlToVNode } from '@chandq/html-diff/parse';
import { diffChildren } from '@chandq/html-diff/diff';

API

renderHtmlDiff(options)

Mounts the diff into a container and returns the rendered root, fragment, stats, and destroy().

Option	Type	Default
container	HTMLElement	required
oldHtml	string	required
newHtml	string	required
mode	'shadow' | 'scoped' | 'none'	'shadow'
ignoreWhitespace	boolean	true
theme	DiffTheme	GitHub-style add/remove colors, page padding

Other Exports

Function	Returns
diffHtml(oldHtml, newHtml, options?)	{ fragment, stats }
createHtmlDiffFragment(oldHtml, newHtml, options?)	DocumentFragment
createHtmlDiffHtml(oldHtml, newHtml, options?)	serialized diff HTML
parseHtmlToVNode(html, options?)	internal VNode tree

Node Matching

When a stable identity is available, the diff prefers data-key, id, or key to align matching nodes. name is intentionally not used as a node identity because it is often semantic or form-related rather than a reliable structural key.

Development

npm install
npm run dev
npm run test:unit
npm run typecheck
npm run build