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

# Field positioning

> The three ways to place a signing field, text box, checkbox, or radio group on a document: explicit coordinates, text markers embedded in the document, and references to existing PDF form fields.

When you add an element to a document - a signing field, text box, checkbox, or radio group - you
have to tell NSEV where on the page it goes. There are three ways to do that, and you can mix them
within a single document:

1. **Explicit coordinates** - you give a page, a position, and a size.
2. **Text markers** - a short code embedded in the document text marks the spot, and its size.
3. **Existing PDF form fields** - you reference a field already present in the uploaded PDF by its
   name.

This page covers all three. For what each element type is and how elements relate to actors and
documents, see [The package model](/docs/nsev/build/concepts/package-model). For the
calls that create elements, see [Send a document for signing](/docs/nsev/build/tutorials/send-for-signing)
and [Instant package](/docs/nsev/build/tutorials/instant-package).

<Note>
  Markers and existing PDF fields are resolved against the uploaded document, so it is recommended to
  create those elements at document-upload time. After a document conversion, a referenced marker or
  field may no longer exist.
</Note>

***

## Explicit coordinates

Supply a `Location` and `Dimensions` and the element is placed exactly where you say.

```json theme={null}
{
  "Type": "SigningField",
  "SigningMethods": ["manual"],
  "Location": {
    "Page": 1,
    "Top": 600,
    "Left": 100
  },
  "Dimensions": {
    "Width": 200,
    "Height": 70
  }
}
```

**`Location`** has three required fields:

* `Page` - the page the element is on. Pages are 1-based: `1` is the first page, `2` the second, and
  so on. `0` must not be used. To count from the end of the document, use negative integers: `-1` is
  the last page, `-2` the second-to-last, and so on.
* `Top` - distance from the top edge of the page. Minimum `0`.
* `Left` - distance from the left edge of the page. Minimum `0`.

`Top` and `Left` are measured from the top-left of the page in points (1 point = 1/72 inch).

**`Dimensions`** has a required `Width` and `Height`. The minimum size depends on the element type:

| Element type                  | Minimum width | Minimum height |
| ----------------------------- | ------------- | -------------- |
| SigningField                  | 50            | 30             |
| TextBox, CheckBox, RadioGroup | 10            | 10             |

The maximum for both width and height is 999999.

<Note>
  A single document must not contain more than 30 signing fields.
</Note>

A radio group is positioned per button rather than as a whole: each option in the group carries its
own `Location` and `Dimensions`.

***

## Text markers

A **text marker** is a short code written into the document's text. When NSEV processes the
document it finds the marker, reads the element's identifier and size from it, and places the
element there - so you do not supply coordinates yourself. This is useful when the people authoring
the documents control field placement, or when the same template is applied to documents whose
layout varies.

The marker encodes the element's id, height, and width. The exact format depends on the element
type, and signing fields use a different prefix (`#`) from form fields (`@`).

### Signing field marker

```
#id_height_width#
```

Regex: `#[a-zA-Z]+(?:\d*\.)?\d+_(?:\d*\.)?\d+_(?:\d*\.)?\d+#`

For example, a signing field with id `sig1`, height `70`, and width `112` is marked in the document
text as:

```
#sig1_70_112#
```

### Form field markers

Form fields (text box, checkbox, radio group) use the `@` prefix and a `#` terminator. There is a
generic form-field marker plus type-specific variants for text boxes and checkboxes:

```
@id_height_width#        generic form field (any form field type)
@id_TB_height_width#     text box
@id_CB_height_width#     checkbox
```

Regexes:

* Generic form field: `@[a-zA-Z]+(?:\d*\.)?\d+_(?:\d*\.)?\d+_(?:\d*\.)?\d+#`
* Text box: `@[a-zA-Z]+(?:\d*\.)?\d+_TB_(?:\d*\.)?\d+_(?:\d*\.)?\d+#`
* Checkbox: `@[a-zA-Z]+(?:\d*\.)?\d+_CB_(?:\d*\.)?\d+_(?:\d*\.)?\d+#`

For example, a text box with id `name1`, height `20`, and width `200`:

```
@name1_TB_20_200#
```

<Warning>
  A **radio group cannot be placed with a text marker.** Place a radio group with explicit
  coordinates (one `Location` and `Dimensions` per option) or by referencing an existing PDF form
  field.
</Warning>

### Marker matching when creating from a template

When a package is created from a template whose elements are matched to documents by markers, the
`SingleMarkerMatchPerElement` parameter on `POST /packages` controls how each element definition is
consumed as documents are confirmed:

* `false` (the default, or `null`): an element definition can be matched by markers in multiple
  documents, and cleanup of any remaining unplaced elements is deferred.
* `true`: each element definition can be matched by only one marker during document confirmation,
  and the definition is removed once it has been placed.

See [Templates](/docs/nsev/build/tutorials/templates#templates-and-super-calls) for the
full template flow.

***

## Existing PDF form fields

If the uploaded PDF already contains form fields you
can attach an element to one of them with `FieldId` instead of giving coordinates or a marker. The
**`FieldId` is the name of the PDF field**, and it must be unique within the document.

To be referenceable by `FieldId`, the PDF field's name must follow the NSEV naming convention: a
signature field's name must match the signature-field pattern (`#` prefix) and a form field's name
must match the form-field pattern (`@` prefix). A field whose name does not follow the convention
cannot be targeted by `FieldId` - so the fields you intend to reference must be named accordingly
when the PDF is prepared.

```json theme={null}
{
  "Type": "SigningField",
  "SigningMethods": ["manual"],
  "FieldId": "Signature1"
}
```

As with markers, the prefix pattern differs between signature fields and form fields:

* Signature field (placed as a SigningField): `#[a-zA-Z]+(?:\d*\.)?\d+`
* Form field - checkbox, text box, or radio group: `@[a-zA-Z]+(?:\d*\.)?\d+`

This is the one way a **radio group** can be attached to an existing field rather than placed by
coordinate.

<Note>
  The names of existing signature and text fields in an uploaded PDF must be **alphanumeric** - only
  letters and numbers, no accented characters, slashes, or dots. There is also a tenant-configurable
  rule under which uploaded text fields whose name matches the configured Text Field format are
  converted to empty signature fields. Both behaviours are covered in
  [Gotchas → PDF input pitfalls](/docs/nsev/build/guides/gotchas#pdf-input-pitfalls).
</Note>

***

## Choosing an approach

* Use **explicit coordinates** when your integration owns the layout and you know exactly where
  each field belongs. It is the most direct and works for every element type.
* Use **text markers** when the documents are authored by someone else who can place the markers,
  or when one template is applied to documents whose layouts differ. Not available for radio
  groups.
* Use **existing PDF form fields** when the uploaded PDF was already prepared with named fields and
  you want to map elements onto them.

***

## Next steps

* Create elements step by step in [Send a document for signing](/docs/nsev/build/tutorials/send-for-signing)
* Place fields as part of a single super call in [Instant package](/docs/nsev/build/tutorials/instant-package)
* Reuse a field layout across packages with [Templates](/docs/nsev/build/tutorials/templates)
* Understand the element object model in [The package model](/docs/nsev/build/concepts/package-model)
* Review PDF input behaviours in [Gotchas](/docs/nsev/build/guides/gotchas)