Fine-Tune HTML, SVG, MHTML, and EPUB Rendering in Java

Use the low-level rendering API when a direct Converter.convertHTML() call does not provide enough control. Combine an HTMLDocument with renderTo() or a format-specific renderer and output device to control PDF, XPS, DOCX, or image output.

Aspose.HTML for Java provides two related approaches to format conversion. The static Converter methods cover common conversion workflows. The renderTo() method and format-specific renderers expose the lower-level rendering pipeline.

Converter API vs. Rendering API

Approach	Use it when
Converter.convertHTML() and other Converter methods	You need a concise conversion workflow with default or customized save options.
Document.renderTo(device)	You have one loaded document and want to send it directly to a configured output device.
Renderer.render(device, sources)	You need to process multiple source documents together or control the rendering timeout.

For device-based output such as PDF, XPS, DOCX, and images, either approach can be used. The Converter class also covers conversions that are not represented by rendering devices. The main difference is the level at which your application controls the operation.

Render HTML to PDF with a Rendering Device

A rendering device implements the IDevice interface and receives drawing commands generated from the source document. Aspose.HTML for Java provides devices and matching option classes for the principal output types:

Output	Device	Rendering options
PDF	PdfDevice	PdfRenderingOptions
XPS	XpsDevice	XpsRenderingOptions
DOCX	DocDevice	DocRenderingOptions
Images	ImageDevice	ImageRenderingOptions

To render a document to an output device:

1. Load the source document.
2. Create a device for the required output format and specify its output destination.
3. Call renderTo(device) on the document.

The following example initializes an HTMLDocument from an HTML string and renders it to output.pdf through PdfDevice with default rendering options.

// Render HTML to PDF using Java

// Prepare HTML code
String code = "<span>Hello, World!!</span>";

// Initialize an HTML document from HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of the PdfDevice class and specify the output file to render
    try (PdfDevice device = new PdfDevice("output.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }
}

Configure Rendering Options

Rendering options are passed to an output device and control the layout and format-specific behavior. General settings include page setup, resolution, CSS media type, and background color. PDF and image devices also expose settings specific to their output formats.

Set the PDF Page Size

To apply custom PDF page dimensions:

1. Create PdfRenderingOptions.
2. Configure a Page through PageSetup with the required dimensions.
3. Pass the options and output path to PdfDevice.
4. Render the document to the configured device.

The next example sets the PDF page to 5 × 2 inches and renders an inline HTML document to output.pdf.

// Render HTML to PDF in Java with custom page size

// Prepare HTML code
String code = "<span>Hello, World!!</span>";

// Initialize a HTML document from the HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of PdfRenderingOptions and set a custom page-size
    PdfRenderingOptions options = new PdfRenderingOptions();
    PageSetup pageSetup = new PageSetup();
    Page anyPage = new Page();
    anyPage.setSize(
            new Size(
                    Length.fromInches(5),
                    Length.fromInches(2)
            )
    );
    pageSetup.setAnyPage(anyPage);
    options.setPageSetup(pageSetup);

    // Create a PDF Device and specify options and output file
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }
}

General Rendering Options

The RenderingOptions base class provides settings shared by output devices. CssOptions controls how CSS media queries are resolved during rendering.

Set Horizontal and Vertical Resolution

Horizontal and vertical resolution values are measured in pixels per inch. For PDF output, these settings affect internal raster images, including images used while processing filters; they do not simply increase the quality of vector text. For image output, resolution also affects the raster output.

The following example renders the same HTML document to two PDF files using horizontal and vertical resolution values of 50 dpi and 300 dpi.

// Render HTML to PDF with custom resolution using Java

// Prepare HTML code and save it to a file
String code = "< style >\n" +
        "                p\n" +
        "        {\n" +
        "            background:\n" +
        "            blue;\n" +
        "        }\n" +
        "        @media(min - resolution:300dpi)\n" +
        "        {\n" +
        "            p\n" +
        "            {\n" +
        "                /* high resolution screen color */\n" +
        "                background:\n" +
        "                green\n" +
        "            }\n" +
        "        }\n" +
        "    </style >\n" +
        "    <p > Hello World !! </p >\n";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
    fileWriter.write(code);
}

