Kebechet.Blazor.HtmlToImage 1.11.13

Blazor.HtmlToImage

Blazor wrapper for html-to-image: capture any DOM element as PNG, JPEG, SVG, raw bytes or pixel data.

The html-to-image build is vendored and pinned inside the package and injected by a Blazor JS initializer, so there is no npm step, no CDN, and no <script> tag to add. That matters beyond convenience: a CDN reference breaks a MAUI or hybrid app offline, lets a shipped store build change behaviour without a release, and counts as downloading executable code at runtime under App Store guideline 2.5.2.

Live storybook - interactive stories for every feature.

Installation

dotnet add package Kebechet.Blazor.HtmlToImage

Register the service:

using Kebechet.Blazor.HtmlToImage;

builder.Services.AddHtmlToImage();

Usage

@inject IHtmlToImageService _htmlToImage

<div @ref="_poster" class="poster">
    <h1>Bench press - 120 kg x 5</h1>
    <button class="capture-ignore" @onclick="Capture">Share</button>
</div>

@code {
    private ElementReference _poster;

    private async Task Capture()
    {
        var png = await _htmlToImage.ToPngBytesAsync(_poster, new HtmlToImageOptions
        {
            PixelRatio = 3,
            BackgroundColor = "#0b0b0b",
            ExcludeCssClasses = ["capture-ignore"],
        });

        // upload, save, or hand to a native share sheet
    }
}

Every method also takes a DOM id instead of an ElementReference:

var dataUrl = await _htmlToImage.ToPngAsync("poster");

Data URL vs. bytes

ToPngAsync returns a data:image/png;base64,... string, matching upstream. ToPngBytesAsync returns byte[] and streams the image over JS interop instead of marshalling base64. Prefer the bytes overload for anything you intend to upload or save: a poster at PixelRatio = 3 is several megabytes, and a data URL carries it as one JSON string - roughly 33% larger and fully buffered on both sides.

Excluding elements from the capture

Upstream's filter is a JavaScript predicate, which cannot cross JS interop as a delegate without a round-trip per DOM node. It is modelled instead as two declarative options that the interop layer compiles into a single filter:

new HtmlToImageOptions
{
    ExcludeCssClasses = ["capture-ignore", "debug-overlay"],
    ExcludeSelector = "[data-private]",
}

Excluding a node excludes its whole subtree, matching upstream semantics.

Repeated captures of the same subtree

Font resolution dominates the cost of a capture that uses web fonts. Resolve once and reuse:

var fontCss = await _htmlToImage.GetFontEmbedCssAsync(_poster);

foreach (var frame in frames)
{
    var png = await _htmlToImage.ToPngBytesAsync(_poster, new HtmlToImageOptions
    {
        FontEmbedCss = fontCss,
    });
}

Coverage vs. html-to-image 1.11.13

Complete. Every upstream entry point and every option is reachable.

Entry points: toPng, toJpeg, toSvg, toPixelData, getFontEmbedCSS and toCanvas map to ToPngAsync, ToJpegAsync, ToSvgAsync, ToPixelDataAsync, GetFontEmbedCssAsync and ToCanvasAsync. toBlob's role is served by ToPngBytesAsync / ToJpegBytesAsync, which route through toCanvas to work around an upstream bug - see the deviation note below.

Options: all 20, though three are reshaped because their upstream form is a JavaScript value that cannot cross interop as data:

⚠️ ImageLoadFailed and ImagePlaceholder are alternatives, not complements. Upstream resolves a failed URL to the placeholder before assigning it to the cloned image, so with a placeholder set the clone loads successfully and the error never fires. Pick reporting or papering over. Pinned by ImageLoadFailed_ReportsAnImageThatCouldNotResolve.

Coverage is measured against html-to-image's published type definitions - lib/index.d.ts for entry points, lib/types.d.ts for the Options interface - excluding underscore-prefixed internals. Re-checked on every upstream version bump.

One deliberate deviation from upstream

⚠️ ToJpegBytesAsync does not call upstream's toBlob.

Upstream's toBlob forwards its options to toCanvas but then calls its own internal canvasToBlob(canvas) with no options at all, so type and quality are silently dropped - asking it for a JPEG returns a PNG at quality 1. This wrapper calls toCanvas and does the canvas-to-blob step itself, which is what makes ToJpegBytesAsync return real JPEG bytes and Quality take effect. Pinned by the Capture_JpegStory_ReturnsBytesWithAJpegSignature browser test.

Captures stall in hidden tabs - by upstream design

⚠️ A capture started while the tab is hidden or fully occluded does not complete until the tab renders a frame again. Nothing errors and nothing times out - the Task just stays pending, then resolves when the tab becomes visible.

This is upstream's own resolution path, not wrapper behaviour: html-to-image's createImage resolves every capture inside img.decode().then(() => requestAnimationFrame(resolve)), and browsers do not fire requestAnimationFrame for hidden documents. The normal case - capturing in response to a user action in a visible tab - never sees this. It matters only if a capture races a tab switch, or if you drive the page from automation that keeps it backgrounded (CDP screenshots force a frame, which un-stalls it).

Vendored library provenance

The npm dist build is already minified - jsDelivr reports "skipped minification" for it - so it is vendored verbatim rather than re-minified, and the hash above verifies byte-for-byte against the tarball.

License

MIT. html-to-image is itself MIT licensed.