<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: SlipKiln</title>
    <description>The latest articles on DEV Community by SlipKiln (@slipkiln).</description>
    <link>https://dev.to/slipkiln</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4256545%2F76094a87-c6e4-4195-9cd9-3c0a36eec393.jpg</url>
      <title>DEV Community: SlipKiln</title>
      <link>https://dev.to/slipkiln</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/slipkiln"/>
    <language>en</language>
    <item>
      <title>CSS page breaks for HTML-to-PDF: tables, headers, margins and backgrounds</title>
      <dc:creator>SlipKiln</dc:creator>
      <pubDate>Sat, 21 Nov 2026 01:48:29 +0000</pubDate>
      <link>https://dev.to/slipkiln/css-page-breaks-for-html-to-pdf-tables-headers-margins-and-backgrounds-3ebp</link>
      <guid>https://dev.to/slipkiln/css-page-breaks-for-html-to-pdf-tables-headers-margins-and-backgrounds-3ebp</guid>
      <description>&lt;p&gt;These rules work in Chromium-based renderers: Chrome's Print to PDF, Puppeteer, Playwright and APIs built on them, including SlipKiln. Older engines like wkhtmltopdf support less of this.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tables split across pages
&lt;/h2&gt;

&lt;p&gt;Long tables get rows cut in half at the page edge, and the header row appears only on page one. Two rules fix both:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="cm"&gt;/* Keep each row whole and repeat the header row on every page */&lt;/span&gt;
&lt;span class="nt"&gt;tr&lt;/span&gt;      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;break-inside&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;avoid&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="nt"&gt;thead&lt;/span&gt;   &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;display&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;table-header-group&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="nt"&gt;tfoot&lt;/span&gt;   &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;display&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;table-footer-group&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Chromium repeats a &lt;code&gt;&amp;lt;thead&amp;gt;&lt;/code&gt; on every printed page, so make sure your header row is actually in a &lt;code&gt;&amp;lt;thead&amp;gt;&lt;/code&gt;, not the first &lt;code&gt;&amp;lt;tr&amp;gt;&lt;/code&gt; of the body. A &lt;code&gt;break-inside: avoid&lt;/code&gt; row that is taller than a whole page still has to break somewhere; keep rows short.&lt;/p&gt;

&lt;h2&gt;
  
  
  Controlling where pages break
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="cm"&gt;/* Start each section on a new page */&lt;/span&gt;
&lt;span class="nc"&gt;.section&lt;/span&gt;       &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;break-before&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="nc"&gt;.section&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="nt"&gt;first-child&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;break-before&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;auto&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="cm"&gt;/* Don't split cards, figures or signature blocks */&lt;/span&gt;
&lt;span class="nc"&gt;.card&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nt"&gt;figure&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;.signature&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;break-inside&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;avoid&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="cm"&gt;/* Don't leave a heading alone at the bottom of a page */&lt;/span&gt;
&lt;span class="nt"&gt;h2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nt"&gt;h3&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;break-after&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;avoid&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="cm"&gt;/* At least 3 lines of a paragraph on each side of a break */&lt;/span&gt;
&lt;span class="nt"&gt;p&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;orphans&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;widows&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The older &lt;code&gt;page-break-before&lt;/code&gt;, &lt;code&gt;page-break-after&lt;/code&gt; and &lt;code&gt;page-break-inside&lt;/code&gt; properties still work as aliases. New code should use &lt;code&gt;break-*&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Page size and margins
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="k"&gt;@page&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;size&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Letter&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;          &lt;span class="cm"&gt;/* or A4, A5, "Letter landscape" */&lt;/span&gt;
  &lt;span class="nl"&gt;margin&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;18mm&lt;/span&gt; &lt;span class="mi"&gt;16mm&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="k"&gt;@page&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="nt"&gt;first&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;margin-top&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;30mm&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;   &lt;span class="cm"&gt;/* extra room for a letterhead */&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Watch out: many HTML-to-PDF tools pass a paper size to the renderer, and in Chromium that overrides your CSS &lt;code&gt;size&lt;/code&gt; unless the tool sets &lt;code&gt;preferCSSPageSize&lt;/code&gt;. With SlipKiln, set the size with &lt;code&gt;options.format&lt;/code&gt; (&lt;code&gt;A4&lt;/code&gt;, &lt;code&gt;A5&lt;/code&gt;, &lt;code&gt;Letter&lt;/code&gt;, &lt;code&gt;Legal&lt;/code&gt;) and &lt;code&gt;options.landscape&lt;/code&gt;, and margins with &lt;code&gt;options.margin&lt;/code&gt;, so your PDF comes out the same every time.&lt;/p&gt;

&lt;h2&gt;
  
  
  Backgrounds and colors disappear
&lt;/h2&gt;

&lt;p&gt;Browsers drop backgrounds when printing to save ink. SlipKiln turns &lt;code&gt;print_background&lt;/code&gt; on by default; in your own Chromium pass &lt;code&gt;printBackground: true&lt;/code&gt;. For individual elements:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="cm"&gt;/* Keep background colors and shaded rows in the PDF */&lt;/span&gt;
&lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;-webkit-print-color-adjust&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;exact&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;print-color-adjust&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;exact&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Fonts and images
&lt;/h2&gt;

&lt;p&gt;A server-side renderer only has the fonts installed on that machine, so text falls back to a default face. Embed fonts with &lt;code&gt;@font-face&lt;/code&gt; and a base64 &lt;code&gt;data:&lt;/code&gt; URL, and do the same for logos. SlipKiln requires this because its renderer has no network access; it also means your PDF never depends on a CDN being up.&lt;/p&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Header row inside &lt;code&gt;&amp;lt;thead&amp;gt;&lt;/code&gt;; &lt;code&gt;tr { break-inside: avoid }&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;break-before: page&lt;/code&gt; for sections, &lt;code&gt;break-after: avoid&lt;/code&gt; on headings&lt;/li&gt;
&lt;li&gt;Page size and margins set where your renderer actually reads them&lt;/li&gt;
&lt;li&gt;Backgrounds on, &lt;code&gt;print-color-adjust: exact&lt;/code&gt; for shaded rows&lt;/li&gt;
&lt;li&gt;Fonts and images inlined&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Want to try your HTML? The free plan renders 50 PDFs a month with no card: &lt;a href="https://slipkiln.com/docs/" rel="noopener noreferrer"&gt;POST /v1/render/html&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://slipkiln.com/guides/css-page-breaks-pdf.html" rel="noopener noreferrer"&gt;slipkiln.com&lt;/a&gt;. We build SlipKiln, an API that turns HTML or JSON into PDFs.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>css</category>
      <category>pdf</category>
      <category>webdev</category>
      <category>html</category>
    </item>
  </channel>
</rss>
