Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
When a background image is missing from a HiQPdf PDF, check the resource URL first, then the rendering context. HTML converted from a string has no document location unless you provide a baseUrl (or use an absolute URL). After the URL resolves, verify whether HiQPdf is rendering screen or print CSS and whether background graphics are enabled. Lazy-loading and the distinction between a CSS background and a PDF page-background layer are separate issues.
1. Identify the HiQPdf generation before changing code
HiQPdf has several .NET product generations, including Classic, Chromium for .NET and Next .NET. Their option names and defaults are not interchangeable. The guidance below describes the underlying rendering decisions, but you should confirm the exact property names in the reference documentation installed with your package.
- Classic or Chromium for .NET: look for the conversion overload that accepts a base URL and the Chromium lazy-image option.
- Next .NET: options include media type,
PrintBackgroundsand selectable lazy-image loading modes.
Record the package/version and conversion method before copying a sample. A property that compiles in Next may not exist in an older assembly.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
2. Give relative URLs a base URL
A relative reference such as Images/paper.png is resolved relative to the HTML document’s location. An HTML string has no location by itself, so the converter cannot know which host or directory should contain the image. HiQPdf’s FAQ recommends passing a base URL to HTML-to-PDF, HTML-to-image or HTML-to-SVG methods, or replacing relative references with fully qualified URLs.
#1 Best Overall
HTML string with a base URL
using HiQPdf;
var html = @"
<html>
<head>
<style>
.cover {
width: 700px;
height: 400px;
background-image: url('Images/paper.png');
background-size: cover;
background-repeat: no-repeat;
}
</style>
</head>
<body>
<div class='cover'>Report</div>
</body>
</html>";
var converter = new HtmlToPdf();
// The converter resolves Images/paper.png against this URL.
PdfDocument document = converter.ConvertHtmlToPdf(html, "https://example.com/");
document.Save("report.pdf");
document.Close();In this example the effective image URL is https://example.com/Images/paper.png. The base URL is the resource root; it is not necessarily the image file itself. If the CSS is in a subdirectory, choose a base path that matches the HTML document’s intended location.
Use an absolute URL as a diagnostic
Temporarily change the declaration to background-image: url('https://example.com/Images/paper.png'). If that works, your CSS is being rendered and the original failure is URL resolution or access to the relative path. Restore a relative URL plus a correct base URL when you need portable templates.
URL conversion versus string conversion
When you convert a web URL, the page already supplies its own URL context, so relative CSS and image paths can resolve naturally. An HTML string still needs the appropriate base URL. A base URL does not bypass authentication, firewall rules, TLS errors or filesystem permissions: the conversion process must be able to reach the resolved resource.
3. Check CSS media and background printing
URL resolution and background printing are different checks. A resource can resolve successfully yet remain absent because the converter is using print CSS or suppressing background graphics.
Screen versus print rules
HiQPdf Next uses screen media by default. Selecting print media activates @media print rules. If your background exists only in screen CSS, selecting print can remove it; conversely, a print-only declaration will not appear while rendering screen media.
<style>
.hero { background-image: url('Images/hero.png'); }
@media print {
.hero { background-image: url('Images/print-hero.png'); }
}
</style>Inspect the active stylesheet and explicitly choose the media type required by your design. Do not assume browser preview and PDF output use the same media.
Enable printed background graphics
HiQPdf Next documents PrintBackgrounds as the switch controlling printed background graphics. Chrome-like print setup can omit backgrounds unless this option is enabled. Set it on the page setup or document-control object used by your installed Next version, then verify that the selected layout preset does not override it.
// Illustrative Next-style configuration; verify the containing type in your version.
var pageSetup = new PdfPageSetup();
pageSetup.PrintBackgrounds = true;
// Apply pageSetup to the Next conversion options before converting.The exact containing type varies by API surface, so consult the property reference for your package. The important distinction is that PrintBackgrounds controls printing of CSS background graphics; it does not repair a bad URL.
4. Handle lazy-loaded images
An image may be absent because the page has not loaded it when conversion captures the document. This is common with <img loading="lazy"> and JavaScript-driven image insertion. HiQPdf Chromium troubleshooting describes HtmlToPdfLoadLazyImages as enabled by default. HiQPdf Next also documents lazy loading as enabled by default with selectable loading modes. Defaults can differ by version, so inspect the runtime setting instead of relying on assumptions.
Chromium for .NET
var converter = new HtmlToPdf();
converter.HtmlToPdfLoadLazyImages = true;
var pdf = converter.ConvertHtmlToPdf(html, "https://example.com/");
pdf.Save("lazy-images.pdf");
pdf.Close();If your build exposes a different option name, use its equivalent lazy-image setting. For JavaScript that inserts a background after load, wait for a selector, a delay or network idle if your edition supports those controls; otherwise make the image eager in the template.
Next .NET loading modes
Next provides lazy-image loading modes rather than one universal switch. Select the mode appropriate to your page and confirm the documented default for the installed version. A true setting only permits lazy resources to load; it cannot fix a URL that resolves to a 404 or a host blocked from the conversion environment.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →5. Distinguish a CSS background from a PDF page background
A CSS background belongs to an HTML element and follows that element’s size, stacking and CSS rules. A PDF page-background layer is content inserted behind the converted HTML by the PDF API. Choose the mechanism based on the requirement.
Use CSS when the image belongs to an element
- The image should move, crop or repeat with a component.
- Different elements need different backgrounds.
- You want CSS properties such as
background-size, positioning and media queries.
Use a page layer for stationery or a full-page watermark
HiQPdf documents a page-layouting event that can draw a PDF image or graphic before HTML content is laid out. This is appropriate for letterhead, a watermark or a full-page texture that should remain behind every element regardless of HTML flow. It is not a substitute for enabling CSS background printing.
// Conceptual pattern: attach the page-layouting event in your edition,
// draw the PDF image/graphic first, then allow HTML content to render.
// The event and drawing types differ between HiQPdf generations.Because event signatures differ among Classic, Chromium and Next, use the page-layouting example shipped for your exact assembly rather than mixing namespaces from another generation.
6. A repeatable diagnostic checklist
- Identify the HiQPdf generation and version.
- Determine whether conversion starts from a URL or an HTML string.
- For strings, pass a base URL that makes every relative CSS and image path resolve correctly.
- Test one fully qualified image URL to separate URL resolution from rendering problems.
- Confirm the resolved resource is reachable from the machine running conversion, including TLS, authentication and firewall requirements.
- Inspect the active media type and both
@media screenand@media printrules. - Enable
PrintBackgroundswhere your Next page setup requires it. - Check lazy-image settings and wait conditions for images inserted or deferred by JavaScript.
- Decide whether the requirement is an element background or a PDF page layer.
- Save a minimal test PDF containing one known image before debugging the complete template.
7. Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Neither CSS nor images load | Relative resources have no context | Pass baseUrl or use absolute URLs; verify access from the converter host. |
| <img> works but CSS background is missing | Background printing is disabled or CSS media differs | Check media selection and enable PrintBackgrounds in the applicable Next setup. |
| Only below-the-fold images are absent | Lazy loading has not completed | Enable the documented lazy-image option/mode and add an appropriate wait strategy. |
| Browser preview differs from PDF | Different media type, viewport or JavaScript timing | Compare screen/print rules, viewport and load completion; test an eager image. |
| Page watermark is clipped or overlays text | CSS background used for a page-layer requirement | Use the page-layouting background layer and draw it before HTML content. |
8. Performance, reliability and security considerations
Absolute URLs simplify diagnosis but make templates dependent on a host. A base URL keeps templates portable while preserving normal URL semantics. Remote images add network latency and can fail independently of HTML; self-hosting assets near the converter usually makes builds more predictable. If resources require cookies or authorization, configure the supported request headers or cookies for your HiQPdf edition rather than embedding secrets in public URLs.
Recommended Free Tools
Keep image dimensions and formats appropriate for the PDF’s target resolution. Very large backgrounds increase memory use and output size. For repeatable builds, log the final resolved URLs, media choice, lazy-loading mode and conversion errors. Never treat a successful conversion as proof that every background loaded: inspect representative pages or add an asset-verification step.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your real goal is a clean screenshot or PDF of a web page rather than controlling HiQPdf internals, ScreenshotNeo provides a single HTTP request and an MCP server for AI clients such as Claude and Cursor. It accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status.
For a screenshot, see the ScreenshotNeo API documentation. cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
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}`);It also supports PDF output, full-page and element captures, custom CSS/JavaScript, waiting rules, headers and cookies, device presets, dark mode, blocking controls, caching, signed links, asynchronous webhooks and bulk capture. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →FAQ
Does supplying a base URL download the image automatically?
No. It only tells HiQPdf how to resolve the relative reference. The conversion environment must still be able to retrieve the resulting URL.
Should I always enable print backgrounds?
Only when your selected HiQPdf setup suppresses them or your output requires printed CSS backgrounds. Confirm the behavior for your edition and layout preset.
Can a page-layer image replace CSS backgrounds?
It can replace them for stationery, watermarks and other page-wide artwork, but it will not provide element-level CSS behavior such as per-component positioning or media queries.
Frequently Asked Questions
Does supplying a base URL download the image automatically?
No. It resolves the relative reference; the converter still needs network or filesystem access to the resulting resource.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteShould I always enable print backgrounds?
Enable the setting when your edition or layout suppresses CSS backgrounds and your document requires them; verify the installed version’s defaults.
Can a page-layer image replace CSS backgrounds?
Only for page-wide artwork such as stationery or watermarks. Element-specific positioning and CSS media behavior require an HTML background.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
