Class PdfOptions
- Namespace
- CobaltPdf
- Assembly
- CobaltPdf.dll
Represents configuration options used when generating a PDF.
public class PdfOptions- Inheritance
-
PdfOptions
- Inherited Members
Remarks
Defines the input source, layout settings, and output behavior applied during PDF generation.
Properties
BypassCsp
Gets or sets whether to bypass the page's Content Security Policy (CSP). Required to be TRUE if injecting custom fonts or scripts into strict websites.
public bool BypassCsp { get; set; }Property Value
Cookies
Gets or sets the list of browser cookies to inject before the page navigates.
public List<CobaltCookie> Cookies { get; set; }Property Value
Remarks
Cookies with an explicit Domain are applied before the first navigation. Cookies without a domain are applied after the initial navigation, with the domain inferred from the final URL (after any HTTP redirects), and the page is then reloaded so the cookies are sent with the second request.
DisplayHeaderFooter
Returns true if either a header or footer template has been provided.
public bool DisplayHeaderFooter { get; }Property Value
Encryption
Gets or sets the encryption settings applied to the generated PDF.
public PdfEncryptionOptions? Encryption { get; set; }Property Value
Remarks
When specified, the generated PDF will be password-protected after rendering.
If null, the PDF will be generated without encryption.
ExtraHeaders
Gets or sets additional HTTP request headers sent with every request made by the browser (including the initial navigation and sub-resources). Values set here override any default headers Chromium would otherwise send.
public Dictionary<string, string> ExtraHeaders { get; set; }Property Value
FontDirectory
Gets or sets the path to a local directory containing custom font files to load during rendering.
public string? FontDirectory { get; set; }Property Value
Remarks
When set, CobaltPdf loads all font files from this directory and makes them available to the
rendered page. Supports common font formats recognised by Chromium (TTF, OTF, WOFF, WOFF2).
If the page enforces a strict Content Security Policy, set BypassCsp to true.
FooterTemplate
Gets or sets the HTML template used to render the page footer.
public string FooterTemplate { get; set; }Property Value
Remarks
The template must be valid HTML supported by Chromium's header/footer rendering engine.
This setting is only applied when DisplayHeaderFooter is enabled.
Grayscale
Gets or sets a value indicating whether the PDF should be rendered in grayscale.
public bool Grayscale { get; set; }Property Value
HeaderTemplate
Gets or sets the HTML template used to render the page header.
public string HeaderTemplate { get; set; }Property Value
Remarks
The template must be valid HTML supported by Chromium's header/footer rendering engine.
This setting is only applied when DisplayHeaderFooter is enabled.
Height
Gets or sets a custom page height as a CSS dimension string (e.g. "11in", "297mm").
public string? Height { get; set; }Property Value
Remarks
When set together with Width, overrides the PaperFormat setting. Useful for non-standard page sizes such as receipts, labels, or tickets.
HtmlContent
Gets or sets the raw HTML content to render as a PDF.
public string? HtmlContent { get; set; }Property Value
Remarks
When specified, the provided HTML is rendered directly. Cannot be used together with Url.
JavaScriptToRun
A custom JavaScript to execute on the page after the page is idle, but before the 'WaitStrategy' is applied.
public string? JavaScriptToRun { get; set; }Property Value
Landscape
Gets or sets a value indicating whether the PDF should be rendered in landscape orientation.
public bool Landscape { get; set; }Property Value
Remarks
Defaults to false (portrait orientation).
LazyLoad
Gets or sets the lazy loading configuration used when scrolling the page before rendering.
public LazyLoadOptions LazyLoad { get; set; }Property Value
Remarks
Lazy loading causes CobaltPdf to scroll the page by a set number of viewport-heights before
capturing the PDF. This triggers images and other content that only load when scrolled into view.
Leave PageCount as null (the default) to skip scrolling entirely.
LocalStorage
Gets or sets key/value pairs to write into the browser's localStorage before the page loads.
public Dictionary<string, string> LocalStorage { get; set; }Property Value
Remarks
Values are injected as an initialisation script so they are present before any page script executes.
If the target page enforces a strict Content Security Policy that blocks script injection,
set BypassCsp to true.
Margins
Gets or sets the PDF page margins. Defaults to 1cm. Use MarginOptions.None for no margins.
public MarginOptions Margins { get; set; }Property Value
MediaType
Gets or sets the CSS media type to emulate. Defaults to Screen.
public CssMediaType MediaType { get; set; }Property Value
Metadata
Gets or sets the descriptive metadata for the PDF document.
public MetadataOptions Metadata { get; set; }Property Value
OutputPath
Gets or sets the file path where the generated PDF should be saved.
public string? OutputPath { get; set; }Property Value
Remarks
If null, the PDF is returned in memory only.
PageRanges
Gets or sets the page ranges to include in the output PDF.
public string? PageRanges { get; set; }Property Value
Remarks
Uses a comma-separated list of page ranges, e.g. "1-3", "1,4,7", or "2-5,8".
When null (the default), all pages are included.
PaperFormat
Gets or sets the paper format used when rendering the PDF.
public string PaperFormat { get; set; }Property Value
Remarks
Defaults to "A4". Common values include "A4", "Letter", and "Legal".
PrintBackground
Gets or sets a value indicating whether CSS background graphics should be printed.
public bool PrintBackground { get; set; }Property Value
Remarks
Defaults to true. When disabled, background colors and images defined in CSS are not rendered.
ReloadAfterStorage
Gets or sets whether the page should be reloaded after storage values (localStorage / sessionStorage) have been injected on the initial load.
public bool ReloadAfterStorage { get; set; }Property Value
Remarks
When true, after the page has loaded and the storage init script has
run, the page is reloaded so that application code (e.g. React, Angular, Vue)
can read the storage values during its initialisation lifecycle.
Defaults to false.
Scale
Gets or sets the scale factor for the rendered PDF content.
public float? Scale { get; set; }Property Value
Remarks
Valid values range from 0.1 to 2.0.
Values below 1.0 shrink the content; values above 1.0 enlarge it.
Defaults to 1.0 (no scaling).
SessionStorage
Gets or sets key/value pairs to write into the browser's sessionStorage before the page loads.
public Dictionary<string, string> SessionStorage { get; set; }Property Value
Remarks
Values are injected as an initialisation script so they are present before any page script executes.
If the target page enforces a strict Content Security Policy that blocks script injection,
set BypassCsp to true.
Url
Gets or sets the URL to render as a PDF.
public string? Url { get; set; }Property Value
Remarks
When specified, the page at this URL is navigated to and rendered. Cannot be used together with HtmlContent.
UserAgent
Gets or sets the browser User-Agent string sent with every HTTP request. When null, Chromium's default User-Agent is used.
public string? UserAgent { get; set; }Property Value
WaitStrategy
The wait strategy to use after the page is idle and 'JavaScriptToRun' has executed. Defaults to WaitOptions.DefaultNetworkIdle.
public WaitOptions WaitStrategy { get; set; }Property Value
Watermark
Gets or sets the optional watermark configuration applied to the generated PDF.
public WatermarkOptions? Watermark { get; set; }Property Value
Remarks
When specified, the watermark is injected into the rendered page before PDF generation.
If null, no user-defined watermark is applied.
Width
Gets or sets a custom page width as a CSS dimension string (e.g. "8.5in", "200mm").
public string? Width { get; set; }Property Value
Remarks
When set together with Height, overrides the PaperFormat setting. Useful for non-standard page sizes such as receipts, labels, or tickets.