How to Fix Cut-Off Text and Clipped Content in wkhtmltoimage

Start with the edge where content disappears. If the bottom is missing, check the rendered page height, crop height, and whether dynamic content finished loading. If text or layout is cut off at a side, check screen width, smart-width behavior, crop width, and page CSS such as fixed widths or overflow. If content appears late, wait for a page-specific readiness signal or use a measured JavaScript delay.

For example, render a page with a wider viewport and a deliberate post-load wait:

wkhtmltoimage --width 1440 --javascript-delay 1500 https://example.com page.png

Those values are examples, not universal fixes. Adjust one setting at a time and compare the output. The documented intelligent-shrinking setting has no effect for wkhtmltoimage; do not apply a PDF workaround to this image renderer. See the wkhtmltoimage command-line options and upstream library settings.

1. Identify what is clipped

Before changing options, record the exact command, input URL or file, output format, wkhtmltoimage version, operating system, and how the binary was installed. Save a copy of the output so each change can be compared.

Symptom	First checks
Bottom of the page is missing	Effective screen height, explicit crop height, and whether content expanded after the renderer measured the page.
Right or left edge is missing	Screen width, smart-width behavior, crop width, fixed-width elements, and horizontal overflow.
Text is cut off inside a box	Element height, line height, font availability, overflow, and whether the chosen viewport causes different line wrapping.
Some sections, images, or text are absent	JavaScript completion, image loading, network failures, and whether the page requires authentication or a particular browser state.

A normal browser screenshot is useful as a diagnostic reference, but it does not guarantee identical output: wkhtmltoimage uses its own rendering environment and may lay out modern pages differently.

2. Fix bottom clipping with height and crop checks

The command-line --height sets the screen height; when omitted, the height is calculated from the page content. The library image settings also expose crop coordinates and dimensions. A crop is an output window: if its height is smaller than the content you want, the rest will not appear in the image.

Try rendering without an explicit crop first. If you do need a crop, give it enough height to include the target content:

wkhtmltoimage --width 1280 --height 2400 --crop-x 0 --crop-y 0 --crop-w 1280 --crop-h 2400 https://example.com page.png

Use the actual target dimensions for your page. If the page grows after load, increasing height alone may not help: wait until the content has finished expanding, then capture.

3. Fix horizontal clipping and cut-off text

--width guides the screen width; with --disable-smart-width, it becomes strict. The library settings describe screenWidth and smartWidth, plus crop width and position. These controls affect the render viewport and output window. CSS controls page layout itself.

# Give a wide layout more room
wkhtmltoimage --width 1600 https://example.com page.png

# Enforce the chosen width when you need a fixed viewport
wkhtmltoimage --width 1280 --disable-smart-width https://example.com page.png

# Capture a selected horizontal region
wkhtmltoimage --width 1600 --crop-x 0 --crop-y 0 --crop-w 1600 --crop-h 1200 https://example.com page.png

Compare the two width modes against the same page. Use a wider screen when the page contains a wide table or fixed-width container. Use a strict width when you need reproducible viewport dimensions and have confirmed the page fits them.

If the page’s CSS creates the clipping, fix the layout where possible. Inspect fixed pixel widths, minimum widths, absolutely positioned content, flex or grid children that cannot shrink, and ancestors with overflow: hidden. For a one-off capture, a user stylesheet can override a known problematic rule. Keep overrides narrow so they do not distort unrelated components.

/* Example user stylesheet: apply only after finding the offending rule. */
.problem-container {
  overflow: visible !important;
  max-width: 100% !important;
}

Text can also appear cut off when the renderer has different fonts from the browser. Check whether the expected font is installed or can load, and compare line wrapping and the element’s height before changing viewport dimensions.

4. Wait for JavaScript and late-loaded content

Use a delay only when the page needs time after its load event. The command-line option is --javascript-delay. The library setting is load.jsdelay; its reference says the renderer waits for the delay or until JavaScript calls window.print(). No single delay works for every page.

# Wait a measured interval after page load
wkhtmltoimage --javascript-delay 2000 https://example.com page.png

# Alternatively, wait for the page's own readiness status
wkhtmltoimage --window-status capture-ready https://example.com page.png

The second approach requires the page to set window.status = 'capture-ready' when the content is ready. If you control the page, a readiness signal is generally easier to reason about than guessing a long delay. For a page you do not control, inspect whether content is asynchronous and choose a delay based on observed completion. Check JavaScript diagnostics and failed network resources if content remains absent.

5. Use the right wkhtmltoimage options

