Set a standard paper format with page_size, or set an arbitrary format with both page_width and page_height. Keep custom values as strings with explicit units such as 80mm, 4cm, or 12in. Wicked PDF passes these options to the wkhtmltopdf executable, so that binary must be installed and reachable by your Rails application.
Choose between a named format and custom dimensions
Wicked PDF uses the shell utility wkhtmltopdf to turn HTML into a PDF. Its page-size options are therefore the Rails-facing form of wkhtmltopdf’s command-line flags.
Use page_size for a standard paper format
For A4, Letter, Legal, A3, or another format recognized by your installed wkhtmltopdf version, pass the name directly:
render pdf: "invoice", page_size: "Letter"The wkhtmltopdf manual identifies A4 as the default rendered page size. Supplying a named size makes the intended format explicit and avoids relying on that default.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- 1 ream (500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Use width and height for an arbitrary format
For receipts, labels, tickets, or other nonstandard sheets, pass both dimensions and include a unit in each value:
render pdf: "receipt",
page_width: "80mm",
page_height: "200mm",
margin_top: "5mm",
margin_bottom: "5mm",
margin_left: "5mm",
margin_right: "5mm"These options map to wkhtmltopdf’s --page-width and --page-height flags. Do not pass bare numbers such as 80; use unit-bearing strings. The documented examples use centimetres and inches as well as millimetres.
Install the renderer before changing page dimensions
The Ruby gem supplies the Rails integration, but PDF rendering occurs in the external wkhtmltopdf executable. Install that executable on every machine that generates PDFs, including workers and production containers. Wicked PDF’s README lists the wkhtmltopdf-binary gem as one installation route.
- Add Wicked PDF to your Rails application’s bundle.
- Install a compatible wkhtmltopdf binary, using the binary package or gem route appropriate for your deployment.
- Restart the Rails process after installation so the application can find the executable.
- Generate a small test PDF before debugging dimensions. If no PDF can be rendered at all, fix executable discovery first.
Available flags can vary with the installed wkhtmltopdf version. If an option is rejected, check the binary’s own supported flags and the version used by the environment running Rails.
Implement a custom page size in a controller
A complete controller action can keep the page settings next to the PDF response:
Rank #2
- HP Papers is sourced from renewable forest resources and has achieved production with 0% deforestation in North America. Each ream is wrapped in a polyurethane coated paper wrapper to protect the cut sheets from moisture damage
- Sheet size – 8.5 x 11; Thickness – 20 pounds; Brightness – 92 bright white
- HP Copy&Print20 20 pounds printer paper is Forest Stewardship Council (FSC) certified and contributes toward satisfying credit MR1 under LEED (Leadership in Energy and Environmental Design)
- All HP Papers provide premium performance on HP equipment, as well as on all other printer and copier equipment; 100% satisfaction guaranteed; ColorLok technology provides more vivid colors, bolder blacks and faster drying
- Superior quality, reliability, and dependability for high-volume printing at home, at school and in the office; HP Copy&Print20 print and copy paper prevents yellowing over time to ensure a long-lasting appearance for added archival quality
class ReceiptsController < ApplicationController
def show
@receipt = Receipt.find(params[:id])
render pdf: "receipt-#{@receipt.id}",
template: "receipts/show",
page_width: "80mm",
page_height: "200mm",
margin_top: "5mm",
margin_bottom: "5mm",
margin_left: "5mm",
margin_right: "5mm"
end
endThe values remain strings because the units are part of the wkhtmltopdf option. Keep the width and height together; supplying only one dimension leaves the other dimension to the renderer’s defaults or produces an unusable combination.
Set a named format in the same action
render pdf: "invoice",
template: "invoices/show",
page_size: "Letter",
orientation: "Portrait"Use either a named paper size or an arbitrary width-and-height pair for a given render. Treat them as two different configuration strategies rather than trying to make a custom value fit into page_size.
Control orientation and printable margins separately
Page dimensions, orientation, and margins are separate wkhtmltopdf settings. A custom width and height define the sheet; orientation expresses portrait or landscape; margin options reserve space around the document.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, 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| Requirement | Wicked PDF option | Example |
|---|---|---|
| Named paper | page_size |
page_size: "A4" |
| Arbitrary horizontal dimension | page_width |
page_width: "80mm" |
| Arbitrary vertical dimension | page_height |
page_height: "200mm" |
| Orientation | orientation |
orientation: "Landscape" |
| Top, bottom, left, or right whitespace | margin_top, margin_bottom, margin_left, margin_right |
margin_left: "5mm" |
The wkhtmltopdf manual documents margins as separate flags from page-size flags. If content appears clipped, reduce the content width, increase the page width, or adjust the relevant margins rather than changing only the height.
Pick dimensions that match the physical output
Thermal receipts and labels
Use the actual printable width for page_width and a height long enough for the expected content. For a receipt roll, a short fixed height can cause overflow onto another page if the HTML is taller than the selected sheet. If the output is cut off, increase page_height or redesign the template so its rendered height fits.
Rank #3
- 3 ream case (1,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Cards, tickets, and narrow forms
Keep all four margin values explicit. A wide default margin can consume a significant portion of a small page. Set the CSS layout width below the available width after margins, and avoid fixed pixel widths that exceed the physical sheet.
Metric and imperial units
Use one unit system consistently within a render where possible. Examples include 80mm, 4cm, and 12in. A missing suffix is ambiguous and should be treated as a configuration error.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why Wicked PDF appears to ignore your dimensions
The executable is missing or a different binary is running
Symptoms include an inability to render any PDF, an unknown-option error, or output that does not match the installed documentation. Confirm that wkhtmltopdf is installed, reachable by the Rails process, and the same version in development, background jobs, containers, and production.
You used a bare number
page_width: 80 and page_height: 200 do not communicate whether the values are millimetres, centimetres, or inches. Change them to unit-bearing strings such as "80mm" and "200mm".
You supplied only one custom dimension
Arbitrary sizing requires both page_width and page_height. Add the missing value, then render again with explicit margins.
Rank #4
- 5 ream case (2,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
A named size is overriding your intent
Check the final options passed by your controller, helper, or shared PDF concern. Use page_size for a named format, or use the width-and-height pair for a custom format; do not leave a conflicting named size in a shared default configuration.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →The page is the right size but the content is clipped
Clipping is usually a layout or margin problem rather than a media-box problem. Reduce the HTML/CSS content width, set smaller side margins, or increase the page width. Check long unbroken strings, tables, and images that cannot shrink.
The option is rejected by wkhtmltopdf
Wicked PDF delegates to the installed binary, and supported flags depend on that binary’s version. Run the version’s help output or consult its manual, then use the option names that binary accepts.
Verify the generated PDF instead of guessing
- Render a PDF with an unmistakable custom size, such as
80mmby200mm. - Open the file in a viewer and inspect page breaks, clipping, and whitespace.
- Use a PDF inspection utility available in your environment to read the document’s media box and confirm the physical dimensions.
- Repeat the check in the deployment environment. A different wkhtmltopdf build can produce different results even when the Rails code is unchanged.
Keep a small fixture template for this check. It should contain a border near each edge, a long line, and a multi-row table; those elements expose incorrect margins and insufficient width quickly.
Performance and reliability considerations
Page-size settings do not make HTML rendering instantaneous. The external process still loads the template, stylesheets, images, and any other resources required by the page. Keep PDF templates deterministic, make asset URLs reachable from the rendering environment, and avoid relying on a browser session that is unavailable to the server.
Best Value
- 8 ream case (4,000 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
- Use the same wkhtmltopdf installation and version across environments when reproducibility matters.
- Apply explicit margins and dimensions in the render call or a clearly documented shared default.
- Test the longest realistic receipt or form, not only a short sample.
- Regenerate after deployment if the binary package changed; verify the media box again.
Or skip the browser setup
If your goal is to capture a web page as an image or PDF rather than render a Rails view with Wicked PDF, ScreenshotNeo provides a website screenshot API. It accepts consent banners before capture, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and bills only clean shots. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the result with X-Page-Verdict and X-Billed headers.
One GET request is enough:
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 the complete option set. The service supports PNG, JPEG, WebP, and PDF output; full-page capture with lazy images, CSS-selector element capture, dark mode, device presets, custom viewports, retina scale, PDF paper size and margins, page ranges, custom CSS and JavaScript, clicks, selector waits, delays, network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify a migration.
Python equivalent:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js equivalent:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('shot.webp', data);ScreenshotNeo also includes an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account to get an API key.
Frequently Asked Questions
Can I use a custom width with a named paper size?
Treat these as separate strategies: use page_size for a named format and use both custom dimensions for an arbitrary format. Keep the final render configuration unambiguous.
How do I handle a landscape custom sheet?
Set the custom width and height that describe the sheet you need, then set the separate orientation option and verify the resulting media box in your deployment environment.
Why should I verify the media box when the PDF viewer looks correct?
A viewer can make a page appear plausible while the physical dimensions remain wrong. Reading the PDF media box confirms the actual sheet size consumed by printers and downstream workflows.
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.
