@page Regeln praktisch nutzen: Seitenumbrüche, Ränder und Druckformate steuern

1. Was @page Regeln lösen, das media print nicht kann

Ein @media print Block steuert, wie einzelne Elemente aussehen, aber nicht, wie die Seite selbst als physisches Papierformat definiert ist. Genau hier setzen @page Regeln an: Sie legen fest, wie groß eine gedruckte Seite ist, wie breit ihre Ränder sind und was in den Randbereichen erscheint, unabhängig vom Inhalt des Dokuments. Ohne @page Regeln überlässt man Seitengröße und Ränder vollständig den Standardeinstellungen des Druckertreibers, was bei formalen Dokumenten wie Verträgen zu inkonsistenten Ergebnissen führt.

Für Rechnungen, Angebote und mehrseitige technische Reports sind @page Regeln deshalb keine Kür, sondern oft die einzige Möglichkeit, ein konsistentes Layout ohne serverseitige PDF-Bibliothek zu erreichen. Dieser Artikel geht tief in die Syntax von @page Regeln, von der Grundstruktur über benannte Seiten und Margin-Boxen bis zur automatischen Seitennummerierung mit CSS-Countern.

2. Grundsyntax: @page, size und margin

Die einfachste Form einer @page Regel definiert eine feste Seitengröße und einheitliche Ränder für das gesamte Dokument. Die Eigenschaft size akzeptiert entweder benannte Formate wie A4 und letter, explizite Maße wie 210mm 297mm, oder eine Ausrichtung wie landscape in Kombination mit dem Format. Die Eigenschaft margin funktioniert analog zum Box-Model-Margin, gilt aber für den gesamten bedruckbaren Bereich der Seite und nicht für ein einzelnes HTML-Element.

Wichtig zu verstehen: @page Regeln stehen außerhalb des normalen DOM-Baums, sie referenzieren kein einzelnes HTML-Element, sondern die vom User Agent erzeugten Seitenboxen selbst. Deshalb funktionieren normale CSS-Selektoren wie Klassen oder IDs innerhalb von @page nicht, stattdessen gibt es eigene Pseudo-Klassen und die spezielle Margin-Box-Syntax, die im weiteren Verlauf dieses Artikels erklärt werden.

/* Base @page rule: A4 with generous margins for print binding */
@page {
  size: A4;
  margin: 25mm 20mm 25mm 20mm; /* top right bottom left */
}

/* Landscape variant for wide data tables */
@page wide-report {
  size: A4 landscape;
  margin: 15mm;
}

/* Apply the named page to a specific section via HTML */
.data-table-section {
  page: wide-report;
}

3. Benannte Seiten für unterschiedliche Dokumentabschnitte

Ein einzelnes Dokument braucht selten überall dasselbe Seitenformat. Ein Deckblatt hat oft keine Ränder, der Hauptteil hat Standardränder, und ein Anhang mit breiten Tabellen profitiert von Querformat. Genau dafür bieten @page Regeln benannte Seiten: Mit @page reportcover { ... } wird eine eigene Seitendefinition erzeugt, die über die CSS-Eigenschaft page: reportcover; einem beliebigen HTML-Element zugewiesen wird. Sobald der Renderer dieses Element erreicht, wechselt er automatisch auf einen neuen Seitenumbruch mit den Eigenschaften der benannten Seite.

Diese Funktion von @page Regeln ist besonders wertvoll für automatisch generierte Reports, bei denen Deckblatt, Inhaltsverzeichnis und Anhang unterschiedliche Formate brauchen, aber aus derselben HTML-Quelle gerendert werden. Ohne benannte Seiten müsste man entweder mehrere separate Dokumente erzeugen oder auf eine dedizierte PDF-Bibliothek mit eigener Seitenverwaltung ausweichen.

/* Named page definitions for different document sections */
@page {
  size: A4;
  margin: 20mm;
}

@page cover {
  size: A4;
  margin: 0; /* full bleed cover, no margin */
}

@page appendix {
  size: A4 landscape;
  margin: 15mm 10mm;
}

/* Assign named pages to structural elements */
.cover-page   { page: cover; break-after: page; }
.report-body  { /* uses the default @page */ }
.appendix     { page: appendix; break-before: page; }

4. Pseudo-Klassen: first, left und right

