Fillable form fields

Turn a rendered document into a form: application forms, order sheets, consent forms and contracts with a place to sign. The reader fills the fields in their PDF viewer and can save or submit the result.

<p>Name: {{{pdfFormField name="name" type="text" width="200px" height="20px" value=user.name}}}</p>
<p>Plan: {{{pdfFormField name="plan" type="combo" width="120px" height="20px" items=plans}}}</p>
<p>{{{pdfFormField name="agree" type="checkbox" width="14px" height="14px"}}} I agree</p>
<p>Signature: {{{pdfFormField name="sign" type="signature" width="200px" height="40px"}}}</p>

With the data { "user": { "name": "Ada Lovelace" }, "plans": ["Basic", "Pro"] }, the name box starts filled in and the list offers both plans.

pdfFormField works in an HTML template’s Handlebars source. Print it with triple braces. The field sits inline in the text where you print it, at the size you give.

Pick the field type

type	Adds
text	A text box. Add multiline=true for several lines, password=true to hide the text.
checkbox	A check box.
combo	A drop-down list of items.
button	A push button that submits or resets the form.
signature	An empty signature field the reader signs in their viewer.

A signature field is only a place to sign. To sign the document with your own certificate when it renders, see PDF standards and signatures.

Arguments

Every field needs name, type, width and height. Sizes are in px, such as width="200px".

Argument	Applies to	What it does
name	all	The field’s name, which a submitted form sends its value under.
value, defaultValue	text, combo, checkbox	The value it starts with, and the value a reset restores.
label	all	The text a screen reader announces, and a button’s caption. Without it, the name is used.
fontFamily, fontSize	all but checkbox	One of the 14 standard PDF fonts, such as Helvetica (the default), Times-Roman or Courier, and a size in px. Without fontSize, the viewer fits the text to the field.
color	all	The text color, or a check box’s mark, as #rrggbb, #rgb or rgb(r, g, b).
backgroundColor	all	The fill color, in the same forms.
border	all	Three numbers separated by commas: horizontal and vertical corner radius, then width. "0,0,1" draws a thin border. No border by default.
textAlign	all	left (the default), center or right.
readOnly, required, noExport	all	true makes the field read-only, required, or left out when the form is submitted.
multiline, password	text	true allows several lines, or hides what the reader types.
items	combo	The choices, as an array from your data or a string separated by commas, such as "Basic,Pro". Required.
visualType	checkbox	check (the default) draws a check mark, square a filled square.
action, url	button	submit sends the form to url; reset restores every field’s defaultValue.

Write true without quotes, as in readOnly=true. A quoted "true" is ignored.

A comma-separated items string is split at each comma as is, so leave out spaces after the commas or they become part of the choice.

Check box values

A check box is ticked when its value (or, without one, its defaultValue) is true or any other value except false, 0, an empty string, "false", "0", "off" or "no". Pass a field from your data, as in value=order.giftWrap.

Submit options

A submit button also takes these arguments, each set to true to turn it on: exportFormat, getMethod, XFDF, submitPDF, includeNoValueFields, includeAnnotations, includeAppendSaves, submitCoordinates, canonicalFormat, exclNonUserAnnots, excldFKEy and embedForm. They are the PDF submit-form flags; without any, the viewer sends the values as FDF.

Format what the reader types

A text field can format its value as the reader types, in viewers that run form scripts, such as Adobe Acrobat Reader. Set formatType and the arguments that go with it:

formatType	Arguments
date	formatMask: a date pattern such as "dd/mm/yyyy" (mm is the month).
time	formatMask: "HH:mm", "hh:mm", "HH:mm:ss" or "hh:mm:ss".
number	formatFractionalDigits (0 to 10, default 0), formatSepComma=true for thousands separators, formatNegStyle (default MinusBlack), formatCurrency (a symbol such as "€") and formatCurrencyPrepend=false to put the symbol after the number.
percent	formatFractionalDigits and formatSepComma.
zip, zipPlus4	A US ZIP code, or ZIP+4.
phone, ssn	A US phone number, or a US Social Security number.

{{{pdfFormField
  name="amount"
  type="text"
  width="100px"
  height="20px"
  textAlign="right"
  formatType="number"
  formatFractionalDigits=2
  formatSepComma=true
  formatCurrency="€"
}}}

Rules

• A missing name, type, width or height, a size without px, or an invalid argument fails the render with a message that says what is wrong.
• Keep a field out of elements with display: inline-block; a field there is not added.
• A PDF/A document cannot have form fields: the render fails with UNSUPPORTED_FEATURE. Turn PDF/A off for templates with fields. In a PDF/UA document each field is tagged as a form field and announced with its label. See PDF standards.
• In a password-protected PDF, readers cannot fill the fields when the fillingForms and annotating permissions are both off; see PDF standards.