cfhtmltopdf

Last update:

May 18, 2026

<cfhtmltopdf> creates high quality PDF output from a text block containing CFML and HTML using the PDF Service Manager.

The WebKit implementation for <cfhtmltopdf> is referred as PDFG (acronym of PDF Generator) which is shipped as part of the Jetty installer. The component running inside the Jetty server is referred as the service manager, which takes request for PDF conversion from one or many ColdFusion server/s.

The WebKit implementation for <cfhtmltopdf>:

Encapsulates the PDF conversion library.
Performs HTML to PDF conversion in process.

The enhanced PDF engine in ColdFusion, version 2.0, is a powerful tool for converting HTML to high-quality PDF standards. It supports HTML5, CSS3, and JavaScript, allowing developers to create complex layouts and designs easily. The engine is particularly useful for generating professional-looking PDF documents without requiring extra coding beyond standard HTML usage.

View Enhanced PDF 2.0 in ColdFusion for more information.

Note:

Updates to PDFg service

Applies to:

ColdFusion (2025 release)
ColdFusion (2025 release) Update 1 and later
ColdFusion 2023 Update 13 and later
ColdFusion 2021 Update 19 and later

In the 2025 release, ColdFusion introduced IP-based filtering on the Jetty side. The `ipaccess` module has been enabled in the `start.ini` file. To implement this, add the `jetty-ipaccess.xml` file to the `etc` folder of the Jetty server. This file contains two sections: "white" and "black." The "white" section specifies the IPs that are allowed access, while the "black" section lists the IPs that are blocked.

It is important to implement IP filtering in your existing codebase; otherwise, it may not function as intended.

The following is a sample jetty-ipaccess.xml.

<?xml version="1.0"?>

<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<!-- =============================================================== -->

<!-- The IP Access Handler                                           -->

<!-- =============================================================== -->

<Configure id="Server" class="org.eclipse.jetty.server.Server">

   <Call name="insertHandler">

       <Arg>

           <New id="IPAccessHandler" class="org.eclipse.jetty.server.handler.IPAccessHandler">

               <Set name="white">

                   <Array type="String">

                       <Item>70.120.50.81</Item>

                       <Item>70.120.50.82</Item>

                       <Item>70.120.50.83</Item>

                   </Array>

               </Set>

               <Set name="black">

                   <Array type="String">

                       <Item>70.120.50.12</Item>

                       <Item>70.120.50.13</Item>

                       <Item>70.120.50.14</Item>

                   </Array>

               </Set>

               <Set name="whiteListByPath">false</Set>

           </New>

       </Arg>

   </Call>

</Configure>

Each <Item> represents the IP address of your ColdFusion server.

When you generate a PDF using HTML or CFML, you have to ensure that XSS vulnerabilities cannot be exploited. Hence, you must take relevant measures to protect your system against such vulnerabilities. Also, note that ColdFusion provides encoding functions for XSS protection. See the following functions:

History

ColdFusion (2025 release): The cfhtmltopdf tag supports the pre-filling of PDF forms, though the preview experience may vary by browser. Adobe Acrobat and Firefox handle pre-filled forms as expected, while Google Chrome and Microsoft Edge might show differences. These discrepancies occur because Chrome and Edge use custom PDF viewers that may not fully support certain dynamic features or JavaScript interactions within PDF forms.
ColdFusion (2016 release) Update 3 - Added the attribute language.

Syntax

encryption = "AES_128|RC4_40|RC4_128|RC4_128M|None"

source = "URL|pathname absolute or relative to web root"

destination = "filename"

conformance="PDF 2.0 supports the creation of PDF/A-1a or PDF/A-3a conformant files, as well as other PDF/A subformats."

language="language name"

marginBottom = "number"

marginLeft = "number"

marginRight = "number"

marginTop = "number"

name = "output variable name"

orientation = "portrait|landscape"

overwrite = "yes|no"

ownerPassword = "password"

pageHeight = "page height in inches(default)"

pageType = "page type"

pageWidth = "page width in inches(default)"

permissions = "permission list"

saveAsName = "PDF filename"

unit = "in|cm"

userPassword = "password"

HTML and CFML code

</cfhtmltopdf>

Attributes

