Class ChromePdfRenderOptions

Html To PDF output options for . Specifies options such as Paper-Size, DPI, Headers and Footers and other Chromium specific browser setup options.

Inheritance

System.Object

ChromePdfRenderOptions

Implements

IMargins

Namespace: IronPdf

Assembly: IronPdf.dll

Syntax

public class ChromePdfRenderOptions : Object, IHeaderFooter, IMargins

Constructors

ChromePdfRenderOptions()

Default Constructor. Creates a new instance of ChromePdfRenderOptions with default settings.

Declaration

public ChromePdfRenderOptions()

Fields

CustomCookies

Custom cookies for this HTML render. Cookies do not persist in between renders and must be set each time.

Declaration

public Dictionary<string, string> CustomCookies

Field Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.String>

HttpRequestHeaders

Custom HTTP request headers to be sent with the HTML

Declaration

public Dictionary<string, string> HttpRequestHeaders

Field Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.String>

PaperFit

A html-to-virtual paper setup manager allowing the developer to control how content will be laid out on PDF "paper" pages.

Include options for: Deafult Chrome Behavior, Zoomed, Responsive CSS3 Layouts, SCale-To-Page & Continuous Feed (e.g. reciept) style PDF page setups.

Declaration

public readonly VirtualPaperLayoutManager PaperFit

Field Value

Type	Description
VirtualPaperLayoutManager

Properties

AutoBookmarkCssSelectors

Optional CSS selectors to target specific elements for auto-bookmark generation. When set, only elements matching these selectors will be bookmarked instead of heading tags. Only used when AutoBookmarksFromHeadings is true.

Default value is null (use heading tags based on min/max level).

Declaration

public string[] AutoBookmarkCssSelectors { get; set; }

Property Value

Type	Description
System.String[]	Array of CSS selector strings, or null for heading-based selection

AutoBookmarkMaxHeadingLevel

The maximum HTML heading level to include when generating auto-bookmarks. Only used when AutoBookmarksFromHeadings is true.

Values are automatically clamped to the range 1–6. If set to a value less than AutoBookmarkMinHeadingLevel, the min is lowered to match, preserving the invariant Min ≤ Max.

Default value is 6 (h6).

Declaration

public int AutoBookmarkMaxHeadingLevel { get; set; }

Property Value

Type	Description
System.Int32	Maximum heading level (1-6). Default: 6

AutoBookmarkMinHeadingLevel

The minimum HTML heading level to include when generating auto-bookmarks. Only used when AutoBookmarksFromHeadings is true.

Values are automatically clamped to the range 1–6. If set to a value greater than AutoBookmarkMaxHeadingLevel, the max is raised to match, preserving the invariant Min ≤ Max.

Default value is 1 (h1).

Declaration

public int AutoBookmarkMinHeadingLevel { get; set; }

Property Value

Type	Description
System.Int32	Minimum heading level (1-6). Default: 1

AutoBookmarksFromHeadings

Automatically generate PDF bookmarks from HTML heading elements (h1–h6) during rendering. Bookmarks are created with proper hierarchy (h2 nested under h1, h3 under h2, etc.) and mapped to the correct rendered page locations.

Two modes are available:

1. Heading-tag mode (default): When AutoBookmarkCssSelectors is null, headings are located via post-render text search. This mode is convenient but inherently fragile — headings that span page breaks, headings whose source HTML differs from the rendered text (e.g. due to CSS transforms, ligatures, soft hyphens), or duplicate heading text may produce incorrect page mappings.

2. CSS-selector mode (recommended for reliability): When AutoBookmarkCssSelectors is set, IronPDF injects invisible anchor markers during rendering. This produces substantially more reliable page mappings and is the preferred approach for production documents. Passing new[] { "h1", "h2", "h3" } gives the same element selection as heading-tag mode with far better accuracy.

Default value is false.

Declaration

public bool AutoBookmarksFromHeadings { get; set; }

Property Value

Type	Description
System.Boolean	True to auto-generate bookmarks from headings, false to skip (default)

Examples

// Recommended: reliable CSS-selector mode
var options = new ChromePdfRenderOptions
{
 AutoBookmarksFromHeadings = true,
 AutoBookmarkCssSelectors = new[] { "h1", "h2", "h3" }
};

