Migrate from html2canvas to SnapDOM

What changes, in one block

Install @zumer/snapdom and replace the call. The canvas consumer is the closest match to what you have:

// Before
import html2canvas from 'html2canvas'
const canvas = await html2canvas(el, { scale: 2, useCORS: true })
const dataURL = canvas.toDataURL('image/png')

// After
import { snapdom } from '@zumer/snapdom'
const canvas = await snapdom.toCanvas(el, { dpr: 2 })
const dataURL = canvas.toDataURL('image/png')

If the canvas only existed to get a PNG, skip it: const img = await snapdom.toPng(el) returns an HTMLImageElement whose src is the data URL.

The return value is a capture, not a canvas

html2canvas resolves to a canvas and leaves the encoding to you. snapdom(el) resolves to a capture object that already holds the frozen SVG and exports it on demand, so one capture can feed several outputs without re-walking the DOM:

const capture = await snapdom(el, { dpr: 2 })

const img    = await capture.toPng()                        // HTMLImageElement
const canvas = await capture.toCanvas()                     // HTMLCanvasElement
const blob   = await capture.toBlob({ format: 'png' })      // Blob for upload
await capture.download({ format: 'jpg', filename: 'card' }) // file to disk

The shortcuts snapdom.toPng, snapdom.toJpg, snapdom.toWebp, snapdom.toSvg, snapdom.toCanvas and snapdom.toBlob do the capture and one export in a single call, which is what most html2canvas call sites want.

Option by option

Every html2canvas option you may have set, and what to write instead. Options not listed here (removeContainer, windowWidth, windowHeight, scrollX, scrollY, letterRendering) have no equivalent because SnapDOM captures the element's own box and never scrolls the page.

Replacing onclone

The onclone callback edited the cloned document before html2canvas drew it. The same work goes in a plugin hook, inline for a one-off or shared through snapdom.use() when several call sites need it:

const img = await snapdom.toPng(el, {
  plugins: [{
    name: 'strip-controls',
    afterClone(ctx) {
      ctx.clone.querySelectorAll('.no-capture, button').forEach(n => n.remove())
    }
  }]
})

Two differences from onclone: the hook receives the clone of the element, not a whole document, and beforeClone exists for changes to the live DOM that you undo in afterClone. The plugin API lists every hook.

Fonts come along

html2canvas drew text with whatever fonts the page had loaded. SnapDOM renders the clone inside an SVG image, which is an isolated document, so it embeds the web fonts the element uses on its own (embedFonts: 'auto'). Nothing to configure for Google Fonts or self-hosted fonts. Two cases need a word:

• Icon fonts are matched by name; add yours with iconFonts if glyphs come out as boxes.
• A font stylesheet served without CORS headers cannot be read from any site. Check the console for a [snapDOM] Network/CORS issue line before suspecting the capture.

What renders now that did not before

html2canvas reimplements CSS painting, so its own documentation lists what it skips: box-shadow, filter, mix-blend-mode, object-fit, border-image, background-blend-mode, box-decoration-break, writing-mode, repeating-linear-gradient() and zoom. SnapDOM lets the browser paint the styled clone, so those render as they do on screen, along with pseudo-elements, open shadow roots, typed form values and same-origin iframes.

That is why a migrated capture should be checked against the live element, not against the old html2canvas output: differences are usually things html2canvas was leaving out. The head to head page runs both libraries on the same element so you can see it.

Four mistakes right after switching

1. Keeping scale: 2. You get a capture at twice the CSS size. Use dpr: 2 for sharpness; use scale only when you want a bigger image.
2. Expecting a canvas from snapdom(el). It returns a capture object. Call snapdom.toCanvas(el), or capture.toCanvas().
3. toBlob() with no format. The default export is SVG, so the blob is an SVG blob. Pass { format: 'png' } when the upload expects a PNG.
4. Importing it on the server. SnapDOM runs in the browser only. In Next.js, the dynamic import with ssr: false has to live in a client component, as the Next.js guide shows.