> For the complete documentation index, see [llms.txt](https://docs.roadmap.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadmap.so/forms/add-a-form-to-your-theme.md).

# Add a form to your theme

Place a form in the theme editor, set the handle, and enable reCAPTCHA when needed.

Use this when the form is ready and you want it live on the storefront.

### Before you start

Have these ready first:

* the form has been created in **Forms**
* the form handle is confirmed in **Settings**
* your theme supports app blocks or app sections where you want the form to appear
* a reCAPTCHA v2 Invisible site key is ready if spam protection will be enabled

### Add the form block

{% stepper %}
{% step %}

#### Open the theme editor

Go to **Online Store** → **Themes** → **Customize**.
{% endstep %}

{% step %}

#### Choose the page template or section

Open the template where the form should appear.

Common placements are a dedicated page template, a multicolumn section, or the footer.
{% endstep %}

{% step %}

#### Add the Roadmap form block

Click **Add section** or **Add block**.

Open the **Apps** tab, then choose **Form Builder**.
{% endstep %}

{% step %}

#### Enter the form handle

In the block settings, paste the exact value from **Roadmap Form Handle**.

Use the handle, not the form name.
{% endstep %}

{% step %}

#### Add the reCAPTCHA site key if needed

If the form uses spam protection, add your **reCAPTCHA Site Key** in the block settings.

The matching secret key must also exist in the app settings.

Use [Enable reCAPTCHA spam protection](/forms/enable-recaptcha-spam-protection.md) for the full key setup.
{% endstep %}

{% step %}

#### Save and test

Save the theme, open the storefront, and submit a real test entry.
{% endstep %}
{% endstepper %}

### Block settings you will use most

#### Roadmap Form Handle

This tells the theme block which form to render.

If the wrong handle is used, the storefront form will not match the form you built.

#### reCAPTCHA Site Key

Use this only when **Enable reCAPTCHA spam protection** is turned on for the form.

The site key is the public key used by the storefront block.

### Placement tips

* Use a dedicated page template for long forms.
* Use a narrower section for short contact or lead forms.
* Keep enough spacing around the form so validation messages stay readable.
* Test on mobile after saving.

### Troubleshooting

#### The block shows no preview

Check the form handle first.

If the handle is correct, save the theme and test on the storefront.

#### reCAPTCHA is enabled but the form still fails

Check these first:

* the form toggle is enabled in **Settings**
* the theme block has the site key
* the app settings have the matching secret key

#### The wrong form appears

Check that the handle in the theme block matches the handle in the form settings exactly.

### Related guides

* [Building with forms](/forms/building-with-forms.md)
* [Enable reCAPTCHA spam protection](/forms/enable-recaptcha-spam-protection.md)
* [Customise form design](/forms/customise-form-design.md)
* [Email notifications and templates](/forms/email-notifications-and-templates.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.roadmap.so/forms/add-a-form-to-your-theme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.