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

# Field Types & Coordinates

> Placing signature, date, text, and checkbox fields on your documents.

## Field types

| Type        | Value filled by       | Description                                          |
| ----------- | --------------------- | ---------------------------------------------------- |
| `signature` | Signer (draw or type) | Full signature image                                 |
| `initial`   | Signer (draw or type) | Initials only                                        |
| `date`      | System (auto)         | Current date at time of signing — signer cannot edit |
| `text`      | Signer                | Free-form text input (up to 1000 chars)              |
| `checkbox`  | Signer                | Boolean — check or uncheck                           |

***

## Coordinate system

All field positions use **PDF points** (1 point = 1/72 inch). The origin `(0, 0)` is the
**bottom-left corner** of each page — this is the PDF standard, not a SignProof quirk.

```
┌──────────────────────────────┐ ← top of page (y = page height)
│                              │
│   ┌───────────────┐          │
│   │  field here   │          │
│   └───────────────┘          │
│   ↑                          │
│   (x=72, y=200)              │
│                              │
└──────────────────────────────┘ ← bottom of page (y = 0)
```

**Common page sizes in points:**

| Page size              | Width | Height |
| ---------------------- | ----- | ------ |
| US Letter (8.5" × 11") | 612   | 792    |
| A4 (210mm × 297mm)     | 595   | 842    |
| Legal (8.5" × 14")     | 612   | 1008   |

***

## Field parameters

```json theme={null}
{
  "documentId": "doc_01HX...",
  "signerId": "sgn_01HX...",
  "type": "signature",
  "page": 1,
  "x": 72,
  "y": 72,
  "w": 200,
  "h": 60,
  "required": true
}
```

| Parameter  | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `page`     | 1-based page number                                          |
| `x`        | Left edge of the field in PDF points                         |
| `y`        | Bottom edge of the field in PDF points                       |
| `w`        | Width in PDF points                                          |
| `h`        | Height in PDF points                                         |
| `required` | If `true`, signer cannot complete without filling this field |

***

## Converting screen coordinates to PDF coordinates

If you're placing fields from a browser-rendered PDF, you need to convert screen pixels to PDF
points. The formula accounts for the screen DPI and the PDF render scale:

```typescript theme={null}
function screenToPdf(
  screenX: number,
  screenY: number,
  screenPageHeight: number,
  renderScale: number    // e.g. 1.5 for 150% zoom
): { x: number; y: number } {
  const PDF_DPI = 72;
  const SCREEN_DPI = 96;

  // Convert screen pixels → PDF points
  const pdfX = (screenX / renderScale) * (PDF_DPI / SCREEN_DPI);

  // PDF y-axis is inverted (origin at bottom) — flip it
  const pdfY = ((screenPageHeight - screenY) / renderScale) * (PDF_DPI / SCREEN_DPI);

  return { x: Math.round(pdfX), y: Math.round(pdfY) };
}
```

<Tip>
  The drag-drop field placer in the Console handles coordinate conversion for you. Use it to
  position fields visually without writing coordinate math.
</Tip>

***

## Typical field sizes

These are sensible defaults — adjust to fit your document layout.

| Field type  | Recommended width | Recommended height |
| ----------- | ----------------- | ------------------ |
| `signature` | 180–250 pt        | 50–80 pt           |
| `initial`   | 80–120 pt         | 40–60 pt           |
| `date`      | 100–150 pt        | 20–30 pt           |
| `text`      | 150–300 pt        | 20–30 pt           |
| `checkbox`  | 16–20 pt          | 16–20 pt           |

***

## Optional fields

Set `required: false` to make a field optional. The signer can complete it or leave it blank.
At least one field per signer must be `required` (SignProof will reject an envelope where a signer
has only optional fields).

***

## Date format

`date` fields are auto-filled with the signing date in the format configured on your application
(default: `YYYY-MM-DD`). The date is recorded at the moment the signer submits, in UTC.