HTML to Image Converter Overview

The HTML to Image converter allows you to quickly create screenshots of HTML documents. The class representing the HTML to Image converter is HiQPdf.NextHtmlToImage.

The most important options of the HTML to Image Converter are described in detail in the topics below.

Convert Methods

The following methods of the HiQPdf.Next.HtmlToImage class can be called to convert HTML documents to images.

Methods to convert an HTML document from a given URL to an image:

Methods to convert an HTML string to an image:

Asynchronous HTML to Image Methods

There are also asynchronous variants of these methods that follow the Task-based Asynchronous Pattern (TAP) in .NET, allowing HTML to image conversion to run in parallel using async and await. These methods share the same names as their synchronous counterparts and include the "Async" suffix. They also accept an optional System.ThreadingCancellationToken parameter that can be used to cancel the conversion operation where applicable.

Below is a detailed description of the most important options of the HTML to Image Converter.

Browser Width

The BrowserWidth property of the HiQPdf.Next.HtmlToImage class represents the width of the web browser window when viewing a web page. The default value is 1024 pixels.

Browser Height

The BrowserHeight property of the HiQPdf.Next.HtmlToImage class represents the height of the web browser window when viewing a web page. By default, the HTML to Image Converter captures only the content in the viewport defined by the BrowserWidth and BrowserHeight properties, but it is possible to convert the entire HTML page by setting the property described below. The default browser height is 2048 pixels.

Convert Entire Page

The ConvertEntirePage property controls whether the entire HTML page content is captured in the screenshot or only the area specified by the BrowserHeight property. The captured content is limited by the MaxBrowserHeight property. By default, this property is set to true. Additionally, it is possible to choose between the browser’s internal mechanism and a custom algorithm for capturing the entire page using the HtmlToImageConvertEntirePageMode property. By default, the Browser mode is used by the converter.

Wait Before Convert

The WaitBeforeConvert property of the HiQPdf.Next.HtmlToImage class introduces an additional delay, in seconds, before starting the conversion, allowing more time for JavaScript to update the web page.

Load HTML Timeout

The HtmlLoadedTimeout property of the HiQPdf.Next.HtmlToImage class controls the maximum time, in seconds, to wait for the HTML document to load. The default value is 120 seconds. An exception is thrown if the HTML document cannot be loaded within the specified timeout.

HTML to Image Converter Demo

In this demo, you can convert a URL or HTML code to an image. You can select the image format (PNG, JPG, WEBP), the browser width and height in pixels, choose whether to capture the entire HTML page, set the wait-before-conversion delay and configure the HTML load timeout.

HTML to Image Demo Source Code

C#
using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Mvc;
using HiQPdf_Next_AspNetDemo.Models;

using HiQPdf.Next;

namespace HiQPdf_Next_AspNetDemo.Controllers
{
    public class ConvertHtmlToImageController : Controller
    {
        // GET: ConvertHtmlToImage
        public ActionResult Index()
        {
            var model = new ConvertHtmlToImageViewModel();
            return View(model);
        }

        [HttpPost]
        public ActionResult ConvertToImage(ConvertHtmlToImageViewModel model)
        {
            if (!ModelState.IsValid)
            {
                var errorMessage = ModelStateHelper.GetModelErrors(ModelState);
                throw new ValidationException(errorMessage);
            }

            // Replace the demo serial number with the serial number received upon purchase
            // to run the converter in licensed mode
            Licensing.SerialNumber = "YCgJMTAE-BiwJAhIB-EhlWTlBA-UEBRQFBA-U1FOUVJO-WVlZWQ==";

            // create the HTML to Image converter
            HtmlToImage htmlToImageConverter = new HtmlToImage();

            // set browser width
            htmlToImageConverter.BrowserWidth = model.BrowserWidth;

            // set browser height if specified, otherwise use the default
            if (model.BrowserHeight.HasValue)
                htmlToImageConverter.BrowserHeight = model.BrowserHeight.Value;

            // enable the conversion of the entire page, not only the viewport defined by BrowserWidth and BrowserHeight
            htmlToImageConverter.ConvertEntirePage = model.ConvertEntirePage;

            // set the loading mode used to convert the entire page content
            htmlToImageConverter.ConvertEntirePageMode = model.ConvertEntirePageMode == "Browser" ?
                ConvertEntirePageMode.Browser : ConvertEntirePageMode.Custom;

            // optionally auto resize HTML viewer height at the HTML content size determined after the initial loading
            htmlToImageConverter.AutoResizeBrowserHeight = model.AutoResizeViewerHeight;

            // set wait time before starting conversion
            htmlToImageConverter.WaitBeforeConvert = model.WaitTime;

            // set HTML Load timeout
            htmlToImageConverter.HtmlLoadedTimeout = model.LoadHtmlTimeout;

            // the image buffer in the selected image format
            byte[] imageBuffer = null;
            ImageType imageType = GetSelectedImageFormat(model.ImageFormat);

            if (model.UrlOrHtmlCode == "ConvertUrl")
            {
                // convert URL
                string url = model.Url;

                imageBuffer = htmlToImageConverter.ConvertUrlToMemory(url, imageType);
            }
            else
            {
                // convert HTML code
                string htmlCode = model.HtmlCode;
                string baseUrl = model.BaseUrl;

                imageBuffer = htmlToImageConverter.ConvertHtmlToMemory(htmlCode, baseUrl, imageType);
            }

            // inform the browser about the binary data format
            string imageFileExtension = GetImageFileExtension(imageType);
            string imageFileName = string.Format("HtmlToImage.{0}", imageFileExtension);

            string mimeType = GetImageMimeType(imageType);
            FileResult fileResult = new FileContentResult(imageBuffer, "image/" + mimeType);
            fileResult.FileDownloadName = imageFileName;

            return fileResult;
        }

        private string GetImageMimeType(ImageType imageType)
        {
            switch (imageType)
            {
                case ImageType.Png:
                    return "png";
                case ImageType.Jpeg:
                    return "jpeg";
                case ImageType.Webp:
                    return "webp";
                default:
                    return "png";
            }
        }

        private string GetImageFileExtension(ImageType imageType)
        {
            switch (imageType)
            {
                case ImageType.Png:
                    return "png";
                case ImageType.Jpeg:
                    return "jpg";
                case ImageType.Webp:
                    return "webp";
                default:
                    return "png";
            }
        }

        private ImageType GetSelectedImageFormat(string imageFormat)
        {
            switch (imageFormat)
            {
                case "PNG":
                    return ImageType.Png;
                case "JPG":
                    return ImageType.Jpeg;
                case "WEBP":
                    return ImageType.Webp;
                default:
                    return ImageType.Png;
            }
        }
    }
}

See Also