Control	Use it for	Notes
--width	Choosing the screen width used to render.	A guide unless smart width is disabled.
--disable-smart-width	Making the chosen width strict.	Compare behavior with and without it; it is not a universal clipping fix.
--height	Setting screen height.	If omitted, height is calculated from page content.
--crop-x, --crop-y, --crop-w, --crop-h	Selecting the output window.	Crop dimensions can exclude content even when the page rendered correctly.
--zoom	Changing the scale of page content.	Use only after checking viewport and CSS; zoom changes effective layout and text size.
--javascript-delay	Allowing time for JavaScript-driven content.	Set a measured delay rather than relying on an arbitrary value.
--window-status	Waiting for a page readiness marker.	The page must set the matching window.status value.
--format, --quality	Selecting the output image format and JPEG quality.	These affect encoding, not page layout or clipping.

At the library level, the image settings include screenWidth, smartWidth, crop.left, crop.top, crop.width, and crop.height. Loading settings include load.jsdelay, load.zoomFactor, JavaScript enablement, and JavaScript diagnostics. Match the configuration to the symptom rather than changing several settings together.

Important: web.enableIntelligentShrinking is documented as having no effect for wkhtmltoimage. It is not a fix for clipped image output. Similarly, print-media settings documented as having no effect for wkhtmltoimage should not be treated as image-renderer controls.

6. A repeatable diagnostic workflow

1. Freeze the reproduction. Save the input, exact command, output, renderer version, OS, and binary/package source.
2. Mark the missing region. Determine whether it is at the bottom, side, inside a component, or absent because it loaded late.
3. Remove crop variables. Temporarily capture without crop options. If that resolves it, set crop coordinates and dimensions to include the intended region.
4. Adjust one geometry setting. For horizontal loss, change width or smart-width mode. For vertical loss, examine height and page expansion.
5. Check CSS and fonts. Look for clipping containers, fixed widths, and unavailable fonts. Use a targeted stylesheet only when the problematic rule is known.
6. Check readiness. Add a suitable delay or a page-owned status signal for late content; inspect JavaScript warnings and failed resources.
7. Compare the build. If dimensions still differ from a colleague’s output, compare OS, wkhtmltoimage version, and package/build source.

Historical upstream issue reports describe sizing differences between Linux and Windows for wkhtmltopdf 0.12.1 with patched Qt. That is adjacent evidence, not proof of a defect in every wkhtmltoimage installation; it is a reason to include build and OS details when reproducing a mismatch.

7. Common errors and fixes

What you see	Likely cause	What to try
Increasing --height changes nothing	A crop height still limits the output, or content has not finished loading.	Remove crop options to isolate them; then wait for page readiness and reapply the intended crop.
Right edge remains cut off after increasing width	A strict width, crop boundary, or CSS overflow/fixed-width rule still excludes content.	Check --disable-smart-width, crop width and x-coordinate, then inspect the page’s layout CSS.
Content is present in a browser but absent in the image	Late JavaScript, failed resources, a font difference, or renderer compatibility.	Check JavaScript diagnostics and network access; wait for a readiness marker; compare the exact renderer build.
Longer delay works sometimes but not consistently	Load time varies, or the page has no stable completion condition.	Use a page-specific readiness marker when you control the page; otherwise measure load behavior and choose an appropriate delay.
Disabling intelligent shrinking has no effect	That setting does not affect wkhtmltoimage.	Adjust screen width, smart-width behavior, crop, CSS, or timing based on the clipping direction.
Output differs across machines	Different operating systems, binaries, patched builds, fonts, or dependencies.	Record and align version, build source, OS, and fonts before comparing results.

8. Performance, reliability, and cost considerations

Larger output dimensions and full-page content require more rendering and image data than a smaller crop. Capture only the area you need when that meets the use case. A longer JavaScript delay adds directly to the time spent waiting for each capture, so prefer a reliable readiness condition over a very large blanket delay when you control the page.

For repeatable output, keep viewport, crop, zoom, fonts, and renderer build stable. Record failures and inspect the output dimensions as well as the image itself. wkhtmltoimage runs in your own environment, so account for the cost of maintaining the binary, its dependencies, and any rendering workers in your deployment; the appropriate cost depends on your infrastructure and workload.

9. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. For a screenshot without managing a local renderer, send one request:

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

See the ScreenshotNeo API documentation for parameters and output options. ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Should I use --disable-smart-width for every clipped page?

No. It makes the chosen width strict. Compare both modes and keep the one that matches the layout you need.

Is --javascript-delay the same as waiting for a specific element?

No. A delay waits for a fixed interval; --window-status waits for a status value the page sets. Choose based on whether you can control the page and its readiness signal.

Does this guidance apply to wkhtmltopdf?

Some settings overlap, but PDF pagination and image capture have different behavior. This guide addresses wkhtmltoimage; verify any PDF-specific advice against the PDF documentation.

What details should I include in a bug report?

Include a minimal input, exact command, output, wkhtmltoimage version, operating system, and how the binary was obtained. Describe which edge or element is clipped.