October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix NowOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
CSS

How to Prevent Page Breaks Inside tbody with wkhtmltopdf

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For a table that must flow across PDF pages, leave the table breakable and apply page-break-inside: avoid to each tr, not the tbody or individual td elements:

table {
  page-break-inside: auto;
}

tr {
  page-break-inside: avoid;
  page-break-after: auto;
}

thead {
  display: table-header-group;
}

This is a workaround, not a guarantee. A historical wkhtmltopdf 0.12.2.4 build with patched Qt avoided splitting rows with the tr rule, while td did not. Other reports describe border artifacts, blank gaps and odd repeated headers. Test the exact wkhtmltopdf binary, Qt build, fonts, page size and HTML used in production.

Why a tbody rule does not keep rows together

tbody is a grouping element, but wkhtmltopdf’s WebKit-based pagination does not reliably treat it as an indivisible block. A 2018 issue report describes separate tbody elements with page-break-inside: avoid failing to keep related adjacent rows together. The rule may be accepted by the CSS engine while having no useful effect on the page-break decision.

There are two different layout requirements:

  • Keep one record intact: prevent a single row from being cut between pages. Start with tr { page-break-inside: avoid; }.
  • Keep several records together: keep two or more adjacent rows on the same page. The available reports do not establish a dependable CSS-only solution for this in wkhtmltopdf. A row rule protects each row individually, but does not reserve enough space for a group.

Do not confuse either requirement with allowing the table itself to continue onto the next page. Setting page-break-inside: avoid on the entire table can create large blank areas or force an oversized table into an undesirable position.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Epson EcoTank ET-2800 Wireless Color All-in-One Supertank Printer - Black
  • INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
  • LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
  • COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
  • ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
  • HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs

Use this baseline CSS first

Put the pagination rules in the stylesheet that wkhtmltopdf actually receives. Keep the table breakable, discourage a break inside each row, and mark the header as a repeating table header:

table {
  width: 100%;
  page-break-inside: auto;
}

tr {
  page-break-inside: avoid;
  page-break-after: auto;
}

thead {
  display: table-header-group;
}

tfoot {
  display: table-footer-group;
}

The tfoot declaration is useful only when you deliberately want a footer group to repeat; it does not solve row pagination. Keep borders, padding and line heights explicit while testing, because a row that is taller than the printable page cannot be kept intact by CSS.

Build a minimal reproducible test

  1. Record the renderer: run the same wkhtmltopdf executable used by your application and note its version, operating system and whether it uses patched Qt. The historical evidence is tied to particular builds, not to every package carrying the same version number.
  2. Reduce the HTML: create one table with a long tbody, realistic text wrapping and the same fonts and images as production. Remove JavaScript and unrelated layout until the break can be observed clearly.
  3. Set the page geometry: use the production paper size, margins, orientation and zoom. A row that fits on A4 portrait may not fit on Letter portrait or a narrower printable width.
  4. Render repeatedly: generate a PDF with the baseline CSS, inspect every page boundary and save the output. Repeat after changing only one rule so that a visual improvement can be attributed to that change.
  5. Test realistic extremes: include the longest cell, wrapped text, images, nested lists and rows near a page boundary. A short sample can appear correct while the real document still splits.

A simple command-line render can look like this, with your own input and output paths:

wkhtmltopdf input.html output.pdf

The command is not a compatibility test by itself; the important part is inspecting the produced PDF from the exact binary and document that will ship.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keeping multiple adjacent rows together

There is no reliable evidence that applying page-break-inside: avoid to a tbody keeps a selected group together. If two rows form one logical record, consider changing the markup so the content is represented by one row with multiple lines or cells. That gives wkhtmltopdf one row to protect instead of asking it to coordinate a group of rows.

Rank #2
Sale
Epson EcoTank Photo ET-8550 Wireless Wide-Format All-in-One Tank Printer
  • CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
  • INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
  • LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
  • PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
  • ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴

If separate rows are required, test a wrapper or grouping approach as an experiment, but treat it as build-specific. The 2018 report specifically found that separate tbody groups did not keep the desired rows together. Do not promise users that a group will remain on one page unless your production PDF tests demonstrate it.

Also account for the impossible case: if the combined group is taller than the printable page, no pagination declaration can place it intact. In that situation, reduce content, change orientation or margins, or accept a split.

Repeating headers without introducing new artifacts

thead { display: table-header-group; } is the usual first setting for repeating column headings. However, a wkhtmltopdf 0.12.4 issue report describes a header repeating on a page without the final data row, along with gaps and poor table breaks. Another report on 0.12.2.4 observed a header on the first page while the first row moved to the next page.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

When a repeated header overlaps content or appears by itself, render comparison PDFs with the header repetition enabled and disabled. In one issue context, changing thead to display: table-row-group suppressed repetition, but that necessarily removes the repeated-header behavior. Use that only when a non-repeating header is preferable to the artifact:

