React Html Capture

A modern React hook for capturing HTML nodes as images — with crop, watermark, auto-capture, and Shadow DOM support.
Lightweight, flexible, and perfect for exporting UI elements, receipts, charts, or custom components.

✨ Features

• 🚀 Capture Formats: PNG, JPEG, WebP, SVG
• ✂️ Crop / Region Capture: Capture only a part of the node
• 💧 Watermark: Add text watermark at top-left, bottom-right, or center
• 🌀 Auto-Capture: Automatically capture when DOM mutates
• 🪞 Shadow DOM Support: Works inside shadow roots
• 📏 Preserve Scroll Position: Snapshot & restore scroll positions
• ⚡ SSR Safe: Won’t break on server-side rendering
• ⏱️ Lifecycle Hooks: onBeforeCapture & onAfterCapture
• 📥 Download Helpers: Easy built-in download function

📦 Installation

npm install react-html-capture
# or
yarn add react-html-capture
# or
pnpm add react-html-capture

🛠️ Peer Dependencies

This library requires React 18+:

npm install react react-dom

🚀 Quick Start

import { useHtmlCapture, downloadDataUrl } from "react-html-capture";
import { useRef } from "react";

export function App() {
  const ref = useRef<HTMLDivElement>(null);
  const { capture, captureBlob, isLoading, error } = useHtmlCapture(ref);

  const handleCapture = async () => {
    const dataUrl = await capture({
      type: "png",
      watermark: { text: "My App", position: "bottom-right" },
    });
    downloadDataUrl(dataUrl, "snapshot.png");
  };

  return (
    <div>
      <div ref={ref} style={{ padding: 20, border: "1px solid #ccc" }}>
        Capture this content!
      </div>
      <button onClick={handleCapture} disabled={isLoading}>
        {isLoading ? "Capturing..." : "Capture"}
      </button>
      {error && <p style={{ color: "red" }}>{error.message}</p>}
    </div>
  );
}

⚙️ Options

Option	Type	Default	Description
type	"png" | "jpeg" | "svg" | "webp"	"png"	Output image format
quality	number	0.92	JPEG/WebP quality (0–1)
backgroundColor	string | null	null	Background color override
pixelRatio	number	1	Multiplier of devicePixelRatio
cacheBust	boolean	false	Cache-bust image URLs
auto	boolean	false	Enable auto-capture on DOM changes
debounce	number	300	Debounce time for auto-capture
region	{ x: number, y: number, width: number, height: number } | null	null	Crop region (partial capture)
watermark	{ text: string; position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center" } | null	null	Add watermark to captured image
preserveScroll	boolean	false	Keep scroll positions unchanged
onBefore	() => void | Promise<void>	undefined	Callback fired before capture starts
onAfter	(meta: { width: number; height: number; sizeBytes?: number }) => void	undefined	Callback fired after capture finishes
shadowDom	boolean	false	Capture inside shadow DOM

🎨 Examples

Basic Capture

const { capture } = useHtmlCapture(ref);
const dataUrl = await capture();

Auto-Capture

const { capture } = useHtmlCapture(ref, { auto: true, debounce: 500 });

Capture With Crop + Watermark

await capture({
  type: "png",
  region: { x: 20, y: 30, width: 300, height: 200 },
  watermark: {
    text: "Demo",
    position: "center",
    fontSize: 18,
    color: "rgba(255, 0, 0, 0.4)",
  },
});

Shadow DOM Support

capture({ shadowDom: true });

Download Helper

downloadDataUrl(dataUrl, "snapshot.png");

🌐 Browser Support

• 🌐 Modern browsers: Chrome, Firefox, Safari, Edge
• 🛡️ SSR safe: won't run on Node.js

🤝 Contributing

Contributions are welcome! Please submit a Pull Request or open an issue.

📖 Learn More

• html-to-image Documentation
• MDN: Canvas API
• MDN: Blob API

📄 License

MIT