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

# PDF Tagger

> Upload a fillable PDF, tag each field to a workflow variable, handle checkboxes and conditional logic, and map repeating item data to specific fields.

If you regularly fill out the same court forms, client intake PDFs, or standard legal forms, Gavel can automate the process entirely. You upload a fillable-field PDF, open the PDF Tagger to connect each field to a variable in your workflow, and from then on Gavel populates the form automatically whenever a user completes the questionnaire. There is no need to type into the PDF manually — every tagged field is filled in based on the answers provided.

## How it works at runtime

When a user finishes the questionnaire and Gavel generates documents, it reads each PDF field's tag and substitutes the corresponding questionnaire answer into that field. Fields tagged to a variable receive the variable's value. Fields tagged with a conditional value receive the text that matches the condition. Fields marked as **Untagged** are left blank. The result is a filled PDF that looks as though it was completed by hand.

## Prepare your PDF

Your PDF must have fillable fields before you can tag it in Gavel. If your PDF does not already have fillable fields, you have two options:

* **Adobe Acrobat Pro** — the standard tool for adding text fields, checkboxes, and signature fields to any PDF.
* **PDF Unlocker and Field Renamer** — Go to: `start.gavel.io/pdf` to unlock your PDF, add text fields, checkboxes, or signature fields.

## Tag PDF fields

<Steps>
  <Step title="Add the PDF to your workflow">
    Open your workflow and go to the **Document Templates** tab. Upload your fillable PDF. It will appear in the list of templates attached to the workflow.
  </Step>

  <Step title="Open the PDF Tagger">
    Click **Tag** on the right side of the PDF document template. This opens the PDF Tagger, which displays your PDF with all its fillable fields visible and selectable.
  </Step>

  <Step title="Select a field">
    Click on any fillable field in the PDF. A panel appears with four options for what to put in that field.
  </Step>

  <Step title="Choose a tagging option and save">
    Select the appropriate option for that field (see below), configure the value, and click **Save**. Repeat for all fields you want to tag.
  </Step>
</Steps>

## Field tagging options

For each fillable field in your PDF, you have four choices:

<Tabs>
  <Tab title="Insert Variable">
    Maps the field directly to a workflow variable. When the questionnaire is completed, the field is filled with the answer to that question.

    **How to use:** Select the field, choose **Insert Variable**, pick the variable from the list, and click **Save**.
  </Tab>

  <Tab title="Insert Conditional Value">
    Lets you define rules that determine what text appears in the field based on how other questions were answered. Useful when the content of a field depends on a yes/no answer or a selection elsewhere in the questionnaire.

    **How to use:** Select the field, choose **Insert Conditional Value**, build the condition using the available variables, and click **Save**.
  </Tab>

  <Tab title="Enter Text">
    Places static text that always appears in this field, regardless of questionnaire answers. You can also use this option to enter advanced formatting syntax (see below).

    **How to use:** Select the field, choose **Enter Text**, type the text or syntax you want, and click **Save**.
  </Tab>

  <Tab title="Untagged">
    Leaves the field blank in all generated documents. Use this for fields you intentionally want to leave empty.
  </Tab>
</Tabs>

## Checkboxes

Gavel can check or uncheck PDF checkboxes based on questionnaire answers.

<AccordionGroup>
  <Accordion title="Connect a checkbox to a Yes/No variable">
    To check a box conditionally based on a workflow answer:

    1. Select the checkbox field in the PDF Tagger.
    2. Choose **Insert Conditional Value**.
    3. Build the condition — for example, "check this box if the variable `hasChildren` equals Yes."
    4. Click **Save**.

    Repeat for each checkbox that depends on a variable.
  </Accordion>

  <Accordion title="Set a checkbox to always be checked">
    If a box should always be checked regardless of questionnaire answers:

    1. Select the checkbox field in the PDF Tagger.
    2. Choose **Enter Text**.
    3. Type `Yes` in the text field.
    4. Click **Save**.
  </Accordion>
</AccordionGroup>

## Advanced formatting with Enter Text syntax

When you choose **Enter Text**, you can enter Gavel formatting syntax to apply calculations, transformations, or conditional logic to the field value. PDF syntax is slightly different from Word syntax:

| Context       | Syntax format                    |
| ------------- | -------------------------------- |
| Word document | `{{ capitalize(TextVariable) }}` |
| PDF field     | `${ capitalize(TextVariable) }`  |

PDF syntax uses a single set of curly brackets with a dollar sign instead of double curly brackets. To build the correct syntax:

1. Use the Word add-in or the [Formatting Questions page](https://helpdocs.gavel.io/workflows/formatting-questions) to generate the syntax you need.
2. Remove one set of brackets and add a `$` before the remaining opening bracket.
3. Paste the result into the **Enter Text** field.

For example, to format a number as currency in a PDF field, enter:

```text theme={null}
${ currency(numbervariable) }
```

### Splitting a number across multiple fields

Some forms — such as those with a Social Security Number or phone number — use separate fields for different digit groups. You can split a number variable across fields using slice notation:

```text theme={null}
${ str(NumberVariable)[0:3] }
```

In this example, `0` is the start position and `3` is the end position (the first through fourth characters). Adjust the start and end positions for each field to match the digit groupings in your form.

<Note>
  PDF syntax is mostly the same as the simple variable syntax used in workflow question logic, so you can reuse the same expressions you use when [referencing prior answers in the questionnaire.](https://helpdocs.gavel.io/workflows/formatting-questions)
</Note>

## Repeating items in PDF fields

If your questionnaire includes a repeating item (for example, a list of parties or assets), you can tag PDF fields to specific instances of those repeating values. Open the PDF Tagger, select the relevant field, and choose the repeating item variable and the instance you want to map to that field.

<Warning>
  PDFs have a fixed layout — there is no way for Gavel to dynamically add rows or pages to a PDF the way it can in a Word document. Plan your PDF form with a fixed number of rows for repeating data, and map each row's fields to the corresponding repeating item instance.
</Warning>

## Adding fillable fields to a PDF that has none

If your PDF does not have any fillable fields yet, you need to add them before uploading to Gavel.

<Steps>
  <Step title="Upload the PDF to Gavel Document Templates">
    Go to the **Document Templates** section of your Gavel dashboard and upload the PDF. Gavel unlocks the PDF structure, making it editable.
  </Step>

  <Step title="Download the unlocked version">
    After uploading, download the version stored in Gavel. This is the file you will add fields to.
  </Step>

  <Step title="Add fields using the PDF Renamer">
    Visit `start.gavel.io/pdf` and upload the downloaded file. Use the PDF Renamer to add text fields, checkboxes, or signature fields where needed.
  </Step>

  <Step title="Upload the final version to your workflow">
    Upload the updated PDF to your workflow's Document Templates tab and begin tagging.
  </Step>
</Steps>