First identify where the whitespace appears. A gap between two tables on the same page usually points to margins, padding, or a wrapper; a gap at a page boundary calls for checking print-specific CSS, page-break rules, paper size, and PDF margins. Puppeteer uses print CSS when generating a PDF by default, so the PDF may not match the screen preview. The exact cause depends on your stylesheet and PDF options.
Start by finding out what kind of gap you have
Before changing CSS, record your Puppeteer version, the browser version in use, the PDF options passed to page.pdf(), and the HTML and CSS around both tables. Compare the screen layout with the generated PDF, but account for the fact that Puppeteer renders PDFs with print media by default. See the Puppeteer Page.pdf documentation.
- Both tables are on one page: inspect the computed margins and padding on the tables and their immediate wrappers, including rules inside
@media print. - The whitespace coincides with a page transition: inspect page-break rules, print styles, page dimensions, and PDF margins. Changing cell spacing will not address page geometry.
This distinction is a troubleshooting guide, not a diagnosis of an unseen stylesheet. Use browser developer tools or temporary diagnostic CSS to identify which computed declaration creates the space.
Fix space between tables on the same page
Tables are block-level layout elements in common table layouts, so their own margins and those of surrounding blocks can contribute to visible separation. Vertical margins can also behave differently around page breaks; the CSS 2.2 paged-media rules describe how margins are handled in those circumstances.
#1 Best Overall
- Inspect each table’s computed
margin-topandmargin-bottom. - Inspect padding and margins on the parent or wrapper elements between and around the tables.
- Check whether
@media printoverrides the screen styles. Since PDF generation uses print media by default, those rules apply to the PDF. - Remove or normalize only the declaration responsible for the unwanted whitespace, then regenerate the PDF and check that intentional spacing elsewhere remains.
This CSS is a starting point to adapt to your selectors and verify in the generated file:
@media print {
.report-table {
margin-block: 0;
}
.report-table + .report-table {
margin-block-start: 0;
}
}Do not use border-spacing as the fix for space between two separate tables. Under the separate table border model, that property controls the distance between adjoining cell borders within a table; it does not set the distance between distinct table elements. See the CSS 2.2 table specification.
Fix whitespace that appears at a page boundary
Page fragmentation can depend on rules attached to the previous element, the next element, and their containing element. A forced break may take precedence over an instruction to avoid a break, so inspecting just one table’s CSS may not explain the result. The CSS 2.2 paged-media specification describes these interactions.
- Search the print stylesheet and relevant elements for
break-before,break-after,break-inside, and their legacypage-break-*counterparts. - Check the table immediately before the gap, the table after it, and any wrapper containing either table.
- Remove unintended forced breaks or revise avoid-break rules, then inspect all affected pages. A constraint that keeps a block together can move it if it cannot fit in the remaining page area.
Use modern fragmentation properties where appropriate. For example, this asks the browser to keep a section together when possible and to start a selected section on a new page:
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 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchRank #2
@media print {
.table-section {
break-inside: avoid-page;
}
.new-table-page {
break-before: page;
}
}Apply break-inside: avoid-page only to content that can reasonably fit on a page. If the element is taller than the available page area, test the result rather than assuming the rule will remove whitespace. MDN documents break-inside and its legacy alias relationship: page-break-inside: avoid is a legacy alias for break-inside: avoid.
Make CSS page size and PDF options agree
Page geometry can make content appear displaced or leave unexpected blank areas. Review CSS @page rules alongside the PDF API’s format, width, height, and margin options. Puppeteer’s PDFOptions documentation states that preferCSSPageSize defaults to false; when set to true, a CSS @page size takes priority over API width, height, or format values.
If CSS is meant to determine the paper dimensions, set preferCSSPageSize: true and ensure the API options do not conflict with those dimensions. If the API should determine page size, check that the @page rule is not introducing a different size. Adjust PDF margins deliberately: they affect the printable area, not the gap between cells inside a table.
For print layout details, Chrome for Developers explains page boxes, @page, and margin behavior in its 2024 overview of print margins.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Use print media deliberately when generating PDFs
Because page.pdf() uses print CSS by default, compare the actual print-media layout rather than relying only on a screen screenshot. Puppeteer documents page.emulateMediaType('screen') before page.pdf() as a way to generate using screen media. That can help establish whether print-only styles are responsible, but it also changes which CSS applies; use it as an intentional output choice, not as a universal spacing fix.
For a reliable comparison, generate one PDF with the default print media and another after explicitly selecting screen media. If only the print-media PDF has the gap, focus on print styles, page-break rules, and page geometry. If both have it, inspect shared margins and wrappers too.
Preserve table structure while testing workarounds
Avoid changing table parts such as rows or table headers to display: block as a blanket fix. A 2019 Stack Overflow discussion reports that a display change helped a row-break issue in one case, but also describes lost repeating headers and damaged column structure from related table display changes. That is an anecdotal report, not a general browser rule. See the community example.
Keep semantic table display values while debugging. If a minimal reproduction leads you to test a display override, compare multi-page output, repeated <thead> behavior, and column alignment before adopting it.
Free tools Windows power users keep installed
One-click scans. No signup required.
A quick diagnostic checklist
- Is the gap between elements on one page, or at a page transition?
- What are the computed table and wrapper margins and padding under print media?
- Are there print-only declarations that differ from the screen styles?
- Do break rules on the previous element, next element, or containing wrapper force or avoid a page break?
- Do CSS
@pagedimensions and PDF API dimensions agree, and are the margins intentional? - Does a proposed table display change preserve headers and column geometry across multiple pages?
Common troubleshooting failures
Changing cell spacing does not remove the gap between tables
Cause: border-spacing applies to cell borders within a table, not the distance between separate tables. Fix: inspect table and wrapper margins and padding instead.
The screen looks right but the PDF does not
Cause: PDF generation uses print media by default, so print-specific CSS may change margins, breaks, or dimensions. Fix: inspect computed styles with print media in mind; compare screen media only as a diagnostic or deliberate alternative.
A table jumps and leaves a large blank area
Cause: a forced break, an avoid-break constraint, or a rule on a containing element may affect pagination. Fix: inspect break declarations on both adjacent elements and their wrapper, then remove or revise the rule that is not intended.
The PDF has unexpected page dimensions or margins
Cause: CSS @page settings and API dimensions or margins may not reflect the same intended geometry. Fix: choose which source controls page size, align the options, and set preferCSSPageSize accordingly.
Best Value
- Used Book in Good Condition
Columns or repeated headers break after changing display values
Cause: changing table-part display behavior can disrupt table layout. Fix: restore semantic table display values unless a tested, minimal reproduction justifies the tradeoff.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need screenshots to inspect a page while debugging, ScreenshotNeo is a website screenshot API and MCP server. Its one-call API can return an image or PDF, and the parameter names used by other screenshot APIs also work. For Puppeteer-specific PDF layout debugging, keep using the checks above: the service is an alternative way to capture output, not a diagnosis of your stylesheet.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Set the URL to the page you want to capture. See the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. 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 free.
Frequently Asked Questions
Does page.pdf() use print CSS by default?
Yes. Puppeteer documents print media as the default for PDF generation.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsIs border-spacing the right property for space between two tables?
No. It controls spacing between adjoining cell borders under the separate border model, not the space between distinct table elements.
Should I set page.emulateMediaType('screen') to fix PDF spacing?
Not automatically. It changes the CSS media used for output and is best used to compare layouts or when screen-media output is intentional.
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.
