Form Fields

Form fields are regular content elements with type: "formField". They render as interactive AcroForm widgets in PDF and as printable controls in other formats.

Element shape

{
  "id": "customer-name",
  "type": "formField",
  "name": "customerName",
  "fieldType": "text",
  "label": "Customer name",
  "placeholder": "Enter a name",
  "variable": "customerName",
  "required": true,
  "readOnly": false,
  "width": 100,
  "height": 28,
  "style": {
    "borderMode": "outline",
    "borderLineStyle": "solid",
    "borderWidth": 1,
    "borderColor": "#CBD5E1",
    "backgroundColor": "#FFFFFF",
    "textColor": "#111827",
    "fontSize": 11,
    "inset": 6,
    "borderRadius": 4
  },
  "spacing": { "before": 6, "after": 8 },
  "pagination": { "keepTogether": true }
}

Properties

Property	Type	Required	Description
`id`	string	No	Stable element ID
`type`	`"formField"`	Yes	Element discriminator
`name`	string	Yes	Stable field name (`A-Z`, `a-z`, digits, `_`, `-`)
`fieldType`	string	Yes	`text`, `number`, `multiline`, `date`, `checkbox`, `select`, `signature`, or `initials`
`label`	string	No	Optional visible label; empty means no label spacing
`placeholder`	string	No	Hint for an empty non-checkbox field
`variable`	string	No	Compatible document variable used for the initial value
`value`	string, number, boolean	No	Fixed initial value
`options`	string[]	Conditional	Required for `select`; choice labels for `checkbox`
`selectionMode`	`single`, `multiple`	No	Checkbox selection behavior
`selectedOptions`	string[]	No	Initially selected checkbox options
`required`	boolean	No	Required PDF widget flag
`readOnly`	boolean	No	Read-only PDF widget flag
`signerRole`	string	No	Process role key for `signature` or `initials` fields only
`width`	number	No	Available-width percentage (`10`-`100`)
`height`	number	No	Minimum height in points (`16`-`300`)
`style`	object	No	Local form-field style override
`spacing`	object	No	Local spacing before/after in points
`pagination`	object	No	Page-break and keep hints

Validation rules

select fields require at least one option.
Option labels must be unique.
selectionMode and selectedOptions apply only to checkbox fields.
A single-select checkbox accepts at most one selected option.
Every selected option must exist in options.
Number fields require numeric values; checkbox scalar values must be boolean.
A select value must be one of its options.
signerRole is rejected on every field type except signature and initials.

Checkbox group

{
  "type": "formField",
  "name": "notificationChannels",
  "fieldType": "checkbox",
  "options": ["Email", "SMS", "Portal"],
  "selectionMode": "multiple",
  "selectedOptions": ["Email", "Portal"],
  "style": {
    "checkboxShape": "square",
    "checkboxBorderMode": "outline"
  }
}

For single-selection radio-style controls, use selectionMode: "single" and checkboxShape: "circle".

Form field in a table cell

A table cell may contain text, an image, or one form field, but not more than one of these at the same time.

{
  "type": "table",
  "headers": ["Field", "Value"],
  "rows": [
    [
      "Customer",
      {
        "formField": {
          "type": "formField",
          "name": "customerName",
          "fieldType": "text"
        }
      }
    ]
  ]
}

Global defaults

Use defaults.styles.formField for visual defaults and defaults.spacing.before.formField / defaults.spacing.after.formField for vertical spacing. Local style and spacing values take precedence.

Signature and initials fields are AcroForm widgets, not cryptographic or PAdES signatures.

Overview

Document JSON Syntax

Tools Guides

Document Import

Images

Rendering

Bulk Rendering

Projects & Documents

Templates

Styles

Reusable Blocks

Records

Tools File Management

Tools PDF Actions

Tools Document Actions

Lens (AI)

Tools Jobs

Element shape

Properties

Validation rules

Checkbox group

Form field in a table cell

Global defaults

​Element shape

​Properties

​Validation rules

​Checkbox group

​Form field in a table cell

​Global defaults

Element shape

Properties

Validation rules

Checkbox group

Form field in a table cell

Global defaults