Header in PDF page using DOMPDF in PHP

Header in PDF page using DOMPDF in PHP

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Adding Persistent Headers and Footers in DOMPDF

DOMPDF is a popular PHP library for rendering HTML and CSS into PDF documents. While it excels at converting standard web layouts, adding persistent headers and footers—information like page numbers, document titles, or dates that appear on every sheet—is not as straightforward as using a dedicated PDF generation API like TCPDF or mPDF. In DOMPDF, the default behavior strips most header and footer information unless explicitly configured via CSS or specific loader options.

To achieve this, you must leverage DOMPDF's internal support for @page rules within your stylesheet. This approach requires injecting custom CSS that defines the layout of the physical page media. The mechanism relies on the @page media query syntax, which allows you to specify margins and header/footer content for different page layouts.

You can define these rules by loading a custom stylesheet or by passing a string directly to the DOMPDF instance before rendering. The critical step is ensuring that your HTML document includes the corresponding CSS block that targets the @page rule. Here is a practical example of how to structure the CSS:

@page {
    size: A4;
    margin: 10mm;
}

@page :left {
    @top-left { content: "Document Title"; }
    @bottom-left { content: "Page "; counter-increment: page; content: string(page); }
}

@page :right {
    @top-right { content: "Current Date"; }
    @bottom-right { content: "Page "; counter-increment: page; content: string(page); }
}

In this snippet, the @top-left and @bottom-left pseudo-elements define where content should appear. The content property accepts a string or an object containing specific properties like counter-increment. When using counters for page numbers, you must initialize them in the HTML body with counter-reset: page; before referencing them in the CSS.

DOMPDF handles these rules by parsing the provided HTML and applying the calculated styles during the layout phase. However, there are significant limitations to keep in mind. Unlike TCPDF, where headers and footers can be defined programmatically within the class methods, DOMPDF relies heavily on external CSS or inline styles that adhere to its specific rendering engine. If you attempt to use complex JavaScript to dynamically generate header content, DOMPDF will likely ignore it, as it does not support client-side JavaScript execution in the same way a browser does.

Furthermore, the @page rule configuration only applies to pages that are explicitly loaded. If you are generating a single large HTML file that gets split into multiple PDF pages, the counters and layout rules should persist across those splits. However, if your source HTML contains conditional content or dynamic page breaks based on DOM manipulation, DOMPDF's static nature means it cannot reactively adjust headers mid-document without manual CSS overrides.

For projects built on Laravel, managing this configuration centrally can be tricky because DOMPDF requires the CSS to be present in the loaded HTML string. Some developers prefer to create a dedicated view file containing only the @page rules and include it via <style> tags before rendering the main content. This ensures that the header logic remains decoupled from the dynamic data being rendered.

If you require more robust control over headers, footers, and watermarks, you might consider switching to a library like TCPDF or mPDF, which offer built-in methods like setHeader() and setFooter(). Alternatively, the team at https://laravelcompany.com often discusses migration paths between PDF libraries in their technical resources, highlighting scenarios where DOMPDF's CSS-centric approach becomes a bottleneck for complex document requirements.

Ultimately, using DOMPDF for headers and footers demands a shift from procedural thinking to a stylesheet-first mindset. By mastering the @page pseudo-elements and ensuring your HTML structure supports CSS counters, you can generate professional-looking multi-page PDFs with consistent branding without needing external libraries.

Our network