Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Put the break in the HTML you pass to generatePDF. The package does not document a separate page-break option, so use print CSS: page-break-before or break-before on the element that must start a new page, page-break-after or break-after for a break after a section, and page-break-inside: avoid or break-inside: avoid for content that should stay together.
This works within the limits of the native iOS and Android WebView PDF pipelines. A block taller than one page cannot be kept intact, and tables, nested containers, margins and platform versions need testing with the exact HTML and dimensions used by your app.
Where page-break CSS belongs
react-native-html-to-pdf converts an HTML string to a PDF document. Its documented generatePDF options include html, fileName, base64, directory, height and width, with additional iOS padding and Android font settings. Because the input is HTML, put the pagination rules inside a <style> element in that string.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →const html = `
Chapter 1
Introductory content.
Chapter 2
Summary
Short grouped content.
Chapter 3
`;
const file = await generatePDF({
html,
fileName: 'report',
directory: 'Documents',
base64: false,
width: 595,
height: 842
});The legacy page-break-* properties are retained for compatibility; the modern break-* aliases provide progressive enhancement. CSS 2.1 defines the before and after properties as controls that force a break before or after a generated box.
#1 Best Overall
Force a new page before a heading
Apply page-break-before: always to the heading (or a wrapper) that should move to the next page. The heading remains attached to its following content when you also use page-break-after: avoid.
<h2 class="chapter-start">Chapter 2</h2>
.chapter-start {
page-break-before: always;
break-before: page;
page-break-after: avoid;
break-after: avoid;
}Force a break after a section
Use an empty divider when the preceding section must end a page. It is often clearer than putting the rule on the next heading when that heading is generated conditionally.
<section>...chapter content...</section>
<div class="page-break-after" aria-hidden="true"></div>Keep cards, figures and rows together
page-break-inside: avoid asks the renderer not to split an element. Add break-inside: avoid as the modern equivalent.
.invoice-card,
figure,
.keep-together {
page-break-inside: avoid;
break-inside: avoid;
}
table {
width: 100%;
border-collapse: collapse;
}
thead { display: table-header-group; }
tfoot { display: table-footer-group; }
tr {
page-break-inside: avoid;
break-inside: avoid;
}
This is a request, not an unlimited guarantee. If a card, row or paragraph is taller than the printable page, it must be split or overflow. Reduce padding and font size, split the data into smaller blocks, or insert a deliberate break before the oversized item. Test nested containers separately: native WebView pagination can treat a table, a row and a surrounding flex or block differently.
Rank #2
Why page-break-before can appear to be ignored
The rule is on the wrong box
Place the rule on the element that should move, not only on an ancestor whose layout may be flattened. Try a simple block-level heading or wrapper first.
The element is already at a page boundary
A forced break has no visible effect when the previous content naturally ended the page. Add a temporary border or background and a short preceding paragraph to verify the fixture.
CSS was not included in the HTML string
React Native stylesheets do not style the HTML document. Put the complete rule inside the string passed as html, and confirm that the generated string contains it before calling generatePDF.
The content cannot fit
avoid cannot preserve an element taller than a page. Split long tables, images and cards; set explicit image dimensions; and avoid placing large fixed-height containers inside an avoid group.
Rank #3
WebView pagination differs by platform
The package uses native rendering rather than a fully documented CSS fragmentation engine. Android and iOS releases can therefore produce different results, especially for margins, nested tables and complex layout. The project issue tracker includes reports about margins when content spills to the next page and an Android WebView AwPrintDocumentAdapter/AwPdfExporter failure path. A CSS fix cannot repair a native exporter failure.
A reliable test fixture and workflow
- Create a minimal fixture. Include one forced-before heading, one forced-after divider, one short
avoidcard, a long paragraph and a table with enough rows to cross a page. - Use production dimensions. Pass the same
height,width, margins, fonts and image assets as the real document. A break can move when the printable area changes by only a few pixels. - Generate on every supported platform. Inspect PDFs from each iOS and Android version you ship, not just the simulator or one WebView release.
- Check boundary cases. Look for stranded headings, clipped content, split rows, missing images, unexpected blank pages and margins applied only after a spill.
- Adjust structure, not just CSS. Move a break to a wrapper, reduce an oversized block, or divide a long table when an avoid rule cannot be honored.
- Pin and regress. The npm registry lists
react-native-html-to-pdfversion 1.3.0 (observed in 2026) with built-in TypeScript declarations. Pin the version you validate and keep the fixture as a regression test when upgrading.
Handling tables, images and long documents
Tables
Repeat table headers with thead { display: table-header-group; } where the native renderer honors that display value. Keep individual rows short and apply avoid to rows, but do not expect a multi-page row to remain whole. If a row contains a large image or long unbroken text, constrain it before pagination.
Images
Give images explicit width and height (or a predictable max-width) so layout is known before pagination. A large image can force a blank-looking page when it cannot fit below a heading. Place a deliberate break before it or scale it to the printable width.
Free tools Windows power users keep installed
One-click scans. No signup required.
Long paragraphs
Allow ordinary paragraphs to flow. Applying avoid to every paragraph can create excessive whitespace and still cannot keep a paragraph that exceeds one page intact.
Rank #4
Fixed dimensions and margins
Check the interaction between CSS margins and the height/width options. A content area that is effectively larger than the page can cause overflow or an extra page. The package’s documented options do not include a page-break-specific switch; pagination remains an HTML/CSS and native-renderer concern.
Complete TypeScript example
import { generatePDF } from 'react-native-html-to-pdf';
export async function makeReport() {
const html = `
<!doctype html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
@page { margin: 28px; }
body { font-family: Arial, sans-serif; font-size: 12px; }
.new-page { page-break-before: always; break-before: page; }
.end-page { page-break-after: always; break-after: page; }
.keep { page-break-inside: avoid; break-inside: avoid; }
h2 { page-break-after: avoid; break-after: avoid; }
table { width: 100%; border-collapse: collapse; }
th, td { border: 1px solid #bbb; padding: 6px; }
thead { display: table-header-group; }
tr { page-break-inside: avoid; break-inside: avoid; }
img { max-width: 100%; height: auto; }
</style>
</head><body>
<h1>Report</h1>
<p>Overview...</p>
<h2 class="new-page">Details</h2>
<div class="keep"><h3>Key result</h3><p>...</p></div>
<table><thead><tr><th>Item</th><th>Value</th></tr></thead>
<tbody><tr><td>A</td><td>1</td></tr></tbody>
</table>
<div class="end-page"></div>
<h2>Appendix</h2>
</body></html>`;
return generatePDF({
html,
fileName: 'report',
directory: 'Documents',
base64: false,
width: 595,
height: 842,
});
}Troubleshooting checklist
| Symptom | Likely cause | Fix |
|---|---|---|
| Break has no effect | Rule is absent from the HTML string or attached to an ineffective wrapper. | Inspect the generated string; apply both legacy and modern properties to a block-level target. |
| Heading is stranded at the bottom | No keep-with-next behavior. | Set page-break-after: avoid on the heading and move the break to the heading when necessary. |
| Card or row still splits | Content is taller than a page, or nested layout is not honored. | Reduce its height, split it, simplify nesting, and test the platform-specific renderer. |
| Unexpected blank page | Two forced breaks, a large fixed-height element, or margins exceeding the printable area. | Remove duplicate breaks, eliminate fixed heights, and recalculate margins. |
| Only Android fails | WebView PDF export plumbing rather than CSS. | Reproduce on the target Android WebView; check exporter/device issues separately from the HTML fixture. |
| Margins change after a spill | Native pagination behavior around overflow. | Use explicit page margins, simplify the boundary content, and retain a regression PDF for each platform. |
When a different renderer is justified
If native WebView output cannot meet your requirements, compare engines on CSS fragmentation support, table and image pagination, JavaScript execution, native platform coverage, licensing and operating cost. PDFreactor documents manual-break examples and support for CSS 2.1 page-break-before and page-break-after; it is a commercial alternative, so verify current licensing and availability directly before adopting it. No independent performance or compatibility rate is established for the package, so choose based on reproducible fixtures rather than an assumed success percentage.
Or skip the browser setup
If your real goal is a reliable screenshot or PDF of a URL rather than a PDF generated inside the mobile app, ScreenshotNeo provides a single HTTP request and an MCP server for AI agents. It accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status.
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 API documentation for all options, including full-page capture with lazy images, CSS-selector elements, dark mode, 12 device presets and custom viewports, retina scale, PDF paper size and page ranges, custom CSS and JavaScript, clicks, selector or network-idle waits, request and resource blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed image links, async webhooks, 100-URL bulk calls, usage data and the OpenAPI specification. The parameter names used by other screenshot APIs also work, which can simplify migration.
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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. Every plan includes every feature. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, with yearly billing giving two months free. Create a free ScreenshotNeo account to try it.
Frequently Asked Questions
Does react-native-html-to-pdf have a page-break option in generatePDF?
The documented options do not include one. Put page-break CSS in the HTML string passed to generatePDF.
Can page-break-inside: avoid prevent every table row from splitting?
Only when the row fits in the available page area and the native renderer honors the rule. Oversized rows must be split or redesigned.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why should both page-break-* and break-* be specified?
The page-break properties provide legacy compatibility while break-* is the modern paged-media syntax; using both improves coverage across native WebView versions.
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.
