documenso/apps/docs/content/docs/users/documents/advanced/pdf-placeholders.mdx

---
title: PDF Placeholders
description: Learn how to use placeholder text in your PDFs for automatic field placement in Documenso.
---

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Callout } from 'fumadocs-ui/components/callout';

## Overview

Documenso can automatically detect placeholder text in your PDF documents and create fields at those locations. This allows you to prepare documents in your preferred editing tool (Word, Google Docs, etc.) with placeholders that become signature fields when uploaded.

## How It Works

When you upload a PDF, Documenso scans for text matching the placeholder pattern `{{...}}`. Each placeholder can specify:

1. **Field type**: What kind of field to create (signature, name, email, etc.)
2. **Recipient**: Which signer the field belongs to (r1, r2, etc.)
3. **Options**: Additional settings like required, read-only, font size, etc.

The placeholder text is automatically hidden after fields are created, so your final document looks clean.

## Placeholder Format

The basic format is:

```
{{FIELD_TYPE, RECIPIENT, option1=value1, option2=value2}}
```

### Examples

| Placeholder                   | Description                         |
| ----------------------------- | ----------------------------------- |
| `{{signature, r1}}`           | Signature field for recipient 1     |
| `{{name, r1}}`                | Name field for recipient 1          |
| `{{email, r2}}`               | Email field for recipient 2         |
| `{{date, r1}}`                | Date field for recipient 1          |
| `{{text, r1, required=true}}` | Required text field for recipient 1 |
| `{{initials, r1}}`            | Initials field for recipient 1      |

## Supported Field Types

The following field types are supported in placeholders:

| Field Type | Placeholder Value |
| ---------- | ----------------- |
| Signature  | `signature`       |
| Initials   | `initials`        |
| Name       | `name`            |
| Email      | `email`           |
| Date       | `date`            |
| Text       | `text`            |
| Number     | `number`          |
| Radio      | `radio`           |
| Checkbox   | `checkbox`        |
| Dropdown   | `dropdown`        |

<Callout type="info">
  Field types are case-insensitive. `{{ SIGNATURE, r1 }}` and `{{ signature, r1 }}` are equivalent.
</Callout>

## Recipient Identifiers

Recipients are identified using `r1`, `r2`, `r3`, etc. The number corresponds to the order in which recipients are created:

- `r1` - First recipient
- `r2` - Second recipient
- `r3` - Third recipient

When you upload a PDF with placeholders, Documenso will:

1. Create placeholder recipients for each unique identifier found (e.g., `r1`, `r2`)
2. You can then update these with real email addresses before sending

<Callout type="warning">
  Placeholders without a recipient identifier (e.g., `{{ signature }}` without `r1`) are reserved
  for API use and will not create fields during upload.
</Callout>

## Field Options

You can customize fields by adding options after the recipient identifier:

### Common Options

| Option      | Values                    | Description                                |
| ----------- | ------------------------- | ------------------------------------------ |
| `required`  | `true`, `false`           | Whether the field must be filled           |
| `readOnly`  | `true`, `false`           | Whether the field is pre-filled and locked |
| `fontSize`  | Number (e.g., `12`)       | Font size in points                        |
| `textAlign` | `left`, `center`, `right` | Horizontal text alignment                  |

### Text Field Options

| Option           | Values | Description                           |
| ---------------- | ------ | ------------------------------------- |
| `label`          | Text   | Label shown in the field              |
| `placeholder`    | Text   | Placeholder text shown before signing |
| `text`           | Text   | Pre-filled text value                 |
| `characterLimit` | Number | Maximum characters allowed            |

### Number Field Options

| Option         | Values        | Description           |
| -------------- | ------------- | --------------------- |
| `value`        | Number        | Pre-filled value      |
| `minValue`     | Number        | Minimum allowed value |
| `maxValue`     | Number        | Maximum allowed value |
| `numberFormat` | Format string | Number display format |

### Selection Field Options

Checkbox, radio, and dropdown placeholders can define their selectable choices via the `options` property.
Separate choices with pipe (`|`) characters.
Checkbox, radio, and dropdown placeholders do not support `label` or `placeholder` metadata.