/* Diagnostic alternative: do not repeat the header */
thead {
  display: table-row-group;
}

Do not combine several pagination changes at once. First establish whether the defect is row splitting, header repetition, or a border drawn beyond the page; each symptom can require a different compromise.

Rank #3
HP Smart Tank 5000 Wireless All-in-One Ink Tank Printer, Scanner, Copier with 2 Years of Ink Included, Best-for-Home, Cartridge-Free, Refillable and AI-Enabled. (5D1B6A)
  • SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
  • INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
  • KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
  • PREMIUM SUPPORT - Strong technical expertise to solve issues faster
  • THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.

What to inspect at every page boundary

Goal or symptom First experiment What the reports establish
A single row is cut between pages tr { page-break-inside: avoid; } Worked in a historical 0.12.2.4 patched-Qt setup; not a universal guarantee.
Applying the rule to cells td { page-break-inside: avoid; } Did not prevent row breaks in that 0.12.2.4 report.
Several selected rows must stay together Model them as one row where possible; otherwise test the exact markup A 2018 grouped-tbody attempt failed to keep related rows together.
Header repeats incorrectly Compare table-header-group with a diagnostic non-repeating header Historical 0.12.2.4 and 0.12.4 reports describe orphaned or misplaced headers.
Vertical borders extend into blank space Inspect borders and page boundary after each CSS change Border artifacts were observed in an issue report; no universal fix was established.

Troubleshooting common failures

The row still splits

Confirm that the declaration reaches the generated HTML and is not overridden by a later stylesheet. Then verify that you are testing the expected executable, Qt build and page geometry. Replace unusually complex row content with plain text to determine whether an image, nested block or font metric is triggering the break. If the row is taller than the printable area, splitting is unavoidable.

The table leaves a large blank area

Look for page-break-inside: avoid applied to table or a large wrapper. Remove that restriction and keep page-break-inside: auto on the table. The goal is to protect rows while allowing the table to flow.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Rows move but the header is missing

Check that the header is valid table markup inside thead and that the header style is applied in the PDF-rendering stylesheet. Compare a minimal table with the production one. Repeating headers are a separate behavior from preventing row splits.

A header appears on a page by itself

Render a comparison without display: table-header-group. If the orphan disappears, decide whether the document is more useful with a non-repeating header or whether changing margins, row content or page size gives the repeating header enough room.

The PDF differs after an upgrade

Capture the old and new wkhtmltopdf version, Qt variant, operating system, fonts and command-line options. The cited issue tracker was archived in 2023, and its reports are historical examples rather than compatibility guarantees for current packages. Re-run the representative boundary tests before accepting the upgrade.

Rank #4
NDYIN Portable Printers Wireless for Travel, N80 Bluetooth Thermal Printer
  • Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
  • No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
  • Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
  • Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
  • The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Reliability and performance considerations

Pagination decisions depend on content measurement, so fonts, image dimensions, JavaScript timing and network-loaded assets can change where a row lands. Pin production fonts and assets where possible, wait for dynamic content before rendering, and include a long-table fixture in automated PDF checks. A visual diff or page-count check can catch regressions, but it cannot replace inspecting boundary cases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

There is no published success rate for these declarations. The Debian Stretch wkhtmltopdf manual describes page-break-inside as a partial remedy for WebKit cutting a line across pages, which is consistent with treating the rule as best-effort. If your business requirement is strict group-level pagination and repeated headers remain unstable after testing, evaluate a different HTML-to-PDF renderer rather than claiming that tbody CSS guarantees the result. No particular alternative renderer is established by the available reports.

Or skip the browser setup

If what you actually need is a clean screenshot or PDF of a public URL rather than control over wkhtmltopdf’s table pagination, ScreenshotNeo can capture it through one request. It accepts cookie and consent banners as a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and reports whether a response was billed. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. It does not make wkhtmltopdf’s tbody pagination rules deterministic; it is an alternative capture path when you do not need that browser setup.

See the ScreenshotNeo documentation for authentication and options. A basic request is:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

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}`);

The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account to try the capture path without entering a card.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Frequently Asked Questions

Can page-break-inside: avoid guarantee that every table row stays intact?

No. wkhtmltopdf treats the declaration as a partial, build-dependent remedy. Verify the generated PDF with the exact binary, Qt build and document used in production.

What should I change first when two related rows split apart?

Treat that as a group-pagination problem, not a single-row problem. If possible, represent the content as one table row; separate tbody groups have not reliably kept selected rows together.

Should I disable repeating headers when they look wrong?

Compare PDFs with and without thead { display: table-header-group; }. Disabling repetition can remove an orphaned header, but it also removes headings from later pages.

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Read next

Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.