@page Regeln unterstützen drei spezifische Pseudo-Klassen, die sich auf die Position der Seite im Dokument beziehen. @page :first gilt ausschließlich für die erste Seite und erlaubt zum Beispiel ein größeres Logo im Kopfbereich oder das komplette Weglassen der Seitennummer auf dem Deckblatt. @page :left und @page :right unterscheiden zwischen linken und rechten Seiten in einem doppelseitig gedruckten Dokument, was für Buchlayouts wichtig ist, bei denen der Bundsteg auf der Innenseite jeweils breiter sein muss als auf der Außenseite.

Die Kombination aus benannten Seiten und diesen Pseudo-Klassen erlaubt feingranulare @page Regeln wie @page report:first, die nur für die erste Seite eines bestimmten Abschnitts gelten. Die Browserunterstützung für :left und :right ist in Chromium-basierten Browsern über den Print-to-PDF-Renderer solide, in regulären Firefox- und Safari-Druckdialogen aber lückenhafter, weshalb ein Test in der Zielumgebung vor dem produktiven Einsatz Pflicht ist.

/* First page: larger top margin for a title block, no page number */
@page :first {
  margin-top: 60mm;
}

/* Left/right pages for double-sided book-style printing */
@page :left {
  margin-left: 30mm;  /* wider inner margin for binding */
  margin-right: 15mm;
}
@page :right {
  margin-left: 15mm;
  margin-right: 30mm; /* wider inner margin for binding */
}

5. Margin-Boxen: Kopf- und Fußzeilen mit @top-center

Der mächtigste Teil der @page Regeln-Spezifikation sind die sogenannten Margin-Boxen. Innerhalb einer @page Deklaration können bis zu 16 benannte Boxen definiert werden, darunter @top-left, @top-center, @top-right, @bottom-left, @bottom-center und @bottom-right. Jede dieser Boxen kann mit content gefüllt werden, entweder mit statischem Text oder mit CSS-Countern für dynamische Seitennummern, ganz ohne JavaScript.

In der Praxis werden Margin-Boxen für Firmenlogos in der Kopfzeile, für Dokumenttitel und für Seitennummerierung in der Fußzeile genutzt. Die Browserunterstützung für Margin-Boxen ist derzeit uneinheitlich: Chrome unterstützt sie über den nativen Print-to-PDF-Renderer inzwischen produktionsreif, während Firefox einen Teil der Boxen nur in neueren Versionen korrekt rendert. Ein robuster Einsatz von @page Regeln mit Margin-Boxen testet daher immer explizit in der tatsächlichen Zielumgebung, bevor die Funktion für Kunden freigeschaltet wird.

@page {
  size: A4;
  margin: 25mm 20mm 30mm 20mm;

  /* Header: company name left, document title centered */
  @top-left {
    content: "Mironsoft GmbH";
    font-size: 9pt;
    color: #555;
  }
  @top-center {
    content: "Rechnung Nr. 2026-0417";
    font-size: 9pt;
    font-weight: 600;
  }

  /* Footer: page numbering via counters, no JavaScript involved */
  @bottom-right {
    content: "Seite " counter(page) " von " counter(pages);
    font-size: 8pt;
    color: #777;
  }
}

6. Seitengrößen und Ausrichtung im Detail

Die Eigenschaft size innerhalb von @page Regeln unterstützt eine ganze Reihe standardisierter Formatnamen: A3, A4, A5, B4, B5, letter, legal und ledger sind die gängigsten. Zusätzlich lässt sich jedes Format explizit mit zwei Längenwerten definieren, etwa size: 148mm 210mm; für ein individuelles Format, das keinem Standard entspricht. Die Reihenfolge der Werte folgt dabei Breite vor Höhe, unabhängig von Ausrichtung.

Für die Ausrichtung existiert das Schlüsselwort landscape, das in Kombination mit einem Formatnamen die Höhen- und Breitenwerte vertauscht, ohne dass man die Maße manuell umrechnen muss. Ein wichtiger Praxishinweis für @page Regeln: Der Nutzer kann im Druckdialog des Browsers das Papierformat manuell überschreiben, was bedeutet, dass size eine Empfehlung ist, keine absolute Garantie. Für rechtssicheres Layout, bei dem die exakte Seitengröße kritisch ist, bleibt ein serverseitig gerenderter PDF-Export die zuverlässigere Alternative.

