# Split field

A split field collects a single value across a row of cells. Use it where a printed form breaks one answer into boxes, such as a card number, a sort code or a National Insurance number. You place one field over the boxes instead of one text field per box, and the value can be validated as a whole.

Split fields are available from 10 November 2026.

## How split fields work

A split field is made of cells, runs and gaps.

- A **cell** holds one character.
- A **run** is a group of cells that sit together. A field has between 1 and 20 runs, and each run has between 1 and 25 cells.
- The **cell gap** is the space between cells. It is one value shared by every run.
- The **run gap** is the space between runs. It is one value for the whole field.


A card number printed as `1234 5678 9012 3456` has four runs of 4 cells:

```text
 run 1          run 2          run 3          run 4
[1][2][3][4]   [5][6][7][8]   [9][0][1][2]   [3][4][5][6]
           |<->|
          run gap
```

Describe the printed form from left to right, then set the gaps to match the spacing between its boxes. Where boxes touch, use a cell gap of 0.

The `card_number` preset sets this layout for you and checks the value is 16 digits. See [Presets](#presets).

| Property | Limits |
|  --- | --- |
| Runs per field | 1 to 20 |
| Cells per run | 1 to 25 |
| Cell gap | 0 or more. Defaults to 0 |
| Run gap | 0 or more. Defaults to 0 |


## Presets

A preset sets a validation rule and, for most presets, a layout. Presets are for UK references.

| Preset | Layout | What it accepts |
|  --- | --- | --- |
| `numeric` | None, set with `l=` | Digits only |
| `alphabetical` | None, set with `l=` | Letters only |
| `alphanumeric` | None, set with `l=` | Letters and digits only |
| `card_number` | `4-4-4-4` | 16 digits |
| `sort_code` | `2-2-2` | 6 digits |
| `national_insurance` | `2-2-2-2-1` | A National Insurance number, such as `AB123456C`: two capital letters, six digits, then A, B, C or D |
| `utr` | `5-5` | A Unique Taxpayer Reference: 10 digits |
| `uprn` | `12` | A Unique Property Reference Number: 1 to 12 digits |
| `postcode` | `7` | A UK postcode without the space, such as `SW1A1AA` |


`numeric`, `alphabetical` and `alphanumeric` only limit which characters a signer can enter, so use them with `l=`. For example, `{split,p=numeric,l=8:signer1:Reference}`.

You can override a preset's layout or gaps. See [Combine options](#combine-options).

## Validation

Validation restricts what a signer can enter. It comes from the [preset](#presets), and there is no separate validation option. The whole value must match, not part of it. An empty value is not validated unless the field is required.

- A split field without a preset accepts any characters.
- The value is checked without separators, one character per cell.
- Overriding a preset's layout keeps its validation. A layout that cannot fit the preset, such as `p=card_number,l=4`, is accepted. The signer will never be able to enter a valid value, so check the layout still fits the preset.
- Custom regular expressions are not supported.


## Create split fields with document tags

Split tags use the same `{WHAT:WHO:NAME}` format as other [tags](/tags). Add options after `split`, separated by commas. Options can appear in any order.

```text
{split,l=4-4-4-4,cg=2,rg=4:signer1:Card+Number}
```

| Option | Meaning |
|  --- | --- |
| `l=` | Layout. One cell count per run, joined by `-`. Required unless you use `p=` |
| `cg=` | Cell gap, shared by every run. Defaults to 0 |
| `rg=` | Run gap. Defaults to 0 |
| `p=` | A [preset](#presets), which sets validation and, for most presets, the layout |
| `?` | Placed after `split` to make the field optional |
| `w`, `h` | Width and height in PDF units, as described in [Tags](/tags#adjust-field-dimensions). Set width before height |


Gaps are measured in PDF units, the same as `w` and `h`. The tag-level `g` option used for other fields is unrelated to `cg=`.

### Build a tag

Use the [tag builder](/tags#build-a-tag) and choose **Split** to put a tag together, then copy it into your document.

### Set a layout

`l=` takes run cell counts only. Gaps are set separately with `cg=` and `rg=`.

```text
{split,l=9:signer1:Reference}
{split,l=5-10,cg=2:signer1:Reference}
{split,l=4-4-4-4,cg=2,rg=4:signer1:Card+Number}
```

The first gives one run of 9 cells. The second gives two runs sharing a cell gap of 2. The third gives four runs of four cells with a cell gap of 2 and a run gap of 4.

### Use a preset

```text
{split,p=card_number:signer1:Card+Number}
{split?,p=utr,w200:signer1:UTR}
```

### Combine options

Use `l=` with `p=` to override the preset's layout. The preset's validation still applies.

```text
{split,p=card_number,l=16,cg=2:signer1:Card+Number}
```

This keeps the card number check but lays the 16 cells out as one run, for a form that prints the boxes without breaks.

Using `cg=` or `rg=` with `p=` overrides the preset's gaps.

### Tags that are ignored

A split tag with any of these problems is ignored, so no field is created. If a field you expect is missing after upload, check its tag against this list.

| Problem | Example |
|  --- | --- |
| No `l=` or `p=` | `{split:signer1:Card}` |
| A preset with no layout, and no `l=` | `{split,p=numeric:signer1:Ref}` |
| `l=` is not a layout | `{split,l=card_number:signer1:Card}` |
| Gaps written inside `l=` | `{split,l=4g2-4:signer1:Ref}` or `{split,l=4-4-rg2:signer1:Ref}` |
| A run with 0 cells, or more than 25 | `{split,l=26:signer1:Ref}` |
| More than 20 runs | `l=` with 21 counts |
| `cg=` or `rg=` is not a whole number of 0 or more | `{split,l=4,rg=abc:signer1:Ref}` or `cg=-1` |
| An option repeated | `{split,l=4,cg=2,cg=4:signer1:Ref}` |
| Unknown preset | `{split,p=nope:signer1:Card}` |
| `l=`, `cg=`, `rg=` or `p=` on another field type | `{text,cg=2:signer1:Name}` |
| Tag wraps across two lines | Reduce the font size so the tag stays on one line |


## Read completed values

If your integration validates `field_type` against a fixed list, add the new type before 10 November 2026.

## Related documentation

- [Tags](/tags) – The full tag syntax
- [Send an envelope with an uploaded document](/guides/send-envelope/send-envelope-uploaded-document) – Use tags when uploading a document