Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
wkhtmltoimage does not document a command-line option for printing a visual header on an image. To show a heading in the screenshot, add it to the HTML and style it with CSS before rendering. If you cannot change the HTML, render the page first and add a header strip afterward with an image editor or image-processing library. The key distinction: --custom-header sends an HTTP request header; it does not add visible text to the image.
Choose what you mean by “header”
The word “header” can describe three different things in a wkhtmltoimage workflow. Only one is a visible heading inside the generated image.
- A visible page heading: Put the heading in the HTML, style it with CSS, and render that page. This is the right approach when the heading belongs to the page layout.
- An HTTP request header: Use
--custom-headerto send metadata with requests while wkhtmltoimage loads a URL. It affects the request, not the pixels in the output. The Debian bullseye wkhtmltoimage manual documents this option among its loading options. - A PDF page header: wkhtmltopdf documents options such as
--header-htmlfor PDF output. Those are not documented visual-header options for wkhtmltoimage. See the upstream wkhtmltopdf usage documentation.
For the image converter, the Debian bookworm manual, like the bullseye manual, describes HTML-to-image conversion and lists rendering and request-loading options without documenting a visual page-header switch. The manuals do not state a publication date in the examined content, so check the manual applicable to your installation if its behavior differs.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Recommended method: add the heading to the HTML
Place the heading before the page content in the HTML source. Style it as ordinary page content, then pass the HTML file or page URL and an output path to wkhtmltoimage. The documented command form is wkhtmltoimage [OPTIONS]... <input file> <output file>.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
1. Create or edit the HTML
This minimal example produces a heading above the main content. Save it as report.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Monthly report</title>
<style>
* { box-sizing: border-box; }
body {
margin: 0;
font: 16px Arial, sans-serif;
color: #202124;
}
.page-header {
width: 100%;
padding: 16px 24px;
background: #f1f3f5;
font-size: 24px;
font-weight: bold;
}
main { padding: 24px; }
</style>
</head>
<body>
<header class="page-header">Monthly report</header>
<main>
<h1>March results</h1>
<p>Put the page content here.</p>
</main>
</body>
</html>The header is a normal HTML element; its visual appearance comes from the CSS. Change the text, padding, font, and background to suit the page. Keeping box-sizing: border-box makes the declared width include padding, which helps avoid an unexpectedly wider header.
2. Render the file
Run the converter with the input file followed by the output image path:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
wkhtmltoimage report.html report.pngFor a URL input, use the URL in place of the local filename:
wkhtmltoimage https://example.com/report report.pngThe command-line manual documents the input/output form and options including --width, --height, and crop options. These can affect the rendered dimensions and what fits in the output; exact behavior can depend on the installed build and the dimensions you choose. If the heading appears clipped, inspect the output dimensions and adjust the page layout or the relevant width, height, or crop settings rather than looking for a header-specific switch.
3. Decide whether the heading belongs in the page layout
Adding the heading to the HTML means it participates in the rendered page. Its height and spacing occupy room above the content, so the image may become taller or the visible crop may include less of the content below it. This is usually desirable for a report title or a branded page heading. If the heading must sit in a fixed strip without changing the captured page itself, use the post-render approach instead.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
If the HTML cannot be changed: composite a header strip
Render the original page without changing its markup, then create a new image with a blank or styled band at the top and place the rendered screenshot beneath it. This is a general image-compositing workflow, not a documented wkhtmltoimage feature. Use an image editor or an image-processing library already available in your workflow.
This approach is a better fit when the page source is unavailable, the same external heading should be applied to several captures, or the heading must be managed independently from the site’s layout. It also introduces a downstream image-editing step. Decide the strip height, background, and text placement in that step; make the output canvas tall enough for both the new strip and the original screenshot. Check that the original image has not been scaled or cropped unintentionally when positioning it.
Why --header-html does not solve this
It is easy to find examples of --header-html or --header-left in wkhtmltopdf discussions and assume they apply to wkhtmltoimage. The upstream documentation describes header and footer options for PDF generation, including an HTML-header example. They should not be treated as image-mode options: the Debian wkhtmltoimage manuals do not document them as a way to add a visible heading to an image.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
Likewise, --custom-header is not a visual substitute. It sets an additional HTTP header sent during page loading. Use it only when the website expects request metadata; put display text in the page HTML or composite it onto the image.
Or skip the browser setup
If your real goal is to capture a page rather than add a heading to the rendered image, ScreenshotNeo is a website screenshot API and MCP server. It does not replace the HTML-editing or image-compositing methods above for adding a custom heading; it can make the capture step an API request instead of a local browser setup.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsFor example, this cURL request captures a page as WebP:
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for request options. Cookie and consent banners are accepted before capture, and more than 60 known consent platforms, newsletter popups, and chat widgets can be removed; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and other MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Troubleshooting
The heading is not visible
- Confirm that the markup is in the HTML document actually passed to wkhtmltoimage, not only in a separate file or an unrelated page template.
- Check that the heading is not hidden or covered by page CSS. Temporarily give it a contrasting background and text color to make its bounds obvious.
- If rendering a URL, confirm that the URL is the page you intended to capture. A request header sent with
--custom-headerwill not create visible heading text.
The heading is cut off or the content below it disappears
- Inspect the output width and height and the crop settings used in the command. The manual documents width, height, and crop options, but exact output behavior depends on the build and chosen dimensions.
- Reduce excessive header padding or font size, or allow more output height if the heading is meant to add to the page.
- If you need a fixed band that must not affect the page layout, render first and composite the band afterward.
An option is rejected or has no visible effect
- Check the options documented for the executable you are running. The Debian manuals for bullseye and bookworm do not list a visual-header option for wkhtmltoimage.
- Do not transfer a wkhtmltopdf PDF-header option such as
--header-htmlto an image command and expect it to print a heading. - Use
--custom-headeronly for HTTP request metadata; it will not change the rendered page’s visible content.
The page differs from what you see in a browser
First separate a page-loading problem from a heading problem: the heading must be present in the document wkhtmltoimage renders. If a URL depends on request metadata, the manual’s --custom-header option concerns the request, not page display. If the page loads but the final crop or dimensions differ from what you expected, review the chosen width, height, and crop options against the output. The documented material does not establish one universal rendering result across installed builds, so verify the actual image produced by your installation.
Recommended Free Tools
Which method should you choose?
| Need | Use | Trade-off |
|---|---|---|
| The heading is part of the page or report | Add HTML and CSS before rendering | The heading participates in layout and can affect the content dimensions or crop. |
| The HTML cannot be edited | Render, then composite a header strip | Requires an image editor or image-processing step after capture. |
| Send metadata with a page request | --custom-header |
Changes request metadata, not visible pixels. |
| Place repeating headers on PDF pages | Use wkhtmltopdf’s documented PDF header options | These are PDF-generation options, not documented wkhtmltoimage image-header options. |
For a conventional title above a screenshot, edit the HTML and render it. For a heading that must be applied independently of the source page, composite it afterward. There is no documented wkhtmltoimage visual-header switch to insert that heading by command-line option alone.
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.
