PDF forms

When you build a PDF form in LaTeX — fillable text boxes, checkboxes — the first mine you step on is always the same. Write \TextField{Name}, compile, and out comes a PDF with no error, no warning, and no input field anywhere. The label “Name” is typeset into the text, pdfinfo answers Form: none, and looking inside the file turns up not a single widget annotation. Outside a Form environment, hyperref’s field commands silently produce nothing. This page starts at \begin{Form} and follows, by measurement, what each field actually writes into the PDF, where a submit button sends its data by default, and the point at which you should give up and build a web form instead.

Without a Form environment there are no fields

Every interactive field goes inside \begin{Form} … \end{Form}. This is not a stylistic convention; it changes the output. Compile a document with \TextField and \CheckBox outside the environment and pdflatex exits 0 with no warning at all — yet the resulting PDF contains zero /Widget annotations and pdfinfo still reports Form: none. Move the same commands inside and pdfinfo starts answering Form: AcroForm. A PDF form is built as a single AcroForm dictionary that gathers all the fields, and the Form environment is what creates that dictionary. Note also that \usepackage{hyperref} on its own is enough — no driver option such as [pdftex] is needed; the log shows hpdftex.def being loaded automatically.

The Form environment accepts, counting from hyperref’s source, exactly four keys: action (where the data goes), method, encoding and NeedAppearances. Everything about a field’s appearance and behaviour is set in that field’s own [...], so it is enough to think of the environment’s options as the submission settings.

\documentclass{article}
\usepackage{hyperref}          % no driver option needed
\begin{document}
\begin{Form}[action={https://example.org/collect},method=post]
  \TextField[name=fullname,width=6cm]{Name}\par
  \CheckBox[name=agree]{I agree}\par
  \ChoiceMenu[combo,name=affil]{Affiliation}{University,Company,Other}\par
  \Submit{Send}\quad\Reset{Clear}
\end{Form}
\end{document}

The field commands, and what each writes into the PDF

There are five field commands, and on the PDF side they collapse into three field types: text is /Tx, choice is /Ch, and everything button-shaped — checkbox, push button, submit, reset — is /Btn. Compile the example above and pull the objects out and you find exactly that: two /Tx, one /Ch and four /Btn. Lumping the buttons together is what the PDF specification prescribes; the difference between a checkbox and a push button is carried not by the type but by bits in the flags field (/Ff). That “character is decided by flags” structure matters in the next section.

Omit name= and the label becomes the field name — and the radio-group trap

Leave out name= and the label text becomes the field name. Look inside a PDF built from \TextField{Your name} and the field name is /T (Your name) — spaces included. That is an awkward name for whatever receives the data, and a label written in Japanese gives you a Japanese field name. The working practice is to always give an ASCII identifier with name=. There is a second consequence: write the same name= twice and PDF treats fields sharing a name as one and the same field. Two \TextField entries with name=dup produce two objects both carrying /T (dup), and typing in one fills the other with the same value. That is a useful property when you deliberately want a value echoed in two places, but an accidental collision produces a bug whose cause is hard to see.

Radio buttons hide a deeper problem. Build \ChoiceMenu[radio,name=r1]{Pick}{a,b,c} and you get three /Btn objects all named r1 — but only the first appears in the AcroForm dictionary’s /Fields array. The other two float free, referenced by no field at all. Run the file through qpdf and it says so twice: WARNING: this widget annotation is not reachable from /AcroForm in the document catalog. The PDF specification wants a radio group expressed as one parent field gathering its children through /Kids; hyperref lays them out flat instead. Plenty of viewers display it anyway, which is why the problem goes unnoticed — but it is a structure that can break under a strict PDF processor or an automated extractor. When the choices are fixed, combo or popdown is the more honest tool.

The options worth knowing: which become flags and which do not

Each field takes a long list of options in [...] — hyperref defines close to thirty keys. The ones you reach for are name=, width=/height=, default= (initial value), bordercolor/backgroundcolor, charsize, align (0 = left, 1 = centre, 2 = right), maxlen= (maximum characters) and menulength= (how many rows a list shows). Of these, only multiline, readonly and password are valueless switches that map one-to-one onto PDF flags: hyperref.sty from line 5283 defines ReadOnly as bit 1, Multiline as bit 13 and Password as bit 14, and building a form and reading /Ff back gives exactly 1, 4096 and 8192. maxlen=5, by contrast, is not a flag at all — it is written as a separate /MaxLen 5 entry. Knowing which is which tells you where to look when an option does not do what you expected.

\begin{Form}
  \TextField[name=notes,multiline,width=8cm,height=3cm]{Notes}\par
  \TextField[name=locked,readonly,width=4cm,default={fixed}]{Locked}\par
  \TextField[name=short,maxlen=5,width=3cm]{Max 5}\par
  \TextField[name=email,width=5cm,align=0,
             bordercolor={0 0 0},backgroundcolor={1 1 0.9}]{Email}
\end{Form}

\Submit sends FDF by default — method=post alone is not enough

This is the single most important point on the page. Write \begin{Form}[action={https://example.org/collect},method=post], press the submit button, and what reaches your server is not an HTML form POST but FDF, Acrobat’s own data format. The cause is line 5371 of hyperref.sty: \def\Fld@export{fdf} sets the default export format to FDF. Compile it and pull the submit action out and you find /S /SubmitForm with no /Flags entry at all — every flag zero, which means FDF. And method=post? Read \HyField@FlagsSubmit from line 5378: the GetMethod flag that method sets is used only in the HTML and PDF branches and ignored entirely in the FDF branch. So method=post on its own does nothing whatsoever.

To be received by an ordinary web server, add encoding=html to the Form environment. It is a dedicated key that runs \def\Fld@export{html} around line 5665 of hyperref.sty, and with it in place the submit action gains /Flags 4 — bit 3, ExportFormat, is now set, meaning HTML encoding. Write anything other than html in encoding and you get only a Form 'encoding' key with unknown value warning before it is quietly ignored. The other export formats available are xfdf (an XML flavour of FDF) and pdf (which submits the whole filled-in PDF).

% FDF (the default) -- your endpoint receives an Acrobat-specific blob
\begin{Form}[action={https://example.org/collect},method=post]

% an ordinary HTML form post -- note encoding=html
\begin{Form}[action={https://example.org/collect},encoding=html,method=post]

What real viewers do with it, and when to give up

hyperref’s forms do not write the appearance of a field into the file at all. They set /NeedAppearances true in the AcroForm dictionary, which is a request to the viewer to draw the controls itself. Acrobat Reader honours that request, but support varies: in a browser’s built-in PDF display or a lightweight viewer you may find no visible box, or a box you cannot type into. As for the JavaScript in \PushButton[onclick=...], viewers that run it are the minority. The same property has a knock-on effect elsewhere: anything relying on /NeedAppearances cannot conform to PDF/A. One input field is enough for veraPDF to fail the file at clause 6.3.3, “An annotation does not contain an appearance dictionary” (the PDF/A page covers this in detail).

Put all this together and the reasons to choose a PDF form become quite narrow. For validation or scripting there are insdljs and AcroTeX’s eforms, but no amount of building on top of them can guarantee the thing will work in the reader’s viewer. If all you want is to collect answers online, the honest conclusion is that a web form is more reliable and faster to build. Where a PDF form does fit is a document meant to be handed out as a printed form, which the recipient happens to fill in on a computer before printing it or saving a PDF — that is, one that never uses the submit function. For that use, having typeable boxes is genuinely useful, and combining them with readonly fields makes a stable template.