7. Seitennummerierung mit counter(page) und counter(pages)

CSS bringt zwei spezielle, implizit definierte Counter mit, die ausschließlich innerhalb von @page Regeln und ihren Margin-Boxen funktionieren: counter(page) gibt die aktuelle Seitenzahl aus, counter(pages) die Gesamtzahl der Seiten im Dokument. Beide Counter werden vom Renderer automatisch verwaltet, es ist keine manuelle Inkrementierung wie bei benutzerdefinierten CSS-Countern nötig. Die Kombination content: "Seite " counter(page) " von " counter(pages); ist das Standardmuster für eine vollständige Seitenangabe in der Fußzeile.

Ein subtiler Punkt bei @page Regeln mit benannten Seitenabschnitten: Wenn ein Dokument mehrere @page Definitionen mit unterschiedlichem page-name nutzt, kann mit der Funktion target-counter() in Kombination mit Seitenanker-Referenzen sogar auf die Seitenzahl eines anderen Elements verwiesen werden, etwa für ein automatisch generiertes Inhaltsverzeichnis mit korrekten Seitenzahlen. Diese fortgeschrittene Technik ist derzeit primär in spezialisierten Rendering-Engines wie Prince XML und Weasyprint vollständig implementiert, in regulären Browsern nur teilweise.

8. Browser-Unterstützung und Fallback-Strategien

Die Browserunterstützung für @page Regeln ist historisch fragmentiert gewachsen. Grundlegende Eigenschaften wie size und margin funktionieren in allen aktuellen Browsern zuverlässig. Margin-Boxen und die Pseudo-Klassen :left und :right sind dagegen inkonsistenter unterstützt, mit dem besten Support derzeit in Chromium-basierten Browsern. Ein sinnvoller Fallback ist, kritische Informationen wie Seitenzahlen zusätzlich im regulären Dokumentfluss zu platzieren, damit sie auch dann sichtbar sind, wenn eine Margin-Box in einem bestimmten Browser nicht gerendert wird.

Für Anwendungsfälle, in denen exakte, browserunabhängige Ausgabe kritisch ist, etwa bei rechtssicheren Rechnungen, empfiehlt sich der Einsatz einer dedizierten Rendering-Engine wie Prince XML, Weasyprint oder Paged.js, die @page Regeln vollständig und konsistent implementieren, unabhängig vom Browser des Endnutzers. Diese Werkzeuge rendern serverseitig und liefern ein PDF, statt sich auf den clientseitigen Druckdialog zu verlassen.

9. @page Regeln im Vergleich zu anderen Paginierungsansätzen

Je nach Anforderung an Konsistenz und Kontrolle gibt es unterschiedliche Wege, Seitengrößen und Nummerierung umzusetzen, mit @page Regeln als CSS-nativer Basisoption.

Reine @page Regeln im Browser eignen sich am besten für Fälle, in denen der Nutzer selbst über "Drucken" oder "Als PDF speichern" aktiv wird und geringe Abweichungen zwischen Browsern akzeptabel sind. Sobald ein System automatisiert PDFs für viele Nutzer gleichzeitig erzeugen muss, etwa monatliche Rechnungsläufe, verschiebt sich die Wahl klar in Richtung serverseitiger Rendering-Engines, die dieselben @page Regeln als Eingabe nutzen können, aber konsistente Ausgabe garantieren.

10. Zusammenfassung

@page Regeln erweitern das Druck-CSS um die fehlende Ebene der Seite selbst: feste Formate über size, individuelle Ränder über margin, unterschiedliche Layouts über benannte Seiten und die Pseudo-Klassen :first, :left und :right. Margin-Boxen wie @top-center und @bottom-right ermöglichen Kopf- und Fußzeilen inklusive automatischer Seitennummerierung über counter(page), komplett ohne JavaScript.

Die uneinheitliche Browserunterstützung bei Margin-Boxen bleibt der größte praktische Stolperstein bei @page Regeln. Für einfache, vom Nutzer selbst gedruckte Dokumente reicht die native Browserunterstützung meist aus, für automatisierte, rechtssichere PDF-Erzeugung in großem Maßstab ist eine dedizierte Rendering-Engine die robustere Wahl.

11. FAQ: @page Regeln praktisch nutzen