Forms

Form fields are interactive widgets: the reader types into them, ticks them and saves or prints the result in any PDF viewer. Together they are the document's AcroForm. In stationery a field is an element like text or box: it takes its place in the flow, fills the width it is given and moves to the next page when it does not fit.

class ApplicationPdf < Stationery::Document
  def initialize(applicant)
    super()
    @applicant = applicant
  end

  def view_template
    text "Name"
    text_field "applicant.name", value: @applicant.name, required: true
    text_field "applicant.notes", multiline: true, height: 60
    text_field "applicant.pin", comb: 6                      # six cells; sets max_length
    select "applicant.country", options: %w[Sweden Norway Denmark], value: "Sweden"
    radio "plan", "basic", label: "Basic"                    # radios sharing a name form one group
    radio "plan", "pro", checked: true, label: "Pro"
    checkbox "terms", label: "I accept the terms"
    signature_field "signature", label: "Signature of the applicant"
  end
end

Fields work wherever elements do: inside box, row and column, and inside a table cell given as a proc.

row(gap: 12) do
  column { text_field "applicant.name" }
  column(width: 90) { text_field "applicant.postcode", comb: 5 }
end

table([["Name", -> { text_field "name", value: "Ada" }]], width: :full, widths: [100, nil])

at: [x, y] places a field at a page position instead, outside the flow, measured from the top left corner of the page like every other at:.

text_field "reference", at: [400, 60], width: 140

An option a field does not know raises ArgumentError (unknown text field option: …), so a misspelt name never goes unnoticed.

text_field(name, value: "", width: :full, height: 22, at: nil, **options)

text_field "applicant.name", value: @applicant.name, required: true
text_field "applicant.notes", multiline: true, height: 60
text_field "applicant.postcode", comb: 5, width: 90
text_field "applicant.iban", max_length: 34, font_size: 9

checkbox(name, checked: false, size: 12, label: nil, at: nil, **options)

checkbox "terms", label: "I accept the terms of membership."
checkbox "newsletter", checked: true, label: "Send me the monthly newsletter."

The label is ordinary page text, not part of the field, so it wraps, takes the surrounding text_style and is tagged as a paragraph.

radio(name, value, checked: false, size: 12, label: nil, at: nil, **options)

radio "plan", "basic", label: "Basic · SEK 290 / year"
radio "plan", "pro", checked: true, label: "Pro · SEK 590 / year"
radio "plan", "team", label: "Team · SEK 1,490 / year"

Radios sharing a name are one field, of which the reader picks one choice. The group's value is the value of the checked choice, and Off in the file when none is checked.

A group is named after its field name; give the first choice a tooltip: to name it otherwise.

select(name, options:, value: nil, width: :full, height: 22, at: nil, **options)

select "applicant.country", options: %w[Sweden Norway Denmark Finland Iceland], value: "Sweden"
select "applicant.city", options: %w[Lund Malmö], editable: true

signature_field(name, width: :full, height: 40, label: "Signature", at: nil, **options)

row(gap: 24, align: :bottom) do
  column { signature_field "signature", label: "Signature of the applicant" }
  column(width: 150) { text_field "signed_on" }
end

A signature field has no frame: it draws a rule in the border: colour over its label and is written without a value, for the signer to fill. See Signing.

text_style(weight: :bold) do
  text_field "price", value: "4 990 kr", align: :center, color: "#DC2626", font_size: :fit,
                      max_font_size: 120, height: 150, border: nil, background: nil
end
select "unit", options: ["per piece", "per kg"], value: "per piece", align: :center

Each option is written to the field, where a viewer reads it when it redraws the value, and drawn the same way in the appearance stationery writes, so the field looks the same before and after an edit. A field that uses none of them is written as it was. Bold and italic come from the text style around the field, as its font does.

min_font_size: and max_font_size: are not in the file: a viewer that redraws the field sizes it by its own rule, and may draw a short value larger than the cap. With :fit the chosen size is in the file, so a viewer draws the value no larger than the cap.

What viewers do when they redraw

Every viewer shows the appearance as stationery drew it. A viewer redraws a field from /DA and /Q when it opens a form with NeedAppearances (every render without a conformance level or a signature) and after an edit. Firefox draws two things: the appearance pdf.js generates from /DA (src/core/annotation.js), which is what it prints, and an HTML input it shows while the field is edited (src/display/annotation_layer.js, _setTextStyle). That input is set in the browser's own face, never the PDF's, so a bold field shows regular text while it is edited; no file can change that. Read from each engine's source on 2026-10-01:

Sources: pdf.js src/core/annotation.js (_getAppearance, _computeFontSize), src/core/default_appearance.js, src/display/annotation_layer.js (_setTextStyle) and src/shared/util.js (LINE_FACTOR); PDFium core/fpdfdoc/cpdf_generateap.cpp and cpvt_variabletext.cpp (GetAutoFontSize); poppler poppler/Annot.cc (drawText, calculateFontSize); MuPDF source/pdf/pdf-appearance.c (write_variable_text). Acrobat's is what its users report; Adobe documents no rule.

stationery inspect and Inspector#layout report each field's align:, font_size: (:auto for 0 Tf, the number for :fit) and color: (see Testing).

A name is one or more segments separated by dots. Each segment but the last is a group, which viewers and form-data exports show as a hierarchy:

text_field "applicant.name"
text_field "applicant.address.street"
text_field "applicant.address.postcode", comb: 5

That is three fields under the group applicant, two of them under applicant.address.

document.fields returns { name => value } for the last render; it is nil before the first.

document = ApplicationPdf.new(applicant)
document.to_pdf
document.fields
# => { "applicant.name" => "Astrid Lindqvist", "applicant.country" => "Sweden",
#      "plan" => "pro", "terms" => false, "signature" => nil }

