How to Use transform: scale With iText pdfHTML

Short answer: iText pdfHTML provides partial support for the CSS transform property. You should not assume browser-equivalent support for every transform: scale(...) value, element type, transform origin, or pagination interaction. The maintained iText feature overview is based on pdfHTML 6.3.3 with iText Core 9.7.0 and directs developers to validate uncertain cases with the latest HTML Converter demo. Read the current feature matrix.

This guide shows a repeatable way to test scale(), build a minimal Java or .NET conversion, diagnose layout differences, and decide when to replace visual scaling with a more predictable layout technique.

1. What “partial support” means

In pdfHTML, the transform property is not a promise that a browser’s CSS engine and the PDF renderer will produce identical output. “Partial” means behavior can depend on the transform function, its arguments, the selected element, and surrounding layout. The documentation does not establish universal support for every form of scale(), nor does it define guaranteed transform-origin behavior.

Use the following interpretation when planning a document:

A simple scale may render, but its final position or occupied layout area may differ from a browser preview.
Scaling can interact with overflow, clipping, line wrapping, absolute positioning, tables, and page breaks.
A transform may change painted pixels without changing the space the layout engine reserves for the element.
Results can change between library releases, so record the exact pdfHTML and iText Core versions used in production.

pdfHTML 6.3.3 is an iText Core add-on for Java and .NET, released on 2026-07-08. The official tutorial describes a renderer-tree approach that maps HTML and CSS into iText objects, while warning that older tutorial material may not include newer features. Use the maintained feature page for current support claims.

2. Start with a minimal reproducible case

Reduce the problem to one element, one stylesheet, and one expected measurement. Avoid testing inside a complete application first: headers, fonts, tables, and page templates can hide the cause of a mismatch.

Validate scale with a minimal element, fixed page geometry, and measurable PDF output.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    @page { size: A4; margin: 24pt; }
    body { font-family: sans-serif; }
    .sample {
      width: 240px;
      height: 80px;
      background: #dbeafe;
      border: 2px solid #1d4ed8;
      transform: scale(0.75);
      transform-origin: top left;
    }
  </style>
</head>
<body>
  <h1>Scale test</h1>
  <div class="sample">Scaled element</div>
</body>
</html>

Define what “correct” means before converting. For example: the border should measure 180 CSS pixels after a 0.75 scale, its top-left corner should remain at the expected location, and the following paragraph should begin without overlap. Inspect the PDF at 100% zoom and, when possible, measure it with a PDF inspection tool.

3. Java conversion with pdfHTML

The following example uses the standard pdfHTML conversion entry point. Set the dependency versions to the versions approved for your project and keep iText Core and pdfHTML compatible.

import com.itextpdf.html2pdf.ConverterProperties;
import com.itextpdf.html2pdf.HtmlConverter;

import java.io.FileInputStream;
import java.io.FileOutputStream;

public class ScalePdf {
    public static void main(String[] args) throws Exception {
        ConverterProperties properties = new ConverterProperties();
        try (FileInputStream html = new FileInputStream("input.html");
             FileOutputStream pdf = new FileOutputStream("output.pdf")) {
            HtmlConverter.convertToPdf(html, pdf, properties);
        }
    }
}

For production documents, configure the base URI so relative stylesheets, images, and fonts resolve consistently.

ConverterProperties properties = new ConverterProperties()
    .setBaseUri("/srv/templates/invoice/");
HtmlConverter.convertToPdf("input.html", "output.pdf", properties);

If your HTML is a string, use a ByteArrayInputStream or the string overload available in your installed release. Keep the sample self-contained while investigating transforms; add external resources only after the basic case is understood.

4. .NET conversion with pdfHTML

The .NET API follows the same conversion model. This example reads an HTML file and writes a PDF.

using iText.Html2pdf;
using iText.Html2pdf.Resolver.Font;

var properties = new ConverterProperties();
properties.SetBaseUri("/srv/templates/invoice/");

using var input = File.OpenRead("input.html");
using var output = File.Create("output.pdf");
HtmlConverter.ConvertToPdf(input, output, properties);

Do not compare a browser screenshot with a PDF screenshot at arbitrary zoom levels. Compare physical dimensions, page coordinates, and the number of pages. A browser uses CSS pixels and a continuously scrolling viewport; a PDF has fixed page geometry and pagination rules.

5. Test the variables that commonly change the result

Scale value and syntax

Test one-dimensional and two-dimensional forms separately, such as scale(0.8) and scale(0.8, 0.6). The feature documentation does not guarantee that every argument form behaves identically, so treat each as a separate compatibility test.

Browser transforms and PDF pagination can produce different positions, clipping, and wrapping.

Transform origin

Try an explicit transform-origin only after the basic transform is understood. Record whether the element moves, clips, or leaves its original layout space. Because the reviewed documentation does not specify universal origin behavior, describe any successful pattern as version-specific.

Element types

Run separate cases for block elements, inline content, replaced elements such as images, table cells, and absolutely positioned elements. A result that works for a div does not prove that the same declaration works inside a table or on an image.

Pagination and overflow

