# Form Fields

> Complete reference for all form field types available in WPsigner documents.

edition: both
Edition: Lite + Pro
AI note: This page applies to Lite and Pro. Call out Lite limits (PDF only, max 2 signers, email OTP, local timestamp) when they apply. Do not invent Pro-only features.
HTML: https://docs.wpsigner.com/core-features/form-fields/
Markdown: https://docs.wpsigner.com/md/core-features/form-fields.md
Source file: core-features/form-fields.md

---

WPsigner provides a variety of form fields for capturing signer information. This page covers each field type, its properties, and best practices for placement.

## Field Types Overview

| Field Type | Purpose | Signer Action |
|------------|---------|---------------|
| **Signature** | Legal signature capture | Draw or type |
| **Initials** | Abbreviated signature | Draw or type initials |
| **Text** | Single-line input | Type text |
| **Number** | Numeric value | Enter digits |
| **Date** | Date entry | Auto-fill or select |
| **Name** | Full name | Type a name |
| **Email** | Email address with validation | Type an email |
| **Phone** | Telephone number | Type a phone number |
| **Company** | Organization name | Type a company |
| **VAT** | Tax/VAT identifier | Type an identifier |
| **Title** | Job title or position | Type a title |
| **Text Area** | Multi-line input | Type paragraph |
| **Checkbox** | Boolean selection | Click to toggle |
| **Checkbox Group** | Select one or more options | Check options |
| **Radio** | Select one option | Choose an option |
| **Dropdown** | Choice from list | Select option |
| **Attachment** | Supporting file | Upload a file |
| **Label** | Display-only instructions | No input |
| **Payment** | Collect payment when the payment integration is enabled | Complete payment |

> **note**
Some field types appear only when the related feature is available. For example, **Payment** depends on a configured payment integration.

---

## Signature Field

The most important field type - captures the signer's legal signature.

### Signature Options for Signers

When completing a signature field, signers can choose:

| Method | Description |
|--------|-------------|
| **Draw** | Use mouse, finger, or stylus to draw |
| **Type** | Type name, rendered in signature font |
| **Upload** | Upload an image of their signature |

### Signature Properties

| Property | Description | Default |
|----------|-------------|---------|
| **Required** | Must be completed | Yes |
| **Assigned To** | Which signer completes this | First signer |
| **Width** | Field width | 200px |
| **Height** | Field height | 60px |

### Signature Best Practices

- **Size appropriately** - Minimum 150px wide for readable signatures
- **Leave space** - Don't crowd with other elements
- **Align with lines** - Place on existing signature lines in the document
- **One per signer** - Usually one signature field per signer

### Signature Data Captured

When a signer signs, WPsigner records:
- Signature image (PNG)
- Timestamp (UTC)
- IP address
- User agent (browser/device)
- Drawing velocity (for drawn signatures)

---

## Initials Field

A smaller version of the signature field for initializing pages or clauses.

### When to Use Initials

- **Multi-page documents** - Initial each page
- **Specific clauses** - Acknowledge individual sections
- **Amendments** - Mark changes as reviewed
- **Witness marks** - Smaller confirmation signatures

### Initials Properties

| Property | Description | Default |
|----------|-------------|---------|
| **Required** | Must be completed | Yes |
| **Assigned To** | Which signer | Current signer |
| **Width** | Field width | 80px |
| **Height** | Field height | 40px |

### Initials vs Signature

| Aspect | Signature | Initials |
|--------|-----------|----------|
| Size | Larger | Smaller |
| Purpose | Main agreement | Page/section acknowledgment |
| Typical count | 1 per signer | Multiple per signer |

---

## Date Field

Captures the date when the signer completes the document.

### Date Behavior

| Option | Description |
|--------|-------------|
| **Auto-fill** | Automatically uses signing date (default) |
| **Manual entry** | Signer selects the date |

### Date Format

The date format is configured globally in **WPsigner → Settings → General**:

| Format | Example |
|--------|---------|
| MM/DD/YYYY | 01/15/2026 |
| DD/MM/YYYY | 15/01/2026 |
| YYYY-MM-DD | 2026-01-15 |
| Month DD, YYYY | January 15, 2026 |

### Date Properties

| Property | Description | Default |
|----------|-------------|---------|
| **Required** | Must be completed | Yes |
| **Auto-fill** | Use current date automatically | Yes |
| **Format** | Date display format | Site default |

### Date Placement Tips

- Place next to signature fields
- Use for agreement dates, not backdating
- Consider timezone differences for international signers

---

## Text Field

Single-line text input for short responses.

### Common Uses

- **Name** - Full legal name
- **Title** - Job title or position
- **Company** - Organization name
- **Address** - Single-line address
- **Phone** - Contact number
- **Email** - Email address
- **ID Number** - License, SSN (partial), passport

### Text Field Properties

