Render Options

The RenderOptions class is an immutable value object that controls how Chrome renders your HTML to PDF. Every setter returns a new instance, keeping your configuration predictable and side-effect free.

Creating Options

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

// Start with sensible defaults
$options = RenderOptions::create();

// Build up configuration fluently
$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
    ->setPrintBackground(true);

Applying Options

Pass the configured RenderOptions to HtmlRenderer::withOptions().

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

HtmlRenderer::create()
    ->loadHtml('<h1>Configured Output</h1>')
    ->withOptions($options)
    ->save('/output/configured.pdf');

Page Size

Set the paper format using standard format names.

$options = RenderOptions::create()
    ->setPageSize('A4');       // 210 x 297 mm (default)

Supported formats: A0--A6, B0--B6, Letter, Legal, Tabloid, Ledger.

Orientation

$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(true);      // 297 x 210 mm

Margins

Set individual margins in millimeters.

$options = RenderOptions::create()
    ->setMargins(
        top: 20,
        right: 15,
        bottom: 20,
        left: 15,
    );

When header or footer templates are enabled, the top and bottom margins define the space reserved for them.

Scale

Control the rendering scale factor. Values range from 0.1 to 2.0, with 1.0 as the default (100%).

// Shrink content to 80%
$options = RenderOptions::create()
    ->setScale(0.8);

// Enlarge content to 120%
$options = RenderOptions::create()
    ->setScale(1.2);

Headers and Footers

Chrome CDP supports HTML templates for headers and footers. Templates have access to special CSS classes that Chrome replaces with dynamic values at render time.

Available CSS Classes

CSS Class	Replaced With
.date	Formatted print date
.title	Document title
.url	Document URL
.pageNumber	Current page number
.totalPages	Total number of pages

Header Template

$options = RenderOptions::create()
    ->setDisplayHeaderFooter(true)
    ->setMargins(top: 25, right: 10, bottom: 20, left: 10)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; padding: 0 10mm; display: flex; justify-content: space-between;">
            <span>Acme Corp -- Confidential</span>
            <span class="date"></span>
        </div>
    ');

Footer Template

$options = RenderOptions::create()
    ->setDisplayHeaderFooter(true)
    ->setMargins(top: 15, right: 10, bottom: 25, left: 10)
    ->setFooterTemplate('
        <div style="font-size: 9px; width: 100%; text-align: center; color: #999;">
            Page <span class="pageNumber"></span> of <span class="totalPages"></span>
        </div>
    ');

Combined Header and Footer

$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 25, right: 15, bottom: 25, left: 15)
    ->setDisplayHeaderFooter(true)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; padding: 0 15mm; display: flex; justify-content: space-between; border-bottom: 1px solid #e0e0e0; padding-bottom: 5px;">
            <span style="font-weight: bold;">Quarterly Report</span>
            <span class="date"></span>
        </div>
    ')
    ->setFooterTemplate('
        <div style="font-size: 8px; width: 100%; padding: 0 15mm; display: flex; justify-content: space-between; color: #888;">
            <span>Acme Corporation</span>
            <span>Page <span class="pageNumber"></span> / <span class="totalPages"></span></span>
        </div>
    ');

Background Printing

By default, Chrome omits background colors and images (matching the browser print dialog behavior). Enable background rendering explicitly.

$options = RenderOptions::create()
    ->setPrintBackground(true);

CSS @page Rules

When enabled, CSS @page rules in your HTML override the page size and margins configured in RenderOptions.

$options = RenderOptions::create()
    ->setPreferCssPageSize(true);

Your HTML can then control the layout:

@page {
    size: A3 landscape;
    margin: 10mm;
}

Waiting for Content

Wait for a DOM Selector

Delay rendering until a specific element appears in the DOM. Useful when JavaScript generates content dynamically.

$options = RenderOptions::create()
    ->setWaitForSelector('#chart-rendered');

Timeout

Set the maximum time (in milliseconds) to wait for page load and rendering. Defaults to 30000 (30 seconds).

$options = RenderOptions::create()
    ->setTimeout(60000);    // 60 seconds for heavy pages

If the timeout is exceeded, a TimeoutException is thrown.

Complete Example

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$options = RenderOptions::create()
    ->setPageSize('Letter')
    ->setLandscape(false)
    ->setMargins(top: 25, right: 15, bottom: 25, left: 15)
    ->setScale(1.0)
    ->setPrintBackground(true)
    ->setDisplayHeaderFooter(true)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; text-align: center;">
            Internal Document -- Do Not Distribute
        </div>
    ')
    ->setFooterTemplate('
        <div style="font-size: 8px; width: 100%; text-align: center; color: #999;">
            <span class="pageNumber"></span> / <span class="totalPages"></span>
        </div>
    ')
    ->setWaitForSelector('.content-ready')
    ->setTimeout(45000);

HtmlRenderer::create()
    ->loadUrl('https://dashboard.example.com/export')
    ->withOptions($options)
    ->save('/exports/dashboard.pdf');

Next Steps

• HTML Renderer -- Loading content from strings, files, and URLs.
• Advanced Features -- PDF merging, CSS injection, screenshots.