Place the scaled element near the bottom of a page and inside a container with overflow. Check whether content is clipped, overlaps the next block, or moves to another page. PDF pagination can expose issues that are invisible in a browser viewport.

Units and resources

Keep dimensions explicit while testing. Use a known page size, fixed margins, and embedded fonts. Relative URLs, missing fonts, and automatic line wrapping can make a transform appear broken when the underlying issue is resource resolution or changed element dimensions.

6. A validation workflow you can repeat

Check versions. Record pdfHTML, iText Core, Java or .NET runtime, and operating system.
Create a minimal file. Include one transformed element and a visible border.
Convert with the smallest program. Avoid framework middleware and post-processing.
Use the current HTML Converter demo. iText recommends its Demo Lab for uncertain HTML/CSS behavior; it uses the latest pdfHTML release.
Compare measurable output. Check dimensions, coordinates, clipping, wrapping, and page count.
Add one complexity at a time. Introduce external CSS, images, tables, and page templates in separate revisions.
Freeze the result. Keep the HTML, CSS, input assets, library versions, and output PDF as a regression fixture.

The online demo is useful for feature discovery, but your deployed dependency is the authority for production output. A demo result does not prove that an older locked version supports the same behavior.

7. More predictable alternatives when scale is essential

The reviewed iText sources do not establish a universal substitute for transform: scale(). Test alternatives in the actual document context and label conclusions by version. Useful experiments include:

Set the desired width and height directly and adjust font sizes, padding, and gaps.
Use a container with explicit dimensions and place content within it using normal flow.
For a whole document, change page size or margins instead of scaling individual children.
Generate a raster asset at the target dimensions when the content is inherently graphical, then place that asset as an image.
Split a complex component into smaller blocks so pagination can occur between stable units.

Evaluate each option on rendered size, position, pagination, overflow, supported target elements, and consistency between your deployed library and the current converter demo.

8. Troubleshooting common failures

Symptom	Likely cause	Fix
No visible scaling	The declaration is unsupported for that element or release, or another rule overrides it.	Inspect computed CSS, reduce to a one-element case, and test the exact version in the current converter demo.
Element moves unexpectedly	Transform origin or coordinate handling differs from the browser.	Set an explicit origin, add a border, and measure the PDF position. Treat the result as version-specific.
Following content overlaps	Painted size changed but normal-flow space did not.	Reserve the scaled dimensions with explicit layout sizes or redesign the component using normal flow.
Content is clipped	Container bounds, overflow, or page edges intersect the transformed box.	Remove overflow constraints, add page space, and test near a page break.
Different line wrapping	Font substitution, CSS width changes, or PDF pagination.	Embed or configure fonts, set explicit widths, and compare at fixed page dimensions.
Images or CSS are missing	Relative URLs cannot be resolved.	Set `ConverterProperties.setBaseUri` in Java or `SetBaseUri` in .NET and verify file permissions.
Works in demo, fails in deployment	Different pdfHTML or iText Core versions, resources, or HTML input.	Capture a minimal reproducible fixture and align versions and assets before changing CSS.

9. Performance, reliability, and cost considerations

Transforms add little value if they force repeated trial conversions of large documents. Keep a small regression fixture for every transform pattern and run it whenever dependencies change. Cache immutable assets such as fonts and images, and avoid converting the same HTML repeatedly during debugging.

For reliable output, pin compatible iText Core and pdfHTML versions, keep a deterministic base URI, and fail builds when the output page count or required dimensions change. Store representative PDFs as review artifacts. If a document is legally or financially important, inspect the final PDF rather than relying only on a successful conversion return code.

pdfHTML is commercial software, so account for your iText license and deployment terms separately from runtime costs. The sources reviewed here do not provide a benchmark or a universal performance figure; measure your own templates, resource sizes, and concurrency.

10. Or skip the browser setup

If your actual goal is to capture a rendered page as an image or PDF rather than build a PDF from HTML inside your application, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the result in X-Page-Verdict and X-Billed headers. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options, including full-page capture, CSS selectors, dark mode, device presets, retina scale, PDF paper settings, custom CSS and JavaScript, waits, blocking rules, headers, cookies, geolocation, caching, signed links, asynchronous jobs, bulk capture, and usage reporting.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python

import requests
r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const bytes = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', bytes);

ScreenshotNeo includes 1,000 screenshots per month free with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Create a free ScreenshotNeo account and start with the no-card plan.

11. FAQ

Does pdfHTML fully support `transform: scale()`?

No. The official feature overview describes the CSS transform property as partially supported. Validate your exact function, element, and version.

Which version does the feature overview describe?

Its stated basis is pdfHTML 6.3.3 with iText Core 9.7.0. Your installed versions may behave differently.

Is browser output a reliable oracle?

No. Browser layout and fixed-page PDF layout differ in fonts, pagination, coordinate systems, and overflow. Use the browser as a visual reference and measure the generated PDF.

Where should an uncertain case be tested?

Use iText’s current HTML Converter demo with the same minimal HTML and CSS, then repeat the test with the exact dependency versions used by your application.

Does a successful conversion guarantee correct scaling?

No. A successful API call only indicates that conversion completed. Inspect size, position, clipping, wrapping, and page breaks in the resulting PDF.