Values are written as Unicode text strings, so "Βασιλείου" or "Müller" is stored as typed, whatever the font. In an encrypted document (to_pdf(encrypt: …)) the values are encrypted with everything else, and the fields stay fillable for whoever opens it with the password.

Every widget carries its own appearance, so a form looks the same in every viewer and in print, whether or not the viewer can draw fields itself.

• Text (a text field's or select box's value, a signature field's label) is set in the text style around the field, in the document's own fonts: embedded, with the fallbacks applied per character. A value in any script the fonts cover is drawn; a character no font has is reported as a MissingGlyph warning, as in any other text, and drawn as .notdef inside a Span whose ActualText is the character, so the appearance still extracts and copies as written. That holds for every line of a multiline: field and every comb: cell. Under a conformance level it raises instead, unless the level is declared with missing_glyphs: :replace: then the character is drawn as the font's stand-in (U+FFFD, else U+25A1, else ?) in the same Span.
• Check marks and radio dots are vector paths. No appearance uses a symbol font.

text_style(font: "Noto Sans", weight: :bold) do
  text_field "name", value: "Βασιλείου", tooltip: "Family name"
end

What an editable field keeps in its font

Fonts are embedded as subsets. A field the reader can edit must be able to show more than the value it starts with, so its font keeps printable ASCII and Latin-1 beyond that value, and a select box the glyphs of every option.

The repertoire costs 10 to 20 KB per font (16 KB for the bundled Inter). Mark fields the reader should not change read_only: and they cost what ordinary text does.

When the reader types a character outside what the font kept, the viewer draws it in a font of its own. The value is stored correctly either way; only the look of that character differs until the document is rendered again with the new value.

What viewers are asked to do

NeedAppearances is set, so a viewer redraws a field after an edit, using the font and size the field names (/DA, for example /F1 10 Tf 0 g). A form with check boxes or radio buttons also lists ZapfDingbats in its resources, for viewers that redraw a button's mark with it; it is never embedded and never used by the appearances stationery writes. Under a conformance level, and in a signed document, both are left out.

Fields made without a font book

Stationery::Forms::Field.new placed with canvas.widget on a bare canvas has no document fonts to draw with. It falls back to the standard Helvetica in Windows-1252, where a character outside that encoding shows as ?: a real glyph, written without ActualText, while the field's /V keeps the value. The five elements on this page never take that path.

In a tagged PDF every field is a Form structure element that owns its widget, in reading order with the text around it, and a check box's or radio button's label is a paragraph next to it. Every field has an accessible name (/TU):

A name such as applicant.address.postcode is a poor thing to hear read out. Give text fields and select boxes a tooltip: that says what to enter:

text "Postcode", size: 8
text_field "applicant.address.postcode", comb: 5, tooltip: "Postcode, five digits"

Forms are allowed under every conformance level. The appearances draw with embedded fonts and paths, which is what PDF/A-3b and PDF/UA-1 require, and under a level the form leaves out NeedAppearances and the ZapfDingbats entry. examples/form.rb is validated as both with veraPDF in CI.

class ApplicationPdf < Stationery::Document
  conformance :pdf_a3b, :pdf_ua1
  metadata title: "Membership application", lang: "en"
end

to_pdf(debug: [:field]) outlines every field's widget in violet, without the outlines of the other layout kinds; debug: true draws them all.

ApplicationPdf.new(applicant).to_pdf("form-debug.pdf", debug: [:field])

document.fields is the quickest assertion: it is what the form was filled with. The matchers cover the rest.

RSpec.describe ApplicationPdf do
  subject(:document) { described_class.new(applicant) }

  it "prefills the applicant and leaves the signature to the signer" do
    document.to_pdf

    expect(document.fields).to include("applicant.name" => "Astrid Lindqvist", "plan" => "pro",
                                       "terms" => false, "signature" => nil)
  end

  it "shows the applicant on the page" do
    expect(document).to have_pdf_text("Astrid Lindqvist", fields: true)
  end

  it "renders without warnings, such as a glyph no font has" do
    expect(document).to have_no_warnings
  end

  it "is an accessible archive copy" do
    expect(document.to_pdf(conformance: %i[pdf_a3b pdf_ua1])).to have_conformance(:pdf_a3b, :pdf_ua1)
  end
end

A value is drawn by its widget and is no part of the page content, so have_pdf_text leaves it out. fields: true reads what the fields show as well, each where it is on its page; so do have_pdf_text_on_page, assert_pdf_text, refute_pdf_text, Inspector#text and Inspector#page_texts. A widget that is hidden shows nothing, and the marks of a check box and a radio button are paths, which read as nothing.

In a tagged document Inspector#structure lists each field as [:Form] between the text around it, which is how to assert the reading order:

Stationery::Testing::Inspector.new(document).structure
# => [[:Document, [[:P, "Name"], [:Form], [:Form], [:P, "I accept the terms"]]]]

For anything else, the field dictionaries are one step away through pdf-reader:

objects = Stationery::Testing::Inspector.new(pdf).reader.objects
form = objects.deref(objects.deref(objects.trailer[:Root])[:AcroForm])
form.keys # => [:Fields, :NeedAppearances, :DA, :DR]

examples/form.rb is a one-page membership application with every field on this page, rendered live by this site.

Open the PDF · Source on GitHub

signature_field writes an empty signature field: a place in the document where a signature goes. The signer fills it in a viewer that can sign, such as Acrobat, with their own certificate. To sign at render time instead, give the document a certificate and key with sign and name the field: sign certificate:, key:, field: "approval". The field keeps its appearance and the file carries a PAdES baseline signature over every byte. See Digital signatures.