How to add interactive radio-button groups to PDF
By ScoutMyTool Editorial Team · Last updated: 2026-05-28
Introduction
The first survey PDF I built had four radio buttons the user could all select at once because I treated them as four separate fields. PDF radio buttons are mutex-by-naming: same field name across the group, distinct export values per button, and one optional NoToggleToOff flag if you do not want the user de-selecting everything. Once those three things are in place, the group behaves the way users expect and the data is extractable downstream. Here is the working pattern in three editors (Acrobat, Foxit, pdf-lib), the naming convention I use for clean extraction, and the gotchas that bite when buttons get copy-pasted into the wrong field.
Vocabulary, quickly
| Term | Meaning |
|---|---|
| Radio button group | Set of buttons sharing one field name; exactly one selectable |
| Field name | Shared name across the group; the data key downstream |
| Export value | Per-button value submitted/extracted when that button is selected |
| Off state | PDF's value for "no selection yet"; usually the literal string Off |
| Mutex group | Mutually exclusive selection group; same concept as radio |
| NoToggleToOff | Property that prevents the user from de-selecting all options |
| Field defaults | Pre-selected button used when the form opens fresh |
Step by step
- Pick the field name. One name per group; snake_case identifier matching the downstream data schema.
- Add buttons sharing that name. In Acrobat, "Add new field with same name" propagates the group; in pdf-lib, call addRadioGroup once and addButton per option.
- Set distinct export values. "very-satisfied", "satisfied", etc — values that decode without translation downstream.
- Lock with NoToggleToOff. Prevents the user from clicking a selected button to de-select. Almost always desired for surveys.
- Set a default if appropriate. Pre-select neutral or the most common answer; for required-input surveys, leave Off so the user must choose.
- Test in three readers. Adobe Reader, Foxit, macOS Preview. Mutex behavior should work in all three.
- Extract values to validate. pdftk dump_data_fields or pypdf gives you the selected export value per group; confirm it matches the schema before shipping.
- Flatten for delivery if appropriate. Survey responses get flattened so the recipient cannot tamper; live forms stay editable.
Radio-group checklist
- All buttons in a group share the exact same field name — case-sensitive, no trailing space.
- Export values are unique within the group and match the downstream data schema.
- NoToggleToOff is set unless de-selection is a deliberate UX choice.
- Group behavior tested in at least three PDF readers including one mobile.
- Visual layout makes the group clear — labels next to buttons, buttons aligned, no other widgets interleaved.
- Extraction step verified on a sample filled form before shipping the survey.
Related reading and tools
FAQ
- Why do my radio buttons let the user select all of them?
- Each button is a separate field, not a group. Radio buttons must share the same field name; the export values distinguish which option is selected. Rename all buttons in the group to the same name (for example, "satisfaction"), set distinct export values per button ("very-satisfied", "satisfied", "neutral", "unhappy"), and the mutex behavior emerges automatically.
- Selecting one option does not de-select the others. What is wrong?
- Either the field names do not match exactly (one button is "satisfaction" and another is "Satisfaction" with capital S — different fields), or the appearance streams for the buttons are corrupted and not refreshing on click. Fix the names first; if the issue persists, re-create the buttons in the same group rather than copy-pasting.
- How do I prevent the user from de-selecting all buttons?
- Set the NoToggleToOff flag on the group. In Acrobat, the field properties dialog has a checkbox; in pdf-lib, set fieldFlags 0x4000 (NoToggleToOff). Without this flag, clicking a selected radio button can de-select it, leaving the group with no selection — almost never what you want for a survey.
- How do I extract the selected value programmatically?
- Read the field by its name; the field value is the export value of the selected button (or "Off" if nothing is selected). pdftk dump_data_fields shows the current value; pypdf and pdf-lib expose the value through their form-field APIs. Use export values that map to your downstream data schema (snake_case identifiers, not display strings).
- Can a radio group span multiple pages?
- Yes — the field name is the binding, not the visual page. Place buttons sharing a name across pages and they form one group. Useful for long surveys, but visually unusual; users may not realize selecting an option on page 3 de-selected one on page 1. Layout buttons close together for clarity unless you have a strong reason to spread them.
- Do radio buttons work in mobile PDF readers?
- Yes in any reader that supports interactive forms — Adobe Reader mobile, Foxit, PDF Expert, most modern apps. macOS Preview supports radio groups; iOS Files does not always preserve form state on save. Test on each platform you support before shipping a survey-grade PDF.
Citations
- Wikipedia — “Radio button — mutex selection model.” en.wikipedia.org/wiki/Radio_button
- Wikipedia — “PDF — form field types and flags.” en.wikipedia.org/wiki/PDF
- Wikipedia — “Forms Data Format (FDF / XFDF).” en.wikipedia.org/wiki/Forms_Data_Format
Add radio groups to PDF in your browser
Share field names, set export values, lock mutex behavior, and verify the extraction step — ScoutMyTool runs the whole pipeline locally so survey responses stay on your machine.
Open the PDF toolkit →