| Option             | Applies To                | Values                   | Description                              |
| ------------------ | ------------------------- | ------------------------ | ---------------------------------------- |
| `options`          | Checkbox, Radio, Dropdown | `Option 1|Option 2`      | Selectable choices                       |
| `checked`          | Checkbox                  | `Option 1|Option 2`      | Pre-checked choices                      |
| `selected`         | Radio, Dropdown           | One option value         | Pre-selected/default choice              |
| `default`          | Radio, Dropdown           | One option value         | Alias for `selected`                     |
| `defaultValue`     | Radio, Dropdown           | One option value         | Alias for `selected`                     |
| `direction`        | Checkbox, Radio           | `vertical`, `horizontal` | Option layout                            |
| `validationRule`   | Checkbox                  | `atLeast`, `exactly`, `atMost` | Checkbox selection validation rule       |
| `validationLength` | Checkbox                  | Number (e.g., `1`)       | Checkbox validation option count         |
| `required`         | Checkbox, Radio, Dropdown | `true`, `false`          | Whether the field must be completed      |
| `readOnly`         | Checkbox, Radio, Dropdown | `true`, `false`          | Whether the pre-selected value is locked |
| `fontSize`         | Checkbox, Radio, Dropdown | Number (e.g., `12`)      | Field text size                          |

For checkbox validation, `validationLength` defines the option count:
- `atLeast` means at least that many options must be selected
- `exactly` means exactly that many options must be selected
- `atMost` means at most that many options must be selected

If an option needs a literal delimiter, escape it with a backslash:

```
{{dropdown, r1, options=Sales\|Ops|Legal\, Compliance|A\=B}}
```

### Examples with Options

```
{{text, r1, required=true, label=Company Name}}
{{number, r1, minValue=0, maxValue=100, value=50}}
{{name, r1, fontSize=14}}
{{text, r2, readOnly=true, text=Contract #12345}}
{{checkbox, r1, options=Email|SMS|Phone, checked=Email|Phone, validationRule=atLeast, validationLength=1}}
{{radio, r1, options=Card|Bank transfer|Check, selected=Check}}
{{dropdown, r1, options=United States|Canada|United Kingdom}}
{{dropdown, r2, options=Sales|Legal|Finance, defaultValue=Legal}}
```

<Callout type="info">
  Signature and Free Signature fields do not support additional options beyond the field type and
  recipient.
</Callout>

## Multiple Recipients Example

Here's how a document might look with placeholders for two signers:

```
AGREEMENT

Party A Signature: {{signature, r1}}
Party A Name: {{name, r1}}
Party A Date: {{date, r1}}

Party B Signature: {{signature, r2}}
Party B Name: {{name, r2}}
Party B Date: {{date, r2}}
```

When uploaded, this creates:

- 3 fields assigned to recipient 1 (Party A)
- 3 fields assigned to recipient 2 (Party B)
- 2 placeholder recipients that you can update with real email addresses

## Tips for Creating Documents

1. **Use a readable font** - Placeholders need to be readable by the PDF parser. Standard fonts like Arial, Helvetica, or Times New Roman work best.

2. **Don't split placeholders** - Ensure the entire placeholder text `{{...}}` is on a single line and not broken across text boxes.

3. **Size matters** - The field will be sized to match the placeholder text width. Use spaces or longer placeholder text if you need wider fields.

4. **Test with a draft** - Upload your document as a draft first to verify fields are detected correctly before sending.

<Callout type="info">
  Placeholder detection happens automatically when you upload a PDF. You can review and adjust the
  created fields in the document editor before sending.
</Callout>

## Troubleshooting

<Accordions type="multiple">
  <Accordion title="Placeholders Not Detected">
    - Ensure placeholders use double curly braces: `{{...}}`
    - Check that the placeholder includes a recipient identifier (e.g., `r1`)
    - Verify the field type is spelled correctly
    - Try using a standard font in your source document
  </Accordion>

<Accordion title="Wrong Field Position">
  - The field is placed at the exact location of the placeholder text - If the position seems off,
  check that your PDF wasn't scaled or reformatted when exported
</Accordion>

  <Accordion title="Placeholder Text Still Visible">
    - Placeholder text is covered with a white rectangle after field creation
    - If you see the text, try re-uploading the document
  </Accordion>
</Accordions>

## See Also

- [Add Fields to Documents](/docs/users/documents/add-fields) - Place fields manually on your documents
- [Field Types](/docs/concepts/field-types) - Detailed reference for all field types
- [Fields API](/docs/developers/api/fields) - Add fields programmatically via API