dompdf HTML to PDF - can't set margin of page

dompdf HTML to PDF - can't set margin of page

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

Stefan Bogdanescu

Founder & Senior Architect

DOMPDF Page Margins and CSS Box Model Conflicts

When working with DOMPDF to convert HTML into PDF, a common point of confusion arises when attempting to control page margins using standard CSS. Developers often expect @page rules or container padding to behave exactly as they do in web browsers. However, DOMPDF's rendering engine operates on a different set of principles regarding the box model and how it interprets pagination directives.

The core issue lies in the distinction between document-level styling and physical page layout settings. In your scenario, you are observing that the #wrapper padding is applied to the content area, but the @page margin rule is either being ignored or overridden by DOMPDF's internal defaults. This frequently happens because DOMPDF prioritizes its own default configuration for the physical page boundaries unless explicitly told otherwise via configuration arrays rather than CSS alone.

To understand why your current approach fails, we must look at how DOMPDF processes the @page rule. While standard CSS allows you to set margins on the @page selector like this:

@page {
    margin: 0.2in 0.5in 0.2in 0.5in;
}

DOMPDF often ignores these definitions if they conflict with its internal layout engine or if the CSS is not processed in the expected order relative to the configuration options passed during initialization. The @page rule in DOMPDF is specifically designed for physical page properties, but it can be superseded by the margin_left, margin_right, margin_top, and margin_bottom properties defined directly on the DOMPDF instance.

The most reliable method to enforce margins in DOMPDF is to configure them programmatically before loading your HTML. This bypasses potential CSS parsing ambiguities and ensures that the physical page boundaries are set exactly as required.

Here is the corrected PHP implementation pattern:

require_once("dompdf/dompdf_config.inc.php");

$dompdf = new DOMPDF();

// Explicitly set margins via configuration array
$dompdf->set_option('isHtml5ParserEnabled', true);
$dompdf->set_option('isPhpEnabled', false); // Optional, depending on needs
$dompdf->set_option('defaultFont', 'serif');

// Define the physical page margins
$dompdf->paperSize = 'A4';
$dompdf->marginTop = 20;        // 20mm top margin (approx 0.7in)
$dompdf->marginRight = 15;      // 15mm right margin
$dompdf->marginBottom = 20;     // 20mm bottom margin
$dompdf->marginLeft = 15;       // 15mm left margin

// Alternatively, use the shorthand array if using newer versions
// $dompdf->set_option('default_media_type', 'print'); 
// $dompdf->set_option('default_paper_size', 'letter');

$dompdf->loadHtml($html);
$dompdf->render();
$dompdf->stream("sample.pdf", array("Attachment" => false));

Note the shift from relying on @page CSS to using $dompdf->marginTop and related properties. This is a critical distinction: DOMPDF treats these configuration properties as the primary source of truth for page layout, effectively treating them as overrides to any conflicting CSS.

Additionally, be aware that setting margins purely via CSS on the <body> or <html> tags (e.g., body { margin-top: 40px; }) will often result in those margins being rendered inside the first page's content box rather than outside the physical page edge. DOMPDF renders the first page slightly differently to handle headers and footers, which can cause unexpected behavior when trying to push content away from the edges using standard block-level margin properties.

If you require complex layout logic where CSS margins must coexist with specific paper sizing, consider that DOMPDF 0.6.0 beta 3 may have limitations in how it resolves these conflicts compared to newer versions. In modern DOMPDF versions (v2.x), the configuration approach remains similar but offers more granular control over media types and page sizes.

For production environments requiring strict adherence to print standards, always prioritize setting margin options via the DOMPDF instance properties or the default_media_type option rather than relying on @page CSS rules. This ensures that your PDF output respects the physical boundaries of the paper regardless of how the HTML content is structured internally.

If you need further assistance with complex PDF generation workflows or specific integration patterns for Laravel applications, resources like https://laravelcompany.com can provide additional insights into managing third-party libraries within your project architecture.

Our network