How to Preserve CSS Backgrounds When Converting HTML to PDF in CloudConvert
Use CloudConvert’s documented screen CSS setting, verify its current options, and diagnose missing background colors and images before relying on a PDF conversion.
Short answer: CloudConvert’s documented HTML-to-PDF example uses the capture-website operation with css_media_type set to screen. That selects screen media styles; it does not, by itself, guarantee that CSS background colors or images will appear in the PDF. Check the current options for your chosen operation and engine, then validate both kinds of background with a small conversion before relying on the result.
1. What the screen setting does—and does not do
CSS can provide different rules for screen and print media. CloudConvert’s example sets css_media_type: "screen", which is the documented starting point when your intended layout comes from screen styles. CloudConvert’s reviewed documentation does not establish that this setting forces backgrounds to print or guarantee that every CSS background will be present.
CloudConvert describes its website-to-PDF tool as Chrome-based and says the output resembles browser Print to PDF. Media selection and the browser’s PDF path are relevant to the result, but neither statement proves that every page, CSS rule, asset, or option combination will render backgrounds as expected. See CloudConvert’s HTML to PDF API and Save Website as PDF documentation.
2. Create a CloudConvert website-to-PDF job
CloudConvert’s documented workflow uses a capture-website task whose output format is PDF. For a URL, the essential structure is:
{
"tasks": {
"capture": {
"operation": "capture-website",
"url": "https://example.com/page",
"output_format": "pdf",
"css_media_type": "screen"
},
"export": {
"operation": "export/url",
"input": "capture"
}
}
}This illustrates the job/task configuration documented by CloudConvert; submit it using the job creation method and authentication required by your CloudConvert account. Consult the Capture Website operation documentation for the current request shape and supported settings. The capture task creates the PDF; the export task makes its output available as a URL.
URL input or HTML input
CloudConvert supports website URLs and HTML input. A URL is convenient when the page is publicly reachable. For protected pages, CloudConvert’s product documentation describes custom authorization headers. With supplied HTML, check how linked stylesheets, fonts, and background image URLs resolve: relative asset paths may not resolve the same way they do on your local site.
Check the live operation options
Before adding settings beyond the documented example, inspect the options accepted for the selected operation and engine in CloudConvert’s Job Builder or API operation metadata. The Operations API reference describes retrieving operations, options, and engine versions. Do not assume a parameter exists just because a browser automation library uses a similarly named option.
3. Validate backgrounds with a minimal page
Use a small test page that separates the two common cases. For example, give one block a solid CSS background color and another a CSS background image. Convert that page with the same input mode, media type, engine, and relevant job options you plan to use in production. Inspect the resulting PDF at normal zoom and at a larger zoom so that missing assets or unexpected layout are easy to spot.
This is a recommended validation method, not a claim that a particular conversion was run. Check these separately:
- Background color: Does a block with a plain CSS
background-colorappear with the intended color? - Background image: Does a CSS
background-imageload and appear, including when its URL is relative? - Media rules: Does the expected stylesheet apply under the selected
screenmedia type? - Timing: Does the background appear after all relevant page content and styles have loaded?
- Repeatability: Does a second conversion produce the same layout and background result?
Keep this sample as a regression check when the source page, stylesheet, asset hosting, or CloudConvert job options change.
4. Tune layout and wait for dynamic content
CloudConvert documents HTML-to-PDF controls such as page size, margins, zoom, and custom headers and footers. These affect page layout or add header/footer content; header and footer templates are separate from the page’s CSS backgrounds. Review the current options for the operation and engine before using them.
If the page renders content dynamically, CloudConvert says its headless Chrome browser can wait for a custom CSS selector. Choose a selector that appears only when the content and styles needed for the capture are ready. A fixed delay may not reliably cover variable network or rendering time; where supported, a readiness selector makes the intended condition clearer.
5. Troubleshoot missing backgrounds
| Symptom | Checks and likely causes | Next step |
|---|---|---|
| Background color is absent | The page may be using print-specific CSS, the selected media type may not match the intended stylesheet, or the conversion path may not render the background as expected. | Try the documented screen setting, inspect the page’s media rules, and compare a minimal color-only test. Check the live operation options; do not assume there is a background-printing switch. |
| Background image is absent but color appears | The image URL may be inaccessible to the conversion process, a relative URL may resolve differently, or the asset may not have loaded before capture. | Check the asset URL and its accessibility from the conversion process. Test an absolute asset URL and wait for a selector that indicates the page is ready. |
| Some pages work and others do not | The pages may differ in media rules, authentication, resource paths, or loading behavior. | Compare the failing page against the known-good minimal sample. Verify authorization headers where needed and check each background asset separately. |
| Layout is wrong as well as backgrounds | The capture may use a different media stylesheet or page size, margins, or zoom than expected. | Confirm css_media_type, then review the current page size, margin, and zoom options for the operation and engine. |
| Dynamic content is missing | The capture may happen before the relevant element or its styling exists. | Use CloudConvert’s documented selector-wait capability with a selector tied to readiness of the needed content. |
| A guessed parameter is rejected | Option names and availability depend on the operation and engine; a setting from another browser tool may not be supported here. | Inspect CloudConvert’s current operation metadata or Job Builder and use only listed options. |
A missing background can be a rendering or stylesheet issue, but it can also be an asset-loading problem. Diagnose those separately before changing the conversion settings.
6. Performance, reliability, and cost considerations
Page complexity and external assets can affect how much work a browser-based capture must do. Keep the page and its required resources reachable, avoid waiting for an unrelated element, and use a readiness selector that reflects the content you need. Revalidate when page code or assets change. The reviewed CloudConvert sources do not provide a benchmark or a guarantee for background rendering across all pages, so use your own representative pages to assess output and conversion behavior.
Check CloudConvert’s current account and pricing information for cost details; no pricing figure is established in the research for this guide. A small representative test can help uncover asset access, timing, and layout problems before you depend on a larger production workflow.
7. Or skip the browser setup
If your goal is a clean capture of a web page rather than a CloudConvert-specific PDF workflow, ScreenshotNeo is a website screenshot API and MCP server. Its PDF capture supports paper size, margins, landscape, and page ranges. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.pdfFor a PDF, use the documented PDF output options in the API request. ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each of these steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.
8. FAQ
Does css_media_type: "screen" guarantee CSS backgrounds in CloudConvert?
No such guarantee is established in the reviewed documentation. It is the documented example value for selecting screen CSS. Confirm the current options and validate the backgrounds in a sample conversion.
Is a missing background image necessarily a PDF setting problem?
No. Check whether the image asset is reachable, whether its path resolves correctly for the conversion, and whether it has loaded by capture time.
Are CloudConvert PDF headers and footers the same as page backgrounds?
No. They are separate layout features. Configure them independently and validate the page’s own CSS backgrounds in the output.
Where can I confirm accepted CloudConvert settings?
Use the Job Builder or the API operation metadata for the selected operation and engine. CloudConvert documents operation options and engine versions in its Operations API reference.
