> ## 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.

# File Uploads

> Add a File Upload question to collect supporting documents from respondents, and learn how to embed or reference uploaded files in your output documents.

The **File Upload** question type lets respondents attach a document or image directly within your Gavel questionnaire. This is useful any time you need supporting materials alongside the form data — a prior agreement, identification document, photo, or exhibit. You configure the question like any other in the Builder, and Gavel handles the upload and storage automatically.

Each File Upload question allows the respondent to upload **one file at a time**. If your workflow needs multiple separate files, add multiple File Upload questions — one per file.

***

## Accepted file types

File Upload questions accept the following file formats:

| Type      | Extensions                                         |
| --------- | -------------------------------------------------- |
| Documents | `.pdf`, `.docx`, `.doc`, `.txt`, `.rtf`            |
| Images    | `.png`, `.jpg` / `.jpeg`, `.tiff`, `.gif`, `.heic` |

<Note>
  Respondents can only upload one file per File Upload question. If you need multiple files, add multiple File Upload questions to your workflow.
</Note>

***

## Adding a File Upload question

To add a File Upload question to your workflow:

1. In the Builder, click **+ Question** or **+ New → Question**.
2. Select **File Upload** from the question type list.
3. Write the question label that will prompt the respondent (for example, "Please upload a copy of your current lease agreement.").
4. Note the **variable name** Gavel assigns to the question — you will use this to reference the uploaded file in your output documents.

<Tip>
  Use the **Settings** tab on the question to add informational text (an info bubble) that tells respondents exactly what file format and content you expect. This reduces confusion and re-submissions.
</Tip>

***

## Referencing uploaded files in output documents

How you handle an uploaded file in your output document depends on the expected file size.

### Embed the file inline (small files)

For small files — such as a signature image, a single-page exhibit, or a compact PDF — you can embed the uploaded file directly into your output Word document. Insert the variable tag wherever you want the file to appear:

```text theme={null}
{{ FileUploadVariable }}
```

Gavel copies the uploaded file directly into the generated document at that location.

### Control the display size

To limit how large the embedded file appears in the document, specify a width:

```text theme={null}
{{ FileUploadVariable.show(width="1in") }}
```

Replace `"1in"` with any valid measurement. This is particularly useful for images where you want a consistent display size regardless of the original file dimensions.

### Display only the file name

If you want to reference the file in your document without embedding it — for example, to list the name of an attached exhibit — use:

```text theme={null}
{{ my_file[0].filename }}
```

Replace `my_file` with your File Upload question's variable name.

### Large files: use email delivery instead

If you expect respondents to upload large files (multi-page PDFs, high-resolution images), do **not** embed the variable in your output document. Large embedded files can cause performance issues. Instead, configure the workflow to email the uploaded file to you when the questionnaire is submitted.

You can set this up in the **Document Settings** of your workflow by enabling the email delivery option for file uploads.

<Warning>
  Embedding large files using `{{ FileUploadVariable }}` can significantly slow down document generation. For anything beyond a single page or small image, use the email delivery approach instead.
</Warning>

***

## Common use cases

<CardGroup cols={2}>
  <Card title="Identification documents" icon="id-card">
    Ask clients to upload a government-issued ID as part of a client intake workflow. Reference the filename in your intake summary document.
  </Card>

  <Card title="Prior agreements" icon="file-text">
    Collect an existing lease, contract, or deed to accompany a drafting workflow. Store the upload alongside the generated output for your records.
  </Card>

  <Card title="Photos and images" icon="image">
    Accept property photos, inspection images, or signatures captured as image files. Embed small images directly into the generated document using the size-controlled syntax.
  </Card>

  <Card title="Exhibits and attachments" icon="paperclip">
    Accept a supporting PDF that will be attached alongside the generated document. Display the filename in the main document body for reference.
  </Card>
</CardGroup>

***

## Tips

* **Label clearly:** Write a specific, unambiguous question label. "Upload a file" is too vague. "Upload a signed copy of your current lease (PDF or Word)" is much better.
* **Set expectations in the info bubble:** Use the question's info bubble to tell respondents what file types are accepted and approximately what size is appropriate.
* **One upload per question:** If you need several distinct files (front of ID, back of ID, supporting letter), add a separate File Upload question for each one.
* **Test the upload:** Run through your workflow in Preview mode and upload a real file to confirm that the variable renders correctly in your output document.