| Property | Description | Default |
|----------|-------------|---------|
| **Required** | Must be completed | No |
| **Placeholder** | Helper text shown before input | Empty |
| **Default Value** | Pre-filled value | Empty |
| **Max Length** | Character limit | 256 |
| **Validation** | Input format (email, phone, etc.) | None |

### Text Validation Options

| Validation | Accepts |
|------------|---------|
| **None** | Any text |
| **Email** | Valid email format |
| **Phone** | Numeric with formatting |
| **Number** | Digits only |
| **Letters** | Alphabetic only |

---

## Text Area Field

Multi-line text input for longer responses.

### Common Uses

- **Comments** - Additional notes or observations
- **Explanation** - Detailed responses
- **Address** - Full multi-line address
- **Special instructions** - Custom requirements
- **Decline reason** - Why signer is declining

### Text Area Properties

| Property | Description | Default |
|----------|-------------|---------|
| **Required** | Must be completed | No |
| **Placeholder** | Helper text | Empty |
| **Rows** | Visible text lines | 3 |
| **Max Length** | Character limit | 1000 |

### Text Area vs Text Field

| Text Field | Text Area |
|------------|-----------|
| Single line | Multiple lines |
| Short input | Long input |
| Names, emails | Comments, addresses |

---

## Checkbox Field

Boolean yes/no selection for options and acknowledgments.

### Common Uses

- **Terms acceptance** - "I agree to the terms and conditions"
- **Confirmation** - "I confirm this information is accurate"
- **Options** - "Include extended warranty"
- **Acknowledgment** - "I have read and understood"
- **Consent** - "I consent to email communication"

### Checkbox Properties

| Property | Description | Default |
|----------|-------------|---------|
| **Required** | Must be checked | No |
| **Checked by default** | Pre-checked state | No |
| **Label** | Text next to checkbox | Empty |

### Checkbox Groups

Create related checkboxes for multiple options:

Example: Service Add-ons
- ☐ Priority support (+$99/year)
- ☐ Extended warranty (+$49/year)  
- ☐ Training session (+$199 one-time)

### Required Checkboxes

When marked as required:
- Signer must check the box to proceed
- Used for mandatory acknowledgments
- Document cannot be completed without checking

---

## Dropdown Field

Selection from a predefined list of options.

### Common Uses

- **State/Province** - Select from list
- **Country** - Select country
- **Department** - Choose department
- **Plan tier** - Select service level
- **Relationship** - Spouse, child, parent, etc.
- **Yes/No** - Simple binary choice

### Dropdown Properties

| Property | Description | Default |
|----------|-------------|---------|
| **Required** | Must select an option | No |
| **Options** | List of choices | Empty |
| **Default** | Pre-selected option | None |
| **Placeholder** | Text before selection | "Select..." |

### Adding Options

1. Click the dropdown field in the editor
2. Open the Properties panel
3. In "Options," add each choice on a new line:

```
Option 1
Option 2
Option 3
```

### Dropdown vs Checkbox

| Use Dropdown | Use Checkbox |
|--------------|--------------|
| Many options (3+) | Yes/No only |
| Mutually exclusive | Multiple selections possible |
| Saves space | Self-explanatory |

---

## Choice, identity, attachment, and payment fields

- **Checkbox Group** allows multiple selections; **Radio** allows exactly one selection.
- **Name, Email, Phone, Company, VAT, and Title** are purpose-specific text fields. Use them instead of a generic Text field when validation or integration mapping benefits from a stable type.
- **Attachment** lets the assigned signer upload supporting evidence. Avoid requesting sensitive files unless they are required, and define an appropriate retention policy.
- **Label** adds non-editable instructions to the signing layer.
- **Payment** is available when the payment integration is configured and must be completed according to that integration's signing flow.

For choice fields, define clear option labels and test the final PDF output before sending.

---

## Field Placement

### Accessing the Field Editor

1. Go to **WPsigner → New Document** (or edit a **Campaign**) and open the **Fields** step
2. Field types appear in the left sidebar
3. The PDF preview is in the center — place fields directly on the page

The same field editor is used when you build a template and later save it from **Review → Save as Template**.

### Placing Fields

**Click Method**
1. Click a field type in the toolbar
2. Click on the document where you want it
3. Field appears at cursor position

**Drag Method**
1. Click and hold a field type
2. Drag to the document
3. Release to place

### Moving Fields

- Click and drag any placed field
- Fields snap to alignment guides

### Resizing Fields

- Hover a field and drag the resize handle (bottom-right corner)
- Make signature fields large enough for finger or stylus input

### Deleting Fields

- Hover the field and click the red **X** outside the top-right corner
- Or right-click the field → **Delete**

---

## Field name, mapping name, and placeholder

Every placed field (except types that open their own options modal, such as dropdown / radio / checkbox group) can be renamed with a **double-click**.

### Open Field Properties

1. **Double-click** the field on the PDF
2. A floating **Field Properties** popup appears (not inside the field box)
3. Edit the values, then click **Save** (or press Enter). **Cancel** or Escape closes without saving

