Recursive AI

Rename and style a PDF form field in C#

OnePDF is a free, open-source PDF library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

The example zip includes form.pdf, which has one editable field named applicant.name.

Terminal
dotnet add package RecursiveAI.OnePdf

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

For your own PDF, list its field names with TerminalFields. A widget is the field’s box on the page.

C#
using OnePdf;
 
var edit = new PdfOpenOptions
{ AllowEditing = true };
using var pdf =
    PdfDocument.Open("form.pdf", edit);
var form = pdf.Form!;
form.RenameField("applicant.name", "fullName");
var style = new PdfFieldAppearance
{
    Background = PdfFieldColor.Rgb(1, 1, 0.8),
    BorderColor = PdfFieldColor.Gray(0.25),
    FontSize = 14
};
int count = form.SetFieldAppearance(
    "applicant.fullName", style);
pdf.Save("styled.pdf");
Console.WriteLine($"Rebuilt widgets: {count}");

Unzip the example, then dotnet run.

Writes styled.pdf with the name applicant.fullName, a pale yellow fill, a dark gray border, and 14-point text.

Text
Rebuilt widgets: 1

The full program

In form.pdf, applicant is the parent and name is a text field set to “Ada Lovelace.” It has one widget. The program reopens styled.pdf and checks the full name, value, colors, font setting, and stored drawing for that widget. The checks read raw PDF keys such as /MK, /BG, and /N only to verify the result; you can skip them when editing your own form.

C#
using OnePdf;
 
var edit = new PdfOpenOptions { AllowEditing = true };
using var pdf = PdfDocument.Open("form.pdf", edit);
var form = pdf.Form!;
form.RenameField("applicant.name", "fullName");
var style = new PdfFieldAppearance
{
    Background = PdfFieldColor.Rgb(1, 1, 0.8),
    BorderColor = PdfFieldColor.Gray(0.25),
    FontSize = 14
};
int count = form.SetFieldAppearance("applicant.fullName", style);
pdf.Save("styled.pdf");
Console.WriteLine($"Rebuilt widgets: {count}");
 
using var saved = PdfDocument.Open("styled.pdf");
var savedForm = saved.Form ?? throw new InvalidDataException("No saved form.");
var renamed = savedForm.FindField("applicant.fullName")
    ?? throw new InvalidDataException("Renamed field was not saved.");
var widget = renamed.Widgets.Single();
var colors = widget.GetDictionary("MK")!;
var background = colors.GetArray("BG")!;
var border = colors.GetArray("BC")!;
var appearance = widget.GetDictionary("AP")?.GetStream("N");
 
Console.WriteLine($"Field: {renamed.FullName} = {renamed.Value}");
Console.WriteLine($"Old name absent: {savedForm.FindField("applicant.name") is null}");
Console.WriteLine($"Background RGB: {Number(background[0])} {Number(background[1])} {Number(background[2])}");
Console.WriteLine($"Border gray: {Number(border[0])}");
Console.WriteLine($"Default appearance: {renamed.Dictionary.GetString("DA")}");
Console.WriteLine($"Stored normal appearance: {appearance is not null}");
 
static string Number(PdfObject? value) => value switch
{
    PdfInteger integer => integer.Value.ToString(System.Globalization.CultureInfo.InvariantCulture),
    PdfReal real => real.Value.ToString(System.Globalization.CultureInfo.InvariantCulture),
    _ => throw new InvalidDataException("Expected a color component.")
};
Text
Rebuilt widgets: 1
Field: applicant.fullName = Ada Lovelace
Old name absent: True
Background RGB: 1 1 0.8
Border gray: 0.25
Default appearance: /Helv 14 Tf 0 g
Stored normal appearance: True

If the old name is missing, the new name contains a period, or the rename would create a duplicate full name, RenameField throws PdfFormValueException without changing the form.

Variations

After the rename, replace the styling call with this to remove the background and leave the border and text settings alone:

C#
int count = form.SetFieldAppearance("applicant.fullName",
    new PdfFieldAppearance { Background = PdfFieldColor.Transparent });

Or set the text to size itself to the field instead of using a fixed size:

C#
int count = form.SetFieldAppearance("applicant.fullName",
    new PdfFieldAppearance { FontSize = 0 });

The short answer

For a PDF with interactive AcroForm fields, open it with AllowEditing = true. Pass the old full name and the new last part to RenameField: applicant.name plus fullName becomes applicant.fullName. Use the new full name with SetFieldAppearance to change the look, then save to a new file. Neither call changes the field value.

How do I find the names of PDF form fields?

Use the field’s FullName, not the label printed beside the box. A field tree uses periods to separate levels. In the sample, applicant.name tells you which name to edit; a different group could have a name child of its own. List the fields that hold values from the original form, before calling RenameField:

C#
foreach (var field in form.TerminalFields)
    Console.WriteLine(field.FullName);
Text
applicant.name

If a fill script used the old name, update it to use the new one too.

Renaming the parent changes the prefix of every descendant, not just one text field. Renaming applicant to contact, for example, would turn applicant.fullName into contact.fullName. Use a leaf rename when only one field should change. Neither kind of rename can move a field under a different parent. A printed caption is separate page content, so it doesn’t change when you rename the field. See the form renaming API.

How do I change the color of a fillable PDF field in C#?

Use Background for the fill and BorderColor for the outline. Colors take components from 0 to 1: Gray(0) is black, Gray(1) is white. Leave a property unset to keep its existing setting. To remove a fill or border rather than keep it, set that property to PdfFieldColor.Transparent. Font size is a separate setting: 0 means automatic, and a positive value sets the size in points without replacing the font.

A PDF can store a drawing of a widget separately from the field settings. SetFieldAppearance rebuilds that drawing for each widget it changes rather than asking the viewer to create it. The return value counts widgets, not fields: two boxes for the same field can give a count of two. When you style a parent, OnePDF applies the settings to the terminal fields below it, skipping signatures. For check boxes and radio buttons, this redraws the normal states, replacing any custom art stored for those states. See the form appearance API.

All onepdf recipes