// Convenient but less reliable: heading-tag mode
var options = new ChromePdfRenderOptions
{
 AutoBookmarksFromHeadings = true,
 AutoBookmarkMaxHeadingLevel = 3  // Only h1, h2, h3
};

BrowserPool

Configuration for the browser tab pool, which reuses browser tabs across renders.

These settings are process-level — a single pool is shared across all instances. All renderers see the same BrowserPoolOptions instance.

Declaration

public BrowserPoolOptions BrowserPool { get; }

Property Value

Type	Description
BrowserPoolOptions

Examples

var renderer = new ChromePdfRenderer();

// Disable pooling
renderer.RenderingOptions.BrowserPool.Enabled = false;

// Or tune for a memory-constrained environment
renderer.RenderingOptions.BrowserPool.Enabled = true;
renderer.RenderingOptions.BrowserPool.MaxIdleTabs = 1;
renderer.RenderingOptions.BrowserPool.IdleTimeoutSeconds = 15;

CreatePdfFormsFromHtml

Turns all Html forms elements into editable PDF forms.

Default value is true.

Declaration

public bool CreatePdfFormsFromHtml { get; set; }

Property Value

Type	Description
System.Boolean

CssMediaType

Enables Media="screen" CSS Styles and StyleSheets

Note: By setting AllowScreenCss=false, IronPdf renders PDFs from HTML using CSS for media="print" as if printing a web page in a browser print dialog.

Default value is PdfCssMediaType.Screen.

Declaration

public PdfCssMediaType CssMediaType { get; set; }

Property Value

Type	Description
PdfCssMediaType

CustomCssUrl

Allows a custom CSS style-sheet to be applied to Html before rendering. May be a local file path or a remote url.

Declaration

public string CustomCssUrl { get; set; }

Property Value

Type	Description
System.String

Remarks

Only applicable when rendering Html to Pdf

CustomHyphenation

Custom hyphenation patterns. If set, this takes precedence over HyphenationLanguage.

Declaration

public CustomHyphenationDefinitions CustomHyphenation { get; set; }

Property Value

Type	Description
CustomHyphenationDefinitions

DefaultChrome

A ChromePdfRenderOptions preset with default settings that match the vanilla PDF viewer in Chrome.

These values are:
CssMediaType: Print, FirstPageNumber: 1, IronPdf.ChromePdfRenderOptions.FitToPaperMode: IronPdf.Engines.Chrome.FitToPaperModes.None, Top and left margin: 0.39 in, Bottom and Right margin: 0.38 in, PaperSize: A4, PaperOrientation: Portrait, PrintHtmlBackgrounds: false, IronPdf.ChromePdfRenderOptions.RenderDelay: 20

Declaration

public static ChromePdfRenderOptions DefaultChrome { get; }

Property Value

Type	Description
ChromePdfRenderOptions

ElementQuerySelectors

CSS selectors for elements whose rendered page locations should be queryable after rendering. After rendering, call PdfDocument.GetElementLocations() to retrieve the page index and coordinates of each matched element.

This enables power users to build custom bookmark logic or verify element placement.

Default value is null (no element location tracking).

Declaration

public string[] ElementQuerySelectors { get; set; }

Property Value

Type	Description
System.String[]

Examples

var options = new ChromePdfRenderOptions
{
ElementQuerySelectors = new[] { "h1", ".invoice-total", "[data-track]" }
};
var renderer = new ChromePdfRenderer { RenderingOptions = options };
var pdf = renderer.RenderHtmlAsPdf(html);
var locations = pdf.GetElementLocations();

EnableJavaScript

Enables JavaScript and Json to be executed before the page is rendered. Ideal for printing from Ajax / Angular Applications.

Also see IronPdf.ChromePdfRenderOptions.RenderDelay

Default value is true.

Declaration

public bool EnableJavaScript { get; set; }

Property Value

Type	Description
System.Boolean

EnableMathematicalLaTex

Enables Mathematical LaTeX Elements Rendering

Declaration

public bool EnableMathematicalLaTex { get; set; }

Property Value

Type	Description
System.Boolean

FirstPageNumber

First page number to be used in PDF Headers and Footers.

TextHeader

HtmlHeader

TextFooter

HtmlFooter

Default value is 1.

Declaration

public int FirstPageNumber { get; set; }

Property Value

Type	Description
System.Int32

ForcePaperSize

