Table of Contents

Class PdfOptions

Namespace
CobaltPdf.WebKit
Assembly
CobaltPDF.WebKit.dll

Configuration options used when generating a PDF.

public class PdfOptions
Inheritance
PdfOptions
Inherited Members

Fields

DefaultUserAgent

Modern desktop Chrome User-Agent applied by default (see UserAgent).

public const string DefaultUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"

Field Value

string

Properties

BypassCsp 

public bool BypassCsp { get; set; }

Property Value

bool

Cookies 

public List<CobaltCookie> Cookies { get; set; }

Property Value

List<CobaltCookie>

DisplayHeaderFooter 

public bool DisplayHeaderFooter { get; }

Property Value

bool

Encryption 

public PdfEncryptionOptions? Encryption { get; set; }

Property Value

PdfEncryptionOptions

ExtraHeaders 

public Dictionary<string, string> ExtraHeaders { get; set; }

Property Value

Dictionary<string, string>

FontDirectory 

public string? FontDirectory { get; set; }

Property Value

string

FooterTemplate 

public string FooterTemplate { get; set; }

Property Value

string

Grayscale 

public bool Grayscale { get; set; }

Property Value

bool

HeaderTemplate 

public string HeaderTemplate { get; set; }

Property Value

string

Height 

public string? Height { get; set; }

Property Value

string

HtmlContent 

public string? HtmlContent { get; set; }

Property Value

string

ImageJpegQuality

JPEG quality used by OptimizeImages. Default 85.

public int ImageJpegQuality { get; set; }

Property Value

int

JavaScriptToRun 

public string? JavaScriptToRun { get; set; }

Property Value

string

Landscape 

public bool Landscape { get; set; }

Property Value

bool

LazyLoad 

public LazyLoadOptions LazyLoad { get; set; }

Property Value

LazyLoadOptions

LocalStorage 

public Dictionary<string, string> LocalStorage { get; set; }

Property Value

Dictionary<string, string>

Margins 

public MarginOptions Margins { get; set; }

Property Value

MarginOptions

MediaType

CSS media type to emulate. Defaults to Screen, matching the Chromium-based CobaltPDF default so a "uninstall CobaltPDF, install CobaltPDF.WebKit" migration produces visually identical output. Set to Print to activate @media print rules — most modern sites use them to strip navigation, ads, and sticky banners, matching Chrome's "Save as PDF" behaviour.

public CssMediaType MediaType { get; set; }

Property Value

CssMediaType

Metadata 

public MetadataOptions Metadata { get; set; }

Property Value

MetadataOptions

OptimizeFonts

Dedupe identical font streams and re-subset each through fontTools to strip unused TTF tables (DSIG, LTSH, VORG, kern, GPOS, …) and non-essential name records. Default true — matches what Chrome's PDF backend does. Saves 50-90% of font bytes for typical pages.

public bool OptimizeFonts { get; set; }

Property Value

bool

OptimizeImages

Re-encode every embedded image as JPEG in a post-processing pass, matching what Chrome's PDF backend does natively. Default true — brings image-heavy pages (news sites, dashboards) from ~50 MB down to ~3-5 MB. Quality 85 = no visible loss at normal viewing zoom. Set to false if you need byte-identical reproduction of source images.

public bool OptimizeImages { get; set; }

Property Value

bool

OutputPath 

public string? OutputPath { get; set; }

Property Value

string

PageRanges 

public string? PageRanges { get; set; }

Property Value

string

PaperFormat 

public string PaperFormat { get; set; }

Property Value

string

PrintBackground 

public bool PrintBackground { get; set; }

Property Value

bool

ReloadAfterStorage 

public bool ReloadAfterStorage { get; set; }

Property Value

bool

Scale 

public float? Scale { get; set; }

Property Value

float?

SessionStorage 

public Dictionary<string, string> SessionStorage { get; set; }

Property Value

Dictionary<string, string>

SkipPostProcessing

When true, skip the entire post-processing pipeline (pikepdf, fontTools, PIL) and emit the PDF that the engine wrote directly. Set by CobaltEngine.WithoutPostProcessing().

Trade-off:

  • Saves ~30 MB of peak RSS per render and renders faster — useful on memory-constrained hosts (small Azure plans, tight containers).
  • Produces ~70% larger PDFs because fonts are embedded whole instead of subset to used glyphs, images aren't re-encoded, and there's no font deduplication.
  • Watermark / encryption / metadata / OptimizeImages / OptimizeFonts are all implemented by the post-processing pipeline, so they are ignored while it is skipped.

Default false: optimised output (smaller files) wins for typical "render → store → ship" workflows. Set true only when the PDF is transient (preview, in-memory stream) and memory is the bottleneck.

public bool SkipPostProcessing { get; set; }

Property Value

bool

Url 

public string? Url { get; set; }

Property Value

string

UserAgent

User-Agent string sent for the render. Defaults to a modern desktop Chrome UA (DefaultUserAgent). This matters: WebKitGTK's built-in User-Agent causes many modern sites (news sites, SPAs, etc.) to serve a degraded or empty JS-skeleton, which renders as a BLANK PDF. A mainstream UA makes them serve the full desktop experience — the same one Chromium gets. Override with WithUserAgent(...); set to null/empty to fall back to WebKitGTK's own UA.

public string? UserAgent { get; set; }

Property Value

string

ViewportHeight

Render viewport height in CSS pixels. Rarely needed — the engine uses a deliberately tall internal viewport to trigger lazy-loaded content. When set, raises the floor on that internal height.

public int? ViewportHeight { get; set; }

Property Value

int?

ViewportWidth

Render viewport width in CSS pixels. Defaults to 1280 — a standard desktop width, so responsive sites serve their full DESKTOP layout (the wide render is then scaled to fit the paper). A narrower default made desktop sites collapse to the left / render their mobile layout. Lower it (e.g. 1024) for a narrower layout, or raise it for very wide designs.

public int? ViewportWidth { get; set; }

Property Value

int?

WaitStrategy 

public WaitOptions WaitStrategy { get; set; }

Property Value

WaitOptions

Watermark 

public WatermarkOptions? Watermark { get; set; }

Property Value

WatermarkOptions

Width 

public string? Width { get; set; }

Property Value

string