// Create an instance of the HTMLDocument class
try (HTMLDocument document = new HTMLDocument("document.html")) {

    // Create options for low-resolution screens
    PdfRenderingOptions options = new PdfRenderingOptions();
    options.setHorizontalResolution(Resolution.to_Resolution(50d));
    options.setVerticalResolution(Resolution.to_Resolution(50d));

    // Create an instance of the PdfDevice
    try (PdfDevice device = new PdfDevice(options, "output_resolution_50.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }

    // Create options for high-resolution screens
    options = new PdfRenderingOptions();
    options.setHorizontalResolution(Resolution.to_Resolution(300d));
    options.setVerticalResolution(Resolution.to_Resolution(300d));

    // Create an instance of PDF device
    try (PdfDevice device = new PdfDevice(options, "output_resolution_300.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }
}

Select the CSS Media Type

CSS media types let a document apply different style rules for screen and print output. They can be assigned to a linked style sheet or used in an @media rule:

Linked style sheet

<link rel="stylesheet" media="print" href="style.css">

Inline style sheet

<style>
@media print {
  body { color: #000000; }
}
</style>

Set the media type through options.getCss().setMediaType(). The example below selects MediaType.Screen before rendering HTML to PDF.

// Render HTML to PDF with custom MediaType settings with Java

// Prepare HTML code
String code = "<span>Hello, World!!</span>";

// Initialize an HTML document from the HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of the PdfRenderingOptions class
    PdfRenderingOptions options = new PdfRenderingOptions();
    // Set the 'screen' media-type
    options.getCss().setMediaType(MediaType.Screen);

    // Create a PDF Device and specify options and output file
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }
}

The default CSS media type is MediaType.Print. Use MediaType.Screen when the output should apply screen-specific media queries instead of print-specific rules.

Set the Output Background Color

The background color setting fills each output page behind the document content. Its default value is transparent. Set an explicit color when the target format or design requires a predictable page background.

The following example sets PdfRenderingOptions background color to cyan and renders document.html to output.pdf.

// Render HTML to PDF with custom background color using Java

// Prepare HTML code and save it to a file
String code = "<p>Hello, World!!</p>";
try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
    fileWriter.write(code);
}

// Create an instance of the HTMLDocument class
try (HTMLDocument document = new HTMLDocument("document.html")) {

    // Initialize options with 'cyan' as a background-color
    PdfRenderingOptions options = new PdfRenderingOptions();
    options.setBackgroundColor(Color.getCyan());

    // Create an instance of the PdfDevice class
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }
}

Adjust the Page Size to Wide Content

PageSetup controls page dimensions, margins, page-specific configurations, and the interaction between conversion settings and CSS @page rules. When document content is wider than the configured page, setAdjustToWidestPage(true) can expand the page width instead of clipping the content.

The adjustment is applied only when the widest content exceeds the configured width, and the adjusted size is used for all output pages. This option can increase processing time.

The next example starts with a 500 × 200 pixel page and adjusts the PDF page width to fit the widest HTML content.

// Render HTML to PDF and adjust to the widest page with Java

// Prepare HTML code
String code = "    <style>\n" +
        "        div {\n" +
        "            page - break -after:always;\n" +
        "        }\n" +
        "    </style >\n" +
        "    <div style = 'border: 1px solid red; width: 400px' > First Page</div >\n" +
        "    <div style = 'border: 1px solid red; width: 600px' > Second Page</div >\n";
// Initialize an HTML document from HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of the PdfRenderingOptions class and set a custom page-size
    PdfRenderingOptions options = new PdfRenderingOptions();
    options.getPageSetup().setAnyPage(new Page(new Size(500, 200)));

    // Enable auto-adjusting for the page size
    options.getPageSetup().setAdjustToWidestPage(true);

    // Create an instance of the PdfDevice class and specify options and output file
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }
}

Configure PDF Rendering Options

PdfRenderingOptions includes the general rendering settings and PDF-specific properties for document information, encryption, form-field behavior, and JPEG compression quality.

The following example configures user and owner passwords, permits printing, selects the RC4_128 encryption algorithm, and renders the HTML document to output.pdf.

// Render HTML to PDF with password protection using Java

// Prepare HTML code
String code = "<div>Hello, World!!</div>";

// Initialize an HTML document from the HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create the instance of the PdfRenderingOptions class
    PdfRenderingOptions options = new PdfRenderingOptions();

    // Set file permissions
    options.setEncryption(
            new PdfEncryptionInfo(
                    "user_pwd",
                    "owner_pwd",
                    PdfPermissions.PrintDocument,
                    PdfEncryptionAlgorithm.RC4_128
            )
    );

    // Create a PDF Device and specify options and output file
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

        // Render HTML to PDF
        document.renderTo(device);
    }
}

Configure Image Rendering Options

ImageRenderingOptions controls the raster image format, resolution, antialiasing, compression, background, and page setup.

The next example selects JPEG output, disables smoothing, sets horizontal and vertical resolution to 75 dpi, and renders the inline HTML document to output.jpg.

// Render HTML to JPG with custom resolution and antialiasing settings with Java

