Pdfium Impl Form Fields

pdfium-impl-form-fields

Read and fill interactive PDF form fields with pdfium-render: detect an embedded form, enumerate fields, set text values, toggle checkboxes, select radio buttons, render the filled result, and save.

Scope: form fields specifically. For non-field annotations (highlights, stamps, links) see pdfium-impl-annotations. For the render pipeline see pdfium-syntax-rendering. For saving see pdfium-impl-saving.

Default API surface is 0.9.x. Version traps for 0.8.x are called out inline.

The one rule that dominates this area

pdfium-render fills a field's VALUE but does NOT regenerate its appearance stream. Adobe Acrobat paints fields from the appearance stream, so a programmatically filled field can show correctly in Chrome and pdfium-render's own renderer yet appear BLANK in Acrobat (issue #145). ALWAYS verify filled output in the target viewer. See references/anti-patterns.md section 1.

Quick Reference

The access path

Form fields are NEVER a flat collection. The path is fixed:

PdfDocument
  -> form() -> Option<&PdfForm>                  (does a form exist?)
  -> pages().iter() -> PdfPage
       -> annotations().iter() -> PdfPageAnnotation   (owned values)
            -> as_form_field()      -> Option<&PdfFormField>
            -> as_form_field_mut()  -> Option<&mut PdfFormField>
                 -> as_text_field_mut()         -> PdfFormTextField
                 -> as_checkbox_field_mut()     -> PdfFormCheckboxField
                 -> as_radio_button_field_mut() -> PdfFormRadioButtonField

Each field is wrapped inside a page annotation of type Widget or XfaWidget. as_form_field() returns None for every other annotation type.

Core API

Full signatures and version annotations: references/methods.md.

PdfFormField variants

ALWAYS use the struct name PdfFormTextField for text fields. The name PdfFormFieldText does NOT exist and is a compile error.

Decision tree

Reading vs filling

Need only to READ values, by name?
  -> form.field_values(document.pages())  (one HashMap, fastest path)

Need to READ values with type or geometry detail?
  -> iterate annotations(), narrow with as_form_field() + as_<kind>_field()

Need to FILL fields?
  -> iterate annotations() with `mut`-bound items
  -> as_form_field_mut() -> as_text_field_mut / as_checkbox_field_mut /
     as_radio_button_field_mut
  -> save_to_file() / save_to_bytes()

Which field type

field.field_type() == PdfFormFieldType::Text       -> set_value(&str)
field.field_type() == PdfFormFieldType::Checkbox    -> set_checked(true | false)
field.field_type() == PdfFormFieldType::RadioButton -> set_checked()  (no arg)
ComboBox / ListBox / Signature / PushButton / Unknown
  -> readable only through the enum; no mutable narrowing

Patterns

Condensed patterns below. Complete runnable code is in references/examples.md.

Pattern 1: Detect a form

let pdfium = Pdfium::default();
let document = pdfium.load_pdf_from_file("form.pdf", None)?;
match document.form() {
    Some(form) => println!("form type {:#?}", form.form_type()),
    None => println!("no embedded form"),
}

form() returning None means the PDF carries no AcroForm or XFA form. It NEVER means the document failed to load. To test for a form, use document.form().is_some().

Pattern 2: Read all values in one call

if let Some(form) = document.form() {
    for (name, value) in form.field_values(document.pages()) {
        println!("{name} = {value:?}");
    }
}

field_values returns HashMap<String, Option<String>>. It is read-only.

Pattern 3: Inspect fields by iterating annotations

for page in document.pages().iter() {
    for annotation in page.annotations().iter() {
        let Some(field) = annotation.as_form_field() else { continue };
        println!("{:?} type {:?}", field.name(), field.field_type());
    }
}

as_form_field() is the filter: it returns None for every annotation that is not a Widget / XfaWidget. Treat None as continue, NEVER as an error.

Pattern 4: Fill a text field

for page in document.pages().iter() {
    for mut annotation in page.annotations().iter() {
        if let Some(field) = annotation.as_form_field_mut() {
            if let Some(text) = field.as_text_field_mut() {
                text.set_value("Jane Doe")?;
            }
        }
    }
}
document.save_to_file("filled.pdf")?;

The iterated annotation MUST be bound mut (for mut annotation in ...) so as_form_field_mut() is callable. annotations().iter() yields OWNED PdfPageAnnotation values; there is no iter_mut(). set_value was added in 0.8.21.

Pattern 5: Checkbox vs radio button

if let Some(checkbox) = field.as_checkbox_field_mut() {
    checkbox.set_checked(true)?;   // checkbox: takes a bool
} else if let Some(radio) = field.as_radio_button_field_mut() {
    radio.set_checked()?;          // radio: takes NO argument
}

PdfFormCheckboxField::set_checked takes a bool. PdfFormRadioButtonField::set_checked takes NO argument, because selecting a radio button always means "on". Clear a radio selection by selecting a different button in the same group.

Pattern 6: Render the filled form

let config = PdfRenderConfig::new()
    .set_target_width(1600)
    .render_form_data(true);   // OFF by default
let bitmap = page.render_with_config(&config)?;

render_form_data defaults to false. A render WITHOUT it shows page content but NOT filled field values. See pdfium-syntax-rendering for the full builder.

Pattern 7: Save the filled document

document.save_to_file("filled.pdf")?;       // or
let bytes = document.save_to_bytes()?;       // -> Vec<u8>

See pdfium-impl-saving for save_to_writer and saving options.

Version traps

ALWAYS target 0.8.21 or newer for text-field filling, and 0.8.19 or newer when flattening a document that has form fields. Verify checkbox and radio set_checked against the exact version you pin.

Common mistakes

Each mistake is explained with root cause and fix in references/anti-patterns.md.

Reference files

• references/methods.md: complete API signatures with version annotations.
• references/examples.md: working, verified Rust examples.
• references/anti-patterns.md: real failures, why they fail, and the fix.

Related skills

• pdfium-impl-annotations: the annotation layer that wraps every form field.
• pdfium-syntax-rendering: the PdfRenderConfig builder and render_with_config.
• pdfium-impl-saving: persisting a filled document.
• pdfium-impl-page-manipulation: flatten() and its effect on form fields.
• pdfium-errors-runtime: handling PdfiumError from fill and save calls.