First identify which kind of “cut off” you have. If the image is divided at a PDF page boundary, you are dealing with pagination. If pixels are missing inside the image’s own box, investigate CSS clipping, SVG features, overflow, sizing, or image loading instead. For page-boundary splits, put page-break-inside: avoid on a suitable image container, simplify the surrounding markup, and make sure the element can fit in the printable area. This is only a partial mitigation: wkhtmltopdf’s WebKit pagination model can still split content.
Classify the failure before changing CSS
Open the generated PDF at high zoom and compare the HTML in a browser. Then classify the symptom:
- Page-boundary split: the top of an image appears at the bottom of one PDF page and the rest continues on the next page.
- In-box crop: the PDF reserves the expected image area, but part of the artwork is missing inside that area.
- Missing image: a blank region, broken-image icon, or intermittent result indicates loading, URL, permissions, or timing rather than pagination.
These cases need different fixes. A page-break rule will not repair an SVG clip-path, and changing image dimensions will not solve a renderer that cannot load the source.
Why wkhtmltopdf splits images
wkhtmltopdf renders a long WebKit document and then cuts that rendered surface into paper-sized pages. The project manual describes image splitting as a limitation of this pagination model. It says the CSS page-break-inside property can remedy the problem “somewhat” when using patched Qt, and recommends arranging documents so there are many clean lines at which a page can be cut.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
That wording matters: there is no universal “never split images” switch. Results depend on the exact wkhtmltopdf build, whether Qt is patched, paper size, margins, scaling, and the HTML structure around the image.
Record the rendering environment
Before editing the document, save the exact command or library options and collect:
- wkhtmltopdf version and build identifier (run
wkhtmltopdf --version). - Operating-system name and version.
- Whether the build uses patched Qt.
- Paper size, orientation, margins, zoom or smart shrinking settings.
- The image type: raster file, SVG, CSS background, or an image inside a table.
- A minimal HTML file and the resulting PDF.
Build identity is important because features differ between patched and unpatched Qt builds. An older packaged manual describes wkhtmltopdf 0.12.3.2; do not assume its behavior exactly matches your installed release.
Fix images split between PDF pages
1. Add an image wrapper with a break rule
Apply the rule to the smallest meaningful element that must stay together, rather than indiscriminately applying it to the entire document:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems<div class="image-block">
<img src="images/report-chart.png" alt="Quarterly report chart">
<p class="caption">Quarterly results</p>
</div>.image-block {
page-break-inside: avoid;
break-inside: avoid;
}
.image-block img {
display: block;
max-width: 100%;
height: auto;
}page-break-inside is the property wkhtmltopdf’s documentation discusses. The newer break-inside declaration is harmless in many stylesheets, but it is not a guarantee that an older WebKit build will honor the rule.
2. Put the rule on the table row when appropriate
If the image belongs to one logical table row, try the row or an outer cell:
table { width: 100%; border-collapse: collapse; }
tr.image-row, tr.image-row td {
page-break-inside: avoid !important;
}
.image-row img { max-width: 100%; height: auto; }Do not assume !important makes the renderer obey the rule. A reported reproduction showed images inside a deeply nested table splitting despite page-break-inside: avoid !important. In that report, moving the image content to the outermost table avoided the split. Treat this as a layout-specific workaround, not a general rule for every version.
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
3. Make the element physically fit
An element taller than the printable page cannot stay intact without being moved, reduced, or creating substantial whitespace. Calculate the usable height from paper height minus top and bottom margins, then size the image or split the content deliberately. For a landscape document, set the orientation and dimensions explicitly:
Free tools Windows power users keep installed
One-click scans. No signup required.
wkhtmltopdf --page-size A4 --orientation Landscape
--margin-top 12mm --margin-bottom 12mm
--margin-left 12mm --margin-right 12mm input.html output.pdfUse CSS dimensions that match the intended paper layout. Avoid placing a very tall poster, chart, or screenshot in a wrapper that claims it must never break; wkhtmltopdf may move it to the next page or leave a large blank area.
4. Create clean break points
Long, deeply nested layouts give the paginator fewer safe places to cut. Separate major blocks, captions, and tables into sibling containers. Where a new section should start on a fresh page, use a deliberate break:
.new-page { page-break-before: always; }
.keep-together { page-break-inside: avoid; }Prefer several moderate-sized blocks over one giant wrapper. This follows the manual’s recommendation to organize HTML with many lines at which a page can be cut cleanly.
When the image is cropped inside its own box
Inspect CSS clipping and overflow
Temporarily remove overflow: hidden, fixed-height wrappers, transforms, masks, and restrictive width or height declarations. Replace them with a diagnostic style:
.diagnostic img {
width: auto;
max-width: 100%;
height: auto;
}
.diagnostic, .diagnostic svg { overflow: visible; }
If the complete image appears, restore rules one at a time to identify the clipping declaration. Also check whether a parent establishes a smaller containing box than the browser preview suggests.
Check SVG clipping paths
SVGs can crop themselves through clip-path, masks, viewBox coordinates, or transforms. In one community report, replacing an SVG’s clipping path with clip-path="none" was offered as a workaround. A later answer on that page suggested testing opacity: .99. Both are anecdotal: use them only as isolation experiments for a matching SVG case, not as official wkhtmltopdf settings.
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
<svg viewBox="0 0 800 400" overflow="visible">
<!-- temporarily remove clipPath/mask while diagnosing -->
</svg>Exporting the same artwork as a PNG is another diagnostic step. If the PNG renders completely while the SVG does not, focus on SVG geometry or unsupported features rather than pagination.
Images that are blank or intermittently missing
- Use absolute, reachable URLs or a correct
--enable-local-file-accesspolicy for local assets. - Confirm the process can read the file and that case-sensitive paths match.
- For images inserted by JavaScript, wait until the DOM and image requests finish before conversion.
- Check redirects, authentication, mixed-content restrictions, and server responses.
- Try a standalone HTML file containing only the image to separate loading from layout.
A blank image is not evidence that page-break-inside failed; first prove that the renderer received image bytes.
Options worth testing carefully
The official settings reference exposes controls for image loading, intelligent shrinking, print-media selection, paper dimensions, margins, and related image behavior. None is documented as a universal anti-clipping switch.
- Print media: ensure your print stylesheet does not intentionally hide or resize the image.
- Intelligent shrinking: compare output with the setting enabled and disabled when scaling changes cause unexpected dimensions. Record the result because shrinking affects the whole layout.
- Paper and margins: explicitly set them instead of relying on defaults.
- Image loading: verify that disabling image loading has not been enabled by a wrapper or library.
Change one setting at a time and retain the generated PDF for comparison. A visually improved split can still introduce distorted sizing, excess whitespace, or a different page count.
A reproducible diagnostic procedure
- Make a copy of the source HTML and remove unrelated scripts, styles, and sections.
- Keep one problematic image and its immediate container.
- Run the same wkhtmltopdf command with fixed paper size and margins.
- Test the wrapper rule, then test a simplified table structure.
- For SVGs, remove clipping and transforms temporarily.
- Compare the PDF with a browser print preview and with a raster version of the image.
- Reintroduce the original layout in small increments until the failure returns.
This process distinguishes a renderer limitation from a specific CSS, table, SVG, or loading defect.
Troubleshooting by symptom
| Symptom | Likely area | Next action |
|---|---|---|
| Image continues on the next page | Pagination | Add page-break-inside: avoid to the image container; reduce height or restructure blocks. |
| Rule has no effect in a nested table | Table pagination | Flatten the table or move image content to an outer row; validate on your build. |
| Edges disappear inside an SVG | SVG clipPath, mask, viewBox, or overflow | Remove clipping features temporarily and test a PNG. |
| Image area is blank | Loading or access | Test a standalone file, verify paths and permissions, and wait for dynamic content. |
| Output changes after an upgrade | Build or Qt differences | Record exact versions and rerun the minimal reproduction. |
What to include in a bug report
The project support guidance asks for the wkhtmltopdf version, operating system and version, and a detailed description with a test case in HTML, CSS, and JavaScript. Include the exact command or library configuration, paper and margin settings, source assets when possible, and the generated PDF. State whether the failure is a page split, an in-box crop, or a missing image. A small reproducible file is more useful than a screenshot alone.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Or skip the browser setup
If your goal is simply a clean image or PDF of a URL, ScreenshotNeo provides a single HTTP request instead of maintaining a local wkhtmltopdf pipeline. Cookie banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
See the complete parameter reference in the ScreenshotNeo documentation. A basic cURL request is:
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
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}`);The service includes full-page capture with lazy images loaded, CSS-selector element capture, device presets and custom viewports, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, click and wait conditions, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed links, asynchronous webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Its parameter names are compatible with those used by other screenshot APIs, which can simplify migration.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is included on every plan. Create a free ScreenshotNeo account.
Frequently Asked Questions
Will adding !important always stop an image from splitting?
No. A reported nested-table case still split with page-break-inside: avoid !important; layout structure and renderer build matter.
Should I use PNG instead of SVG?
Use PNG as a diagnostic or compatibility fallback when SVG clipping features are the suspected cause. It does not fix pagination by itself.
Why did wkhtmltopdf create a large blank area?
A keep-together rule may move an element that cannot fit in the remaining printable space. Reduce the element, adjust margins, or create a cleaner intentional break.
The Bottom Line
There is no guaranteed anti-clipping switch in wkhtmltopdf. Separate page splits from in-box crops, apply page-break-inside: avoid to a fitting container, simplify nested tables, inspect SVG clipping, and preserve a minimal reproduction with exact build details.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →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.