// Prepare HTML code
String code = "<div>Hello, World!!</div>";

// Initialize an instance of the HTMLDocument class based on prepared code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of the ImageRenderingOptions class
    ImageRenderingOptions options = new ImageRenderingOptions();
    options.setFormat(ImageFormat.Jpeg);

    // Disable smoothing mode
    options.setSmoothingMode(SmoothingMode.None);

    // Set the image resolution as 75 dpi
    options.setVerticalResolution(Resolution.fromDotsPerInch(75));
    options.setHorizontalResolution(Resolution.fromDotsPerInch(75));

    // Create an instance of the ImageDevice class
    try (ImageDevice device = new ImageDevice(options, "output.jpg")) {

        // Render HTML to Image
        document.renderTo(device);
    }
}

Render Multiple Documents to One Output

The renderTo(device) method sends one loaded document to a device. Format-specific renderers can accept multiple sources:

• HtmlRenderer processes HTMLDocument objects.
• SvgRenderer processes SVG documents.
• MhtmlRenderer processes MHTML sources.
• EpubRenderer processes EPUB sources.

The following example passes three HTMLDocument objects to HtmlRenderer and writes their rendered content to one output.pdf file. It combines the output in a PDF; it does not merge the source DOM trees into a new HTML document.

// Merge HTML to PDF using Java

// Prepare HTML code
String code1 = "<br><span style='color: green'>Hello, World!!</span>";
String code2 = "<br><span style='color: blue'>Hello, World!!</span>";
String code3 = "<br><span style='color: red'>Hello, World!!</span>";

// Create three HTML documents to merge later
HTMLDocument document1 = new HTMLDocument(code1, ".");
HTMLDocument document2 = new HTMLDocument(code2, ".");
HTMLDocument document3 = new HTMLDocument(code3, ".");

// Create an instance of HTML Renderer
HtmlRenderer renderer = new HtmlRenderer();

// Create an instance of the PdfDevice class
try (PdfDevice device = new PdfDevice("output.pdf")) {

    // Merge all HTML documents to PDF
    renderer.render(device, new HTMLDocument[]{document1, document2, document3});
}

Set a Rendering Timeout

Renderer overloads with a timeout limit how long the rendering pipeline waits for conditions such as resource loading, active timers, and animation tasks. For the integer overload used by the example, the timeout value is measured in milliseconds; -1 represents an indefinite wait.

The example passes 5 as the timeout value while rendering an HTMLDocument to output.pdf.

// Render HTML to PDF with timeout settings using Java

// Prepare HTML code
String code = "< script >\n" +
        "        var count = 0;\n" +
        "        setInterval(function()\n" +
        "        {\n" +
        "            var element = document.createElement('div');\n" +
        "            var message = (++count) + '. ' + 'Hello, World!!';\n" +
        "            var text = document.createTextNode(message);\n" +
        "            element.appendChild(text);\n" +
        "            document.body.appendChild(element);\n" +
        "        },1000);\n" +
        "</script >\n";

// Initialize an HTML document based on prepared HTML code
try (HTMLDocument document = new HTMLDocument(code, ".");) {

    // Create an instance of HTML Renderer
    HtmlRenderer renderer = new HtmlRenderer();

    // Create an instance of the PdfDevice class
    try (PdfDevice device = new PdfDevice("output.pdf")) {

        // Render HTML to PDF
        renderer.render(device, 5, document);
    }
}

Download complete Java examples and data files from GitHub.

Related Conversion Guides

• HTML Converter – use the high-level API for common HTML conversion workflows.
• SVG Converter – convert SVG to document and image formats.
• MHTML Converter – convert MHTML web archives with format-specific options.
• EPUB Converter – convert EPUB to PDF, XPS, DOCX, and images.

Other Platforms

• Fine-Tuning Converters in .NET
• Fine-Tuning Converters in Python via .NET

Frequently Asked Questions

When should I use Converter instead of a rendering device?

Use the Converter class for concise conversions based on save options. Use renderTo() or a format-specific renderer when you need direct control over a device, multiple input documents, or a rendering timeout.

Does HtmlRenderer merge several HTML files into one HTML document?

No. HtmlRenderer can send several HTMLDocument objects to one output device, such as a PDF device. It does not combine their DOM trees or save a new merged HTML document.

Summary

The low-level rendering API complements the Converter class. Rendering devices define the destination, rendering options control output behavior, and format-specific renderers support multi-source and timeout scenarios.

Try Online Conversion Tools

Use the free online HTML applications for quick manual conversions and checks. Use Aspose.HTML for Java rendering APIs when output settings must be controlled programmatically.