> ## 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

> Add text, number, date, choice, signature, and initials fields to Autype documents and interactive PDF exports.

Form fields are document elements that stay visible in every export and become
interactive **AcroForm widgets in PDF exports**. They can use fixed values or
read their initial value from a document variable.

## Supported field types

| Type        | Purpose                | Variable type                    |
| ----------- | ---------------------- | -------------------------------- |
| `text`      | Single-line text       | text                             |
| `number`    | Numeric value          | number                           |
| `multiline` | Multi-line text        | text                             |
| `date`      | Date input             | text                             |
| `checkbox`  | One or several choices | text (single) or list (multiple) |
| `select`    | Dropdown choice        | text                             |
| `signature` | Empty signature widget | none                             |
| `initials`  | Empty initials widget  | none                             |

## Basic syntax

```markdown theme={null}
::field{name="customerName" type=text label="Customer name" required=true}
::field{name="invoiceTotal" type=number label="Invoice total" value=149.9}
::field{name="dueDate" type=date label="Due date" placeholder="YYYY-MM-DD"}
::field{name="department" type=select label="Department" options="Sales|Finance|Legal"}
::field{name="signature" type=signature label="Signature" required=true signerRole="customer-signer" width=60 height=72}
```

The `name` is a stable field identifier. Labels are optional; an empty label
renders only the input control without reserving label spacing.

## Checkboxes and choices

A checkbox field contains one or more visible options. Use `selectionMode` to
choose whether users may select one or several options.

```markdown theme={null}
::field{name="approval" type=checkbox options="I approve"}
::field{name="interests" type=checkbox options="Product updates|Events|Research" selectionMode=multiple selected="Events|Research"}
::field{name="contactMethod" type=checkbox options="Email|Phone|Post" selectionMode=single selected="Email"}
```

`placeholder` is not used for checkbox labels. Each value in `options` is both
the visible label and the submitted option value.

## Variable binding

Use `variable` to prefill a field from the document's variables:

```markdown theme={null}
::field{name="customerName" type=text label="Customer" variable="customerName"}
::field{name="interests" type=checkbox options="Events|Research" selectionMode=multiple variable="interests"}
```

The field does not create the variable. Define it in the document's variables
first, using a compatible type. A local `value` or `selected` value remains a
fixed initial value when no variable is bound.

## Multiline values

Use `\n` inside a quoted fixed value. Autype converts it to actual line breaks
and escapes it exactly once when converting back to Markdown.

```markdown theme={null}
::field{name="notes" type=multiline label="Notes" value="First line\nSecond line\nThird line" height=80}
```

## Form fields in tables

A form field can be the sole content of a table cell:

```markdown theme={null}
:::table{columnWidths="1fr,2fr"}
| Label | Value |
| --- | --- |
| Customer | ::field{name="customer" type=text} |
| Department | ::field{name="department" type=select options="Sales,Legal"} |
| Approval | ::field{name="approval" type=checkbox options="Approved"} |
:::
```

Inside table cells, separate choice options with commas because `|` is already
the Markdown table delimiter.

## Attributes

| Attribute                       | Description                                                                                   |                               |
| ------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------- |
| `name`                          | Stable identifier; required                                                                   |                               |
| `type`                          | One of the supported field types; required                                                    |                               |
| `label`                         | Optional visible label                                                                        |                               |
| `placeholder`                   | Hint for an empty non-checkbox field                                                          |                               |
| `variable`                      | Compatible document variable used as the initial value                                        |                               |
| `value`                         | Fixed string, number, or boolean value                                                        |                               |
| `options`                       | Choice values separated by \`                                                                 | \` (or commas in table cells) |
| `selectionMode`                 | `single` or `multiple` for checkboxes                                                         |                               |
| `selected`                      | Initially selected checkbox options                                                           |                               |
| `required`                      | Mark the PDF widget as required                                                               |                               |
| `readOnly`                      | Prevent editing of the PDF widget                                                             |                               |
| `signerRole`                    | Process role allowed to fill a `signature` or `initials` field; rejected on other field types |                               |
| `width`                         | Percentage of available content width (`10`-`100`)                                            |                               |
| `height`                        | Minimum height in points (`16`-`300`)                                                         |                               |
| `spacingBefore`, `spacingAfter` | Local vertical spacing in points                                                              |                               |

## Styling

The following attributes override the global `defaults.styles.formField`
settings for one field:

| Attribute                                     | Values                            |
| --------------------------------------------- | --------------------------------- |
| `borderMode`                                  | `outline`, `underline`, `none`    |
| `borderLineStyle`                             | `solid`, `dashed`, `dotted`       |
| `borderWidth`                                 | `0`-`10` pt                       |
| `borderColor`, `backgroundColor`, `textColor` | Hex color                         |
| `fontSize`                                    | `6`-`72` pt                       |
| `inset`                                       | Inner padding (`0`-`50`)          |
| `borderRadius`                                | Corner radius (`0`-`30`)          |
| `showHints`                                   | Show or hide visual editor hints  |
| `showContainerBorder`                         | Show or hide the editor container |
| `checkboxBorderMode`                          | Border mode for checkbox controls |
| `checkboxShape`                               | `square` or `circle`              |

Global vertical spacing is configured through
`defaults.spacing.before.formField` and `defaults.spacing.after.formField`.

## Output behavior

| Output           | Behavior                                                        |
| ---------------- | --------------------------------------------------------------- |
| PDF              | Interactive AcroForm widgets with required/read-only flags      |
| DOCX / ODT       | Printable visual representation                                 |
| Web preview      | Visual preview of fields and current values                     |
| Rich text editor | Editable document blocks with properties in the context toolbar |

<Warning>
  `signature` and `initials` create PDF form widgets. They do not apply a
  cryptographic signature, qualified electronic signature, or PAdES seal.
  A Workspace signature process can fill these widgets with its audited
  typed-name simple electronic signature when `required=true` and `signerRole`
  matches the signer role.
</Warning>