| Setting | What it is | Who sees it |
|---------|------------|-------------|
| **Field name** | Friendly label shown on the field in the editor (e.g. `Client full name`) | You, in New Document / Campaign / Templates |
| **Mapping name** | Technical key for Zapier, form feeds, and the API (e.g. `client_name`) | Automations and integrations |
| **Placeholder** | Hint text the signer may see before typing | Signer on the signing page (text-like fields) |

### Mapping name rules (important)

- If you leave **Mapping name** empty, WPsigner uses the **Field name** (converted to a safe key, e.g. `Client full name` → `client_full_name`)
- Use short, stable keys for integrations: lowercase letters, numbers, and underscores (`client_name`, `property_address`)
- Keep the same mapping name if Zapier or a form feed already depends on it — changing the key breaks existing mappings

> **Two ways to set mapping keys**
1. **While placing fields** — double-click → **Mapping name** (fastest while building the PDF)
2. **After saving a template** — **WPsigner → Templates → ⋮ → Map Variables** (edit keys on an existing template)

Both point to the same variable keys used by [Zapier](/integrations/zapier/), [Uncanny Automator](/addons/uncanny-automator-actions/#prefill), and the [Templates API](/api/templates/).

### Examples

| Field name (display) | Mapping name | Used for |
|----------------------|--------------|----------|
| Client full name | `client_name` | Prefill from Zapier / Calendly |
| Property address | `property_address` | Prefill from a form or CRM |
| Appointment date | `appointment_date` | Prefill booking date |
| Company | *(leave empty)* | Key becomes `company` automatically |

---

## Field Assignment

### Assigning to Signers

Signer **#1** is the first person on the Add Signers list. Signature fields you place while that slot is active belong to them. Add more people in order for Signer #2, #3, and so on. See [Signer order](/core-features/signer-workflows/#signer-order).

When multiple signers exist:

1. Select a field
2. In Properties, find "Assigned To"
3. Select the signer from the dropdown
4. Field changes to signer's color

### Color Coding

Each signer has a unique color:

| Signer | Color | Meaning |
|--------|-------|---------|
| Signer 1 | Blue | Signer 1's fields |
| Signer 2 | Green | Signer 2's fields |
| Signer 3 | Orange | Signer 3's fields |

This helps visualize which signer completes which fields.

### Field Visibility

- Each signer only sees their assigned fields as editable
- Other signers' fields appear as read-only
- Completed fields show the entered values

---

## Field Properties Reference

### Common Properties (All Fields)

| Property | Type | Description |
|----------|------|-------------|
| `field_name` | String | Display label in the editor (Field Properties) |
| `variable_mapping` | String | Integration key; empty falls back to field name |
| `placeholder` | String | Signer hint text (text-like fields) |
| `assignedTo` | Signer | Which signer completes this |
| `required` | Boolean | Must be completed |
| `x` | Number | X position (% from left) |
| `y` | Number | Y position (% from top) |
| `width` | Number | Width (% of page) |
| `height` | Number | Height (% of page) |
| `page` | Number | Page number (1-indexed) |

### Field-Specific Properties

**Signature/Initials**
| Property | Type | Description |
|----------|------|-------------|
| `drawEnabled` | Boolean | Allow drawing |
| `typeEnabled` | Boolean | Allow typing |
| `uploadEnabled` | Boolean | Allow upload |

**Text/Text Area**
| Property | Type | Description |
|----------|------|-------------|
| `placeholder` | String | Helper text |
| `defaultValue` | String | Pre-filled value |
| `maxLength` | Number | Character limit |

**Checkbox**
| Property | Type | Description |
|----------|------|-------------|
| `checked` | Boolean | Default state |
| `label` | String | Display label |

**Dropdown**
| Property | Type | Description |
|----------|------|-------------|
| `options` | Array | List of choices |
| `defaultOption` | String | Pre-selected value |

---

## Best Practices

### Field Sizing Guide

| Field Type | Recommended Width | Recommended Height |
|------------|-------------------|-------------------|
| Signature | 200-300px | 60-80px |
| Initials | 60-100px | 40-60px |
| Date | 100-150px | 30px |
| Text | 150-300px | 30px |
| Text Area | 200-400px | 60-120px |
| Checkbox | 20px | 20px |
| Dropdown | 150-250px | 30px |

### Mobile Considerations

60%+ of documents are signed on mobile devices:

- Make signature fields larger (minimum 200px wide)
- Space fields apart (avoid overlapping)
- Use clear labels
- Test on phone before sending

### Accessibility

- Add placeholder text to explain expected input
- Use clear, descriptive labels
- Don't rely only on color to convey meaning
- Ensure sufficient field sizes for touch input

---

## Next Steps

- [Creating Documents](/core-features/creating-documents/) - Full wizard guide
- [Signer Workflows](/core-features/signer-workflows/) - Signing order options
- [Campaigns](/core-features/campaigns/) - Public signing links