In Wicked PDF, use margin: { bottom: ... } to reserve space at the bottom of each rendered page, and footer: { spacing: ... } to set the gap between the footer and the document content. These settings do different jobs: footer.spacing is not the footer’s height. For different settings on separately supplied page objects, wkhtmltopdf supports object-level options; its documentation does not establish changing margins or footer settings at arbitrary physical page breaks inside one continuous HTML object.
What “footer height” means in Wicked PDF
There is no documented footer.height option in the Wicked PDF or wkhtmltopdf option lists covered by their documentation. A footer’s visible height is determined by the content and layout of its text or HTML template. The option you can use to make room for it is the page’s bottom margin.
Think of the page as having three separate measurements:
- Footer content: the rendered text or HTML, whose height depends on what it contains and how it lays out.
- Bottom margin: the area reserved at the bottom of the page. Increase it when content runs into the footer or the footer is clipped.
- Footer spacing: the gap between the footer and the document content. Adjust it when the footer is too close to the body, not to make the footer itself taller.
Wicked PDF passes options to wkhtmltopdf, and supported options can depend on the installed wkhtmltopdf version and build. Treat the configuration below as the option shape to adapt, not a universal measurement that fits every template.
#1 Best Overall
Set the bottom margin and footer spacing
In a Rails action that renders a PDF, the options can be nested like this:
render pdf: 'report',
margin: { bottom: '20mm' },
footer: {
spacing: 4,
html: { template: 'shared/footer', layout: 'pdf_plain' }
}The 20mm bottom margin is an example value, not a prescribed setting. Increase or decrease it to reserve the space your actual footer needs. The underlying wkhtmltopdf manual defines footer spacing in millimeters and documents a default of 0; in the example, spacing: 4 is a separate, illustrative gap value.
- Start with the footer content. Decide whether the footer should be plain text or an HTML template. Keep in mind that a more substantial template may need more reserved room.
- Set a bottom margin. Use
margin: { bottom: '20mm' }as an initial example, then adjust it after rendering the actual document. - Set spacing separately. Use the nested
footer: { spacing: 4, ... }option to change the gap between body content and footer. The value is expressed in millimeters by wkhtmltopdf. - Render and inspect the PDF. Check pages with the most body content and the tallest footer. Tune the margin if text overlaps or the footer is clipped; tune spacing if the footer-to-content gap is wrong.
The two margin and footer structures above are shown in the Wicked PDF README. Check the options supported by the gem version installed in your application, particularly if the configuration is being added to an older codebase.
Choose a text footer or an HTML template
Text footer
A text footer is appropriate when the footer is only a short line, such as a page indicator. wkhtmltopdf supports substitutions including [page] and [topage], which represent the current page and total page count. Keep the reserved bottom margin large enough for the rendered line; spacing only changes the gap above it.
HTML footer
Use an HTML template when the footer needs richer layout or styling. Wicked PDF exposes footer HTML through template options, as in html: { template: 'shared/footer', layout: 'pdf_plain' }. The template’s rendered height depends on its actual content and layout, so there is no single documented height setting to substitute for the bottom margin.
wkhtmltopdf’s manual also describes a template pattern that receives page variables in the query string for an HTML footer. Follow the manual’s pattern if the footer needs page-specific data. The exact rendered result still depends on the template and executable used in your deployment.
Can margins vary on each page?
It depends on what “page” means in your PDF generation workflow. wkhtmltopdf documents options in a page object’s option area as well as globally. That supports configuring distinct separately supplied page objects with applicable options, subject to the way your application invokes the renderer.
That is not the same as setting a new margin or footer at every physical page boundary in a long, continuous HTML document. The cited documentation does not establish arbitrary per-physical-page conditional margins or footer options within one HTML page object. Do not assume that a page break in the HTML creates a new page object or that the next printed page can receive different Wicked PDF options.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems- Separate page objects: investigate object-level options for each separately supplied object, and verify that the integration passes them through in your workflow.
- One continuous HTML input: treat its global margin/footer options as document-wide unless your specific implementation establishes otherwise.
- Cover page: wkhtmltopdf documentation explicitly says a cover object has no headers or footers. If a cover needs different treatment, account for that restriction rather than expecting its footer to behave like an ordinary page object.
If you need a different footer on a particular physical page in a continuous report, the documentation cited here does not establish a general per-page option for doing so. Design the document around separately configured objects only if that matches your rendering path, and validate the result with the exact installed binary.
Verify the wkhtmltopdf executable in your environment
Wicked PDF is a wrapper around wkhtmltopdf, and the wrapper warns that available options depend on wkhtmltopdf versions. The Debian Bookworm manual provides a concrete compatibility warning: its build without patched Qt lacks header and footer support. A configuration can therefore be syntactically reasonable yet fail to produce the expected footer because the executable differs from the one assumed.
Before debugging CSS, establish which wkhtmltopdf executable your application actually runs and what build it is. Check the deployment environment as well as a developer workstation; the PDF generation process may use a different executable or package in production. Then render a small representative PDF and inspect both footer behavior and page margins. Do not infer support from the Ruby options alone.
Make HTML footer assets available to the renderer
wkhtmltopdf runs outside the Rails rendering process. Wicked PDF notes that normal Rails layouts do not automatically work for PDF assets, and that PDF stylesheets, images, and other assets need absolute references or Wicked PDF’s helpers. A footer can consequently render without expected styling or omit an image even though its template is being used.
PC 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 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute- Confirm the footer template is the one configured for the PDF.
- Use absolute asset references or the PDF helpers described by Wicked PDF rather than assuming ordinary browser-relative asset paths will resolve.
- When a footer’s appearance changes between environments, check asset availability and the wkhtmltopdf build before changing its spacing value.
Troubleshoot common footer and margin problems
Body text overlaps the footer
Increase margin.bottom to reserve more page area for the footer. Changing footer.spacing alone changes the gap to the content; it does not reserve more page area for a tall footer.
The footer is clipped or partly missing
Give the footer more room by increasing the bottom margin, then render the document again. Also verify that the configured footer template and its assets load, and confirm that the installed wkhtmltopdf build supports footer rendering.
The footer is too far from the body
Adjust footer.spacing rather than using it as a substitute for the bottom margin. Keep enough bottom margin for the footer itself after changing the gap.
The HTML footer is unstyled or missing images
Check the asset paths. The renderer runs outside Rails, so ordinary Rails layout behavior and relative asset references may not carry over to PDF rendering. Use absolute references or Wicked PDF’s helpers.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Best Value
- Wide Compatibility & Plug and Play | portable scanner, document scanner, scanner for laptop, handheld scanner: Works seamlessly with Windows and Mac OS systems, no driver or software required. This portable document scanner is truly plug and play—perfect for laptop users, office work, and travel scanning. Start scanning instantly anytime, anywhere without setup hassle.
- 3 Adjustable DPI for Crystal Clear Scans | portable document scanner, receipt scanner, handheld scanner, image scanner: Choose from 300/600/900 DPI to meet different needs—from quick receipt scans to high-resolution photo archiving. This handheld scanner delivers sharp, vivid results for documents, receipts, and images, ensuring every detail is captured with precision.
- Large Storage & Flexible File Formats | portable scanner, document scanner, scanner for documents, mobile scanner: Supports up to 32GB Micro SD card, allowing massive storage without relying on a computer. Save files in JPG or PDF formats for easy sharing and organization. Ideal for business trips, students, and professionals needing a mobile scanning solution.
- One-Button Easy Operation & Fast Scanning | handheld scanner, portable scanners for documents, receipt scanner, scanner wand: Designed for simplicity—just power on, select mode, and press scan. The ergonomic wand design makes scanning smooth and efficient. Auto-save function ensures no data loss, making it perfect for quick document capture on the go.
- Multi-Scenario Use for Work & Travel | portable document scanner, receipt scanner, scanner for laptop, mobile scanner: Perfect for office, bank, library, travel, or home use. Easily scan contracts, receipts, notes, and photos anytime. Keep your important files digital, organized, and private—an essential tool for professionals, students, and travelers.
Footer options have no effect
Check the exact wkhtmltopdf executable and build used by the application. The available options depend on the version, and the Debian Bookworm manual warns that a build without patched Qt lacks header and footer support. Also check the installed Wicked PDF version and how it passes options to the renderer.
Different settings do not apply after a page break
A page break within continuous HTML is not documented as an object-level options boundary. Confirm whether your PDF is assembled from separate page objects; if it is not, do not expect per-object settings to switch on a physical page break.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server, not a Wicked PDF configuration tool. If your actual goal is to capture a website as an image or PDF instead of generating a Rails report with page-specific footer behavior, one request can return a capture. Its API documentation is at ScreenshotNeo docs.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo 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 shots a month with no card; paid plans start at $5 for 3,000 shots. Those capabilities are for website captures, not a replacement for setting Wicked PDF’s margins or footer options.
Free tools Windows power users keep installed
One-click scans. No signup required.
Sign up for ScreenshotNeo free: 1,000 screenshots a month, no card.
Performance, reliability, and cost considerations
For Wicked PDF, footer layout is a rendering concern: verify the actual template and executable rather than selecting a margin based on a generic recommendation. A small representative PDF can expose overlap, clipping, missing assets, or unsupported footer options before the same configuration is used for a longer report. The sources establish option names and scope, but do not determine the exact rendered height of a particular HTML footer across deployments.
The cited material does not establish a universal performance impact, reliability figure, or cost for changing margins or footer spacing. Those depend on the application and deployment, so measure rendering time and operational costs in the environment that generates the PDFs instead of assuming a specific effect from these settings.
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.
Recommended Free Tools
