User Guide Cancel

cfhtmltopdf

Last updated on Apr 8, 2025 | Also applies to ColdFusion

CFML Reference User Guide
ColdFusion functions
ColdFusion tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    1. cfchartdata
    2. cfchartseries
    3. cfchartset
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

<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" />

Get help faster and easier

New user?

cfhtmltopdf

Category

History

See Also

Syntax

Attributes

Examples

More like this

Get help faster and easier

Share this page

Ask the Community

Contact Us