> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autype.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Fields

> JSON schema reference for standalone and table-cell form fields, variable binding, styling, and PDF AcroForms.

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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

<Warning>
  Signature and initials fields are AcroForm widgets, not cryptographic or
  PAdES signatures.
</Warning>