How to Add a Delay Before a wkhtmltoimage Screenshot
Use wkhtmltoimage’s documented `load.jsdelay` setting to wait after a page loads. Learn what the delay does, how to verify your build’s option, and what to try when timing is not enough.
Set wkhtmltoimage’s documented load.jsdelay setting to the number of milliseconds to wait after the page has loaded. The settings documentation uses 1200 milliseconds as an example. The documented wait can end earlier if JavaScript calls window.print(), so it is not always a guaranteed minimum delay. [Official settings reference]
The setting describes a fixed time allowance; it does not confirm that a particular widget, image, or network request has finished. For command-line use, verify the exact option spelling supported by your installed binary with its help output. The settings reference documents the underlying setting, but does not establish a CLI flag spelling.
1. Find the setting supported by your installed build
First identify the binary and inspect its help:
wkhtmltoimage --version
wkhtmltoimage --helpLook for a JavaScript delay option in the help output. Builds and packaged versions can differ, so use the spelling shown by the binary you will actually run. The official settings documentation names the setting load.jsdelay; it does not itself show the corresponding command-line spelling. Do not copy a guessed flag into production without checking it.
If you configure wkhtmltoimage through a library or wrapper, check that wrapper’s documentation for how it passes image settings. The wkhtmltoimage settings inherit load.* settings, including this delay. [Official settings reference]
2. Set the delay in milliseconds
Choose a value in milliseconds. For example, 1200 means 1.2 seconds. Use the option spelling reported by your installed binary’s --help; the following is a template, not a claim about a universal flag spelling:
wkhtmltoimage [YOUR_BUILD'S_DELAY_OPTION]=1200 https://example.com page.pngReplace [YOUR_BUILD'S_DELAY_OPTION] with the exact delay option shown by your build, and replace the URL and output filename with your own. If help does not show a supported delay option, consult the documentation for that build or wrapper before relying on a setting name from another version.
For a configuration interface that accepts the documented setting directly, configure load.jsdelay as 1200. The setting’s unit is milliseconds, and the wait begins after the page has loaded—not when the process starts. [Official settings reference]
3. Choose a delay that fits the page
Start with a short value such as the documentation’s 1200 ms example, inspect the output, and adjust based on what is missing. A longer delay can give client-side rendering more time, but it does not tell wkhtmltoimage that a specific asynchronous operation completed.
- Static page: a small delay may be enough, or no added delay may be needed.
- Page that renders content shortly after load: increase the delay and check whether the content appears consistently.
- Page with a known completion signal: a page script that calls
window.print()can end the documented wait early. Make sure the page calls it only when the desired content is ready. - Content loaded on user interaction or an unpredictable request: a fixed timer may remain unreliable. Consider a browser automation workflow that can wait for a specific condition.
The settings reference says the renderer waits for the configured interval or until JavaScript calls window.print(), whichever happens first. [Official settings reference]
4. Diagnose an incomplete screenshot
| Symptom | Likely cause | What to check |
|---|---|---|
| The screenshot is captured before the configured interval seems to pass | The page called window.print(), which can end the wait early. |
Search the page’s scripts and dependencies for calls to window.print(). Remove or change that signal only if you control the page and know it is not needed. |
| A widget is still missing after the delay | The widget’s asynchronous work took longer than the fixed allowance, or it depends on an interaction. | Check whether the widget eventually appears in a normal browser. Increase the delay for a quick diagnosis; if timing varies, wait for a specific condition in a browser automation tool. |
| The page is blank or partly rendered | The page may not have loaded successfully, scripts may have failed, or the renderer may not handle the page’s JavaScript as expected. | Open the URL in a browser, inspect the page’s network and console errors, then compare with the installed wkhtmltoimage version and its help output. |
| The CLI rejects the delay option | The flag spelling may differ in the installed build, or the option may be unsupported there. | Run wkhtmltoimage --help for that exact binary. Use only the spelling it lists, or follow the wrapper’s configuration documentation. |
| The configured wait has no visible effect | The value may be in the wrong units, may not be reaching the image settings, or an early window.print() call may end the wait. |
Confirm the value is milliseconds, inspect how the wrapper maps load.* settings, and check the page for window.print(). |
5. When a fixed delay is not enough
A delay is useful when the page usually finishes rendering within a predictable interval. It is a weak signal for a page whose completion time varies: the timer can expire too soon or simply add unnecessary waiting.
The wkhtmltopdf project’s status page describes its WebKit engine as old and recommends considering Puppeteer or a wrapper for sites that use dynamic JavaScript. That is maintainer guidance, not a benchmark or a guarantee that another tool will solve every page-specific issue. [Project status and recommendations]
The project’s downloads page lists stable series 0.12.6, released June 11, 2020. Packaged builds can differ, so check your own binary’s help and verify the behavior in the environment where you capture pages. [Official downloads page]
Or skip the browser setup
ScreenshotNeo provides a website screenshot API: one GET request returns an image or PDF. Its capture process removes supported cookie and consent banners, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses identify the page verdict and billing status in headers. ScreenshotNeo also has an MCP server for AI agents, with tools for taking screenshots, getting page information, and capturing PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
For other available options, see the ScreenshotNeo API documentation. This runnable cURL example captures a PNG from Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.pngCreate a free account for 1,000 screenshots a month, with no card.
Cost, performance, and reliability notes
- Performance: every added millisecond delays the output after page load unless
window.print()ends the wait first. Longer values increase capture time; they do not ensure that a specific operation has finished. - Reliability: confirm behavior with the installed binary and the target page. A fixed delay is most predictable when rendering time is stable. For dynamic pages, prefer a condition-based approach where possible.
- Cost: the research sources do not provide a cost figure for wkhtmltoimage or for running a particular capture workflow. Account for the compute time and infrastructure used by your own setup rather than assuming a universal price.
- Security: the official downloads page warns against using wkhtmltopdf with untrusted HTML and advises sanitizing user-supplied HTML and JavaScript; it warns that unsafe use can lead to complete server takeover. Preserve that warning when accepting untrusted input, and consult the project’s original guidance for scope. [Official downloads page]
Frequently asked questions
Does load.jsdelay use seconds?
No. It uses milliseconds: 1200 is 1.2 seconds. [Official settings reference]
Does the delay start when wkhtmltoimage starts?
The documentation describes the wait as occurring after the page has loaded. It does not describe the delay as starting at process launch. [Official settings reference]
Can I guarantee the full delay always elapses?
No. JavaScript calling window.print() can end the wait sooner. [Official settings reference]
What should I use for a page with dynamic JavaScript?
The project status page recommends considering Puppeteer or a wrapper for dynamic-JavaScript sites. Choose based on your page and workflow, and verify the result in your environment. [Project status and recommendations]