Attribute	Req/Opt	Default	Description
encryption	Optional	none	AES_128 RC4_40 RC4_128 RC4_128M None
source	Required		URL of the source HTML document. In ColdFusion 11, an HTTP URL auto-redirects to an HTTPS URL. In ColdFusion 2016, enter the HTTPS URL manually as there will be no auto-redirects from HTTP to HTTPS.
conformance	Optional		The supported PDF/A conformance levels are PDF/A-1a, PDF/A-1b, PDF/A-2a, PDF/A-2b, PDF/A-2u, PDF/A-3a, PDF/A-3b and PDF/A-3u. For more information, view Enhanced PDF 2.0 in ColdFusion.
destination	Optional		Pathname of a file to contain the PDF output. If you omit the destination attribute, ColdFusion displays the output in the browser.
language	Optional	English	Document language.
marginBottom	Optional		Bottom margin in inches (default) or centimeters. To specify the bottom margin in centimeters, include the unit=cm attribute.
marginLeft	Optional		Left margin in inches (default) or centimeters. To specify the left margin in centimeters, include the unit=cm attribute.
marginRight	Optional		Right margin in inches (default) or centimeters. To specify the right margin in centimeters, include the unit=cm attribute.
marginTop	Optional		Top margin in inches (default) or centimeters. To specify the top margin in centimeters, include the unit=cm attribute.
name	Optional		Name of an existing variable into which the tag stores the PDF.
orientation	Optional	portrait	Page orientation: portrait landscape
overwrite	Optional	no	Specifies whether ColdFusion overwrites an existing file. Used in conjunction with the destination attribute.
ownerPassword	Optional		Specifies the owner password. Cannot be same as userPassword.
pageHeight	Optional		Page height in inches (default) or centimeters. This attribute is only valid if pagetype=custom. To specify page height in centimeters, include the unit=cm attribute.
pageType	Optional	letter	Page type into which ColdFusion generates the report: legal: 8.5 inches x 14 inches. letter: 8.5 inches x 11 inches. A4: 8.27 inches x 11.69 inches. A5: 5.81 inches x 8.25 inches. B4: 9.88 inches x 13.88 inches. B5: 7 inches x 9.88 inches. B4-JIS: 10.13 inches x 14.31 inches. B5-JIS: 7.19 inches x 10.13 inches. custom: custom height and width. If you specify custom , also specify the pageHeight and pageWidth attributes, can optionally specify margin attributes and whether the units are inches or centimeters.
pageWidth	Optional		Page width in inches (default) or centimeters. This attribute is only valid if pageType=custom. To specify page width in centimeters, include the unit=cm attribute.
permissions	Optional		(format="PDF" only) Sets one or more of the following permissions: AllowPrinting AllowModifyContents AllowCopy AllowModifyAnnotations AllowFillIn AllowScreenReaders AllowAssembly AllowDegradedPrinting AllowSecure All None Separate multiple permissions with commas.
saveAsName	Optional		The filename that appears in the SaveAs dialog when a user saves a PDF file written to the browser.
unit	Optional	in	Default unit for the pageHeight, pageWidth, and margin attributes: in: inches. cm: centimeters.
userPassword	Optional		Specifies a user password. Cannot be same as ownerPassword.

Note: <cfhtmltopdfItem> is added to support adding header/footer/pagebreak in the generated PDF. See The new <cfhtmltopdfitem> tag.

Refer to the kb doc Differences between cfdocument and cfhtmltopdf for more information.

Limitation: If you use cfhtmltopdf to convert an HTML page, that contains a form, to PDF, the resultant PDF will not contain the form fields. This is a limitation of the PDFg service, if PDFg is configured to run as a service. If you run PDFg from the command line, then the form fields will work as expected.

Examples

The following example shows the most basic usage of <cfhtmltopdf>, to create a PDF from CFML code, returning a PDF for display:

<cfhtmltopdf>

This is a test <cfoutput>#now()#</cfoutput>

</cfhtmltopdf>

The following example shows the most basic usage of <cfhtmltopdf>, to create a PDF from content returned from a URL, returning a PDF for display:

<cfhtmltopdf source="http://www.google.com/" />

The following example shows using options to control height, width, and save the content to a file instead of for display. The file is saved (by default) into the same directory as the template containing the code:

<cfhtmltopdf

  destination="usage_example.pdf" overwrite="yes"

  source="http://www.google.com/"

  unit="in" pageheight="8" pagewidth="4"

  pagetype="custom" />

The following example shows how you can set margins, and also adds code to display the resulting file to the user using CFContent:

<cfhtmltopdf destination="usage_example2.pdf"

  source="http://www.google.com" overwrite="true"  

  orientation="portrait"  pagetype="A4" margintop="1" marginbottom="1" 

  marginleft="1" marginright="1" />

<cfcontent file="#getdirectoryfrompath(getbasetemplatepath())#usage_example2.pdf" type="application/pdf" >

The following example shows how you can protect the PDF, requiring the user to enter a password to open the file:

<cfhtmltopdf destination="usage_example3.pdf " 

  source="http://www.google.com" overwrite="true"

  orientation="portrait"  pagetype="A4" margintop="1" marginbottom="1"

  marginleft="1" marginright="1" ownerpassword="owner" userpassword="user"

  encryption="RC4_128" permissions="AllowPrinting,AllowCopy" />

cfhtmltopdf

Category

History

See Also

Syntax

Attributes

Examples

More like this

On this page