Force page sizes to be exactly what is specified via PaperSize by resizing the page after generating a PDF from HTML

Useful for bypassing CSS rules which specify paper size

Declaration

public bool ForcePaperSize { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

Helps correct small errors in page size when rendering HTML to PDF

GrayScale

Outputs a black-and-white PDF

Default value is false.

Declaration

public bool GrayScale { get; set; }

Property Value

Type	Description
System.Boolean

HtmlFooter

Sets the footer content for every PDF page as Html. Supports 'mail-merge'.

Declaration

public HtmlHeaderFooter HtmlFooter { get; set; }

Property Value

Type	Description
HtmlHeaderFooter

HtmlHeader

Sets the header content for every PDF page as Html. Supports 'mail-merge'.

Declaration

public HtmlHeaderFooter HtmlHeader { get; set; }

Property Value

Type	Description
HtmlHeaderFooter

HyphenationLanguage

Language for the hyphenation.

This feature is only active if 'hyphens: auto' is used in your CSS and this property is set to a specific language.

Default value is None, which disables the feature.

Declaration

public PdfHyphenationLanguage HyphenationLanguage { get; set; }

Property Value

Type	Description
PdfHyphenationLanguage

InputEncoding

The input character encoding as a string;

Default value is Encoding.UTF8.

Declaration

public Encoding InputEncoding { get; set; }

Property Value

Type	Description
System.Text.Encoding

Javascript

A custom javascript string to be executed after all HTML has loaded but before PDf rendering.

Declaration

public string Javascript { get; set; }

Property Value

Type	Description
System.String

JavascriptMessageListener

Method callback to be invoked whenever a browser JavaScript console message becomes available.

Declaration

public ChromeStringDelegate JavascriptMessageListener { get; set; }

Property Value

Type	Description
ChromeStringDelegate

MarginBottom

Bottom PDF "paper" margin in millimeters. Set to zero for border-less and commercial printing applications.

Default value is 25. However, this value will be ignored unless UseMarginsOnHeaderAndFooter is set to Bottom, TopAndBottom, or All.

Declaration

public double MarginBottom { get; set; }

Property Value

Type	Description
System.Double

MarginLeft

Left PDF "paper" margin in millimeters. Set to zero for border-less and commercial printing applications.

Default value is 25. This value is enabled by default, as UseMarginsOnHeaderAndFooter defaults to LeftAndRight. To explicitly disable, set UseMarginsOnHeaderAndFooter to a value that excludes Left.

Declaration

public double MarginLeft { get; set; }

Property Value

Type	Description
System.Double

MarginRight

Right PDF "paper" margin in millimeters. Set to zero for border-less and commercial printing applications.

Default value is 25. This value is enabled by default, as UseMarginsOnHeaderAndFooter defaults to LeftAndRight. To explicitly disable, set UseMarginsOnHeaderAndFooter to a value that excludes Right.

Declaration

public double MarginRight { get; set; }

Property Value

Type	Description
System.Double

MarginTop

Top PDF "paper" margin in millimeters. Set to zero for border-less and commercial printing applications.

Default value is 25. However, this value will be ignored unless UseMarginsOnHeaderAndFooter is set to Top, TopAndBottom, or All.

Declaration

public double MarginTop { get; set; }

Property Value

Type	Description
System.Double

MaxDynamicHFPagesPerBatch

Maximum number of dynamic header/footer pages rendered in a single browser tab.

When rendering PDFs with dynamic HTML headers or footers (containing page-specific content like {page} or {total-pages}), this property controls how many pages are batched per render.

Trade-off: Higher values = fewer render calls = faster, but higher peak memory per render. Lower values = less memory but more render calls.

Default value is 50. Minimum value is 1.

Declaration

public int MaxDynamicHFPagesPerBatch { get; set; }

Property Value

Type	Description
System.Int32

Remarks

Memory estimates depend on header/footer HTML complexity. Simple text headers use the lower end; headers with images, CSS, or complex layouts use the upper end.

This setting only affects dynamic headers/footers (those with placeholders like {page}, {total-pages}, {date}).

PaperOrientation

The PDF paper orientation. E.g. Portrait or Landscape.

Default value is Portrait.

Declaration

public PdfPaperOrientation PaperOrientation { get; set; }

Property Value

Type	Description
PdfPaperOrientation

PaperSize

Set an output paper size for PDF pages. System.Drawing.Printing.PaperKind.

Use SetCustomPaperSize(int width, int height) for custom sizes.

Default value is A4.

Declaration

public PdfPaperSize PaperSize { get; set; }

Property Value

Type	Description
PdfPaperSize

PrintHtmlBackgrounds

Prints background-colors and images from Html.

Default value is true.

Declaration

public bool PrintHtmlBackgrounds { get; set; }

Property Value

Type	Description
System.Boolean

RequestContext

Request context for this render. Determines isolation of certain resources such as cookies.

See RequestContexts for more information

Declaration

public RequestContexts RequestContext { get; set; }

Property Value

Type	Description
RequestContexts

TableOfContents

Generate a table of contents at the location in the HTML document where an element is found with id "ironpdf-toc".

Declaration

public TableOfContentsTypes TableOfContents { get; set; }

Property Value

Type	Description
TableOfContentsTypes

TextFooter

Sets the footer content for every PDF page as text. Supports 'mail-merge' and automatically turns urls into hyperlinks..

Declaration

public ITextHeaderFooter TextFooter { get; set; }

Property Value

Type	Description
IronPdf.ITextHeaderFooter

TextHeader

Sets the header content for every PDF page as text. Supports 'mail-merge' and automatically turns urls into hyperlinks..

Declaration

public ITextHeaderFooter TextHeader { get; set; }

Property Value

Type	Description
IronPdf.ITextHeaderFooter

Timeout

Render timeout in seconds

Default value is 60.

Declaration

public int Timeout { get; set; }

Property Value

Type	Description
System.Int32

Title

PDF Document Name and Title meta-data. Not required. Useful for mail-merge and automatic file naming in the IronPdf MVC and Razor extensions.

Declaration

public string Title { get; set; }

Property Value

Type	Description
System.String

UseMarginsOnHeaderAndFooter

Use margin values from the main document when rendering headers and footers.

This value is ignored when header and footer heights are autosized. Autosizing occurs when a header or footer MaxHeight value is null.

The default value is LeftAndRight. To apply margins on all edges, use All.

Declaration

public UseMargins UseMarginsOnHeaderAndFooter { get; set; }

Property Value

Type	Description
UseMargins

WaitFor

A wrapper object that holds configuration for wait-for mechanism for user to wait for certain events before rendering.

Declaration

public WaitFor WaitFor { get; set; }

Property Value

Type	Description
WaitFor

Remarks

By default, it will wait for nothing.

Methods

Clone()

Supports System.ICloneable. Creates a deep copy of this class instance.

Declaration

public object Clone()

Returns

Type	Description
System.Object	A deep clone of this instance. Use explicit casting to convert object back to the intended type.

SetCustomPaperSizeinCentimeters(Double, Double)

Set an output paper size for PDF pages. Dimensions are in Centimeters.

Declaration

public void SetCustomPaperSizeinCentimeters(double width, double height)

Parameters

Type	Name	Description
System.Double	width	Custom paper width in cm.
System.Double	height	Custom paper height in cm.

SetCustomPaperSizeInInches(Double, Double)

Set an output paper size for PDF pages. Dimensions are in Inches.

Declaration

public void SetCustomPaperSizeInInches(double width, double height)

Parameters

Type	Name	Description
System.Double	width	Custom paper width in Inches.
System.Double	height	Custom paper height in Inches.

SetCustomPaperSizeinMilimeters(Double, Double)

Set an output paper size for PDF pages. Dimensions are in millimeters.

Declaration

public void SetCustomPaperSizeinMilimeters(double width, double height)

Parameters

Type	Name	Description
System.Double	width	Custom paper width in millimeters.
System.Double	height	Custom paper height in millimeters.

SetCustomPaperSizeinPixelsOrPoints(Double, Double, Int32)

Set an output paper size for PDF pages. Dimensions are in screen Pixels or printer Points.

Declaration

public void SetCustomPaperSizeinPixelsOrPoints(double width, double height, int DPI = 96)

Parameters

Type	Name	Description
System.Double	width	Custom paper width in pixels/points.
System.Double	height	Custom paper height in pixels/points.
System.Int32	DPI	Intended print resolution of the PDF. To be clear PDFs have no fixed DPI/PPI value for rendering. 72 and 96 are common onscreen values. 300 is a comon value used in commercial printing.

Implements

IMargins