# Build a form

URL: https://docs.sparklayer.io/help/forms/setup

Create a SparkLayer form, organise it into pages, fields and groups, add internal fields for your team and set its title, success message and notifications.

> **Quick summary**
>
> - Create a form at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) with **Start with a blank form**, or from a template. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - A form is made of pages, and each page holds fields. Groups bundle related fields together. Fields customers fill in go on the **Form** tab, and fields only your team sees go on the **Internal fields** tab.
> - The **Settings** tab controls the title, description, submit button text, language and success message customers see.
> - The templates come with a **Notification of submission** workflow that emails your team about each new entry. You can edit it on the **Workflows** tab. Workflows are on the Growth plan and above: see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).

## How it works

You build a form in the form builder, without code. Every form has the same structure:

| Level | What it is |
| --- | --- |
| **Form** | The main container. |
| **Pages** | Sections of the form. A short form can have one page; longer forms can have several steps. |
| **Fields** | The individual inputs customers fill in. See [Field types](https://docs.sparklayer.io/help/forms/field-types.md). |
| **Groups** | Related fields, nested together inside a group. |

The form builder has six tabs:

| Tab | What it's for |
| --- | --- |
| **Form** | The fields customers fill in, page by page. |
| **Preview** | How the form looks to buyers right now. |
| **Internal fields** | Fields only your team sees on each entry, such as the decision on an application. |
| **Workflows** | Your [automations](https://docs.sparklayer.io/help/forms/workflows.md): what happens when an entry comes in or a decision is made. |
| **Settings** | What buyers see (title, description, button text, language, success message) and settings for your team. |
| **Embed** | How to [add the form to your store](https://docs.sparklayer.io/help/forms/embedding-and-styling.md) or another website. |

The form's name and status (**Draft** or **Published**) show at the top. **Publish** appears while the form has unpublished changes. **More actions** has **View entries**, **Duplicate** and **Archive**.

## Create a form

1. In the SparkLayer Dashboard, go to **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)).
2. On the **Start from a template** card, click **Start with a blank form**. The form builder opens with an empty page.
3. On the **Settings** tab, enter a **Form title**, for example "Trade account request". Customers see this title when they view the form.
4. Optionally, enter an **Internal title**, such as "Trade account request (UK)". It's only shown in the Dashboard.
5. Click **Save** in the save bar.

Then [add fields](#add-fields) on the **Form** tab.

To start from a ready-made form instead, click **Wholesale Registration Form** or **Contact Us Form** on the same card. Each creates a draft you can edit before publishing. See [Start from a template](https://docs.sparklayer.io/help/forms.md#start-from-a-template).

## Add pages

Pages divide a form into sections. A single page suits short forms, where customers see everything at once. Use several pages when you have lots of fields, or want to break the form into steps with clearer progress.

1. On the **Form** tab, click **+ Add page above**. 
2. Give the page a **Title**, shown to customers as a heading. 
3. [Add fields](#add-fields) to the page. The order of pages sets the order customers move through the form. 

## Add fields

1. On the **Form** tab, click **Add field**, then choose a [field type](https://docs.sparklayer.io/help/forms/field-types.md).
2. Click **Edit** on the field to open its settings. They have three tabs: **Properties**, **Validation** and **Display logic**.
3. On **Properties**, enter a **Label** and any other settings you need (see the table below).
4. Drag the handle on a field to reorder it, or click the bin icon to delete it.

Changes save automatically to your draft. Customers only see them once you [publish](https://docs.sparklayer.io/help/forms/versions.md).

Each field on the **Form** tab shows its label (with \* when it's required) and its type, such as **Email** or **Select**. These are the settings on the **Properties** tab:

| Property | What it does |
| --- | --- |
| **Label** | The field name shown to customers. Required. |
| **Description** | Optional help text shown with the field. |
| **Required** | Customers must fill in the field before they can submit. |
| **Read only** | Shows the field but prevents editing. |
| **Repeatable** | Customers can add the field more than once. |
| **Placeholder** | Hint text inside the field. |
| **Default value** | Pre-filled content. Can use [data references](https://docs.sparklayer.io/help/forms/data-references.md), for example the logged-in customer's email. |

Rules on the **Validation** tab are covered in [Validation rules](https://docs.sparklayer.io/help/forms/validation.md), and the **Display logic** tab in [Conditional logic](https://docs.sparklayer.io/help/forms/conditional-logic.md).

## Group related fields

A **Group** field holds other fields, for example a "Contact information" group with first name, last name and email. Groups:

- Keep layouts clean and the form easier to read
- Structure complex data
- Let you apply display logic to several fields at once

### Repeatable groups

To let customers add the same set of fields more than once, turn on **Repeatable** for the group. This suits order lines, locations or team members. Customers can add, remove and reorder each set.

A field can be top-level (placed directly on a page), nested inside a group, or repeatable.

## Add internal fields

Internal fields are a second set of fields that only your team sees when reviewing an entry, for example a decision, reviewer notes or a button that runs a workflow. Customers never see them.

The **Wholesale Registration Form** template comes with these internal fields:

| Field | Type | What it's for |
| --- | --- | --- |
| **Decision** | Toggle | Approve or reject the application. |
| **Customer group** | Select | Shown when approved: the group, and so the prices, the buyer gets. |
| **Tax exempt** | Checkbox | Shown when approved. |
| **Apply decision** | Workflow trigger button | Runs the **Approve/Reject workflow**. |
| **Application status** | Select | Pending, Approved or Rejected. |
| **Error message** | Long text | Shown when a workflow fails. |

1. Open the form and go to the **Internal fields** tab.
2. Add fields in the same way as on the **Form** tab. Internal fields support everything the main form does, including pages, display logic, validation and workflows.
3. To run a workflow from a button, add a **Workflow trigger button** field and use the **Internal button clicked** trigger in [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md).

You fill in internal fields when you open an [entry](https://docs.sparklayer.io/help/forms/entries.md). Changes to them can also run workflows, with the **Internal field updated** trigger.

## Preview your form

1. Click the **Preview** tab.
2. Fill in the form to test fields, validation and logic.
3. Go back to the **Form** tab to make any changes.

Preview entries are kept separate from real ones. The preview has no logged-in customer, so test forms that rely on customer data on your store. See [Versions and publishing](https://docs.sparklayer.io/help/forms/versions.md#preview-a-draft).

## Configure form settings

Open the **Settings** tab to set what customers see and how your team manages entries, then click **Save** in the save bar.

| Card | Setting | What it does |
| --- | --- | --- |
| **What buyers see** | **Form title** | The title shown to customers filling in the form. |
| **What buyers see** | **Description** | A line of instructions under the title. |
| **What buyers see** | **Submit button text** | The wording on the submit button. |
| **What buyers see** | **Language** | Translates built-in text, like buttons and address lookup: Default (English), Dutch, French, German, Italian or Spanish. Your own labels aren't translated: see [Translate a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md#translate-a-form). |
| **What buyers see** | **Success message** | The message shown after a customer submits. It can include the customer's answers and other details with [data references](https://docs.sparklayer.io/help/forms/data-references.md), such as `{{name}}`. It can also use conditions, loops and HTML. |
| **For your team** | **Internal title** | A name only shown in the Dashboard, for example "Trade applications". Useful when it should differ from the public title. |
| **For your team** | **Read/unread tracking** | Marks entries as read or unread, and counts new ones on the Forms screen. |

## Get notified of new submissions

The **Wholesale Registration Form** and **Contact Us Form** templates come with a **Notification of submission** workflow, which emails your team whenever an entry is submitted.

To change the recipient or add more logic, open the **Workflows** tab and click **View** next to that workflow. For a blank form, add a workflow with the **Form submitted** trigger and a **Send email** step. See [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md).

> **Notification emails need workflows**
>
> Submission emails are sent by a workflow, and workflows are on the Growth plan and above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)). On a plan without them, no email is sent: check the form's [entries](https://docs.sparklayer.io/help/forms/entries.md) yourself for new submissions. Shopify Flow can't start from a SparkLayer form submission, so it can't send the email for you either.

## Field IDs and how answers are stored

Every field has an internal ID, used by conditional logic, workflows and data references. Keep IDs short, simple and consistent, so template references stay short.

**How answers are stored**

Answers are stored following the structure you build:

| Structure | Example |
| --- | --- |
| **Simple field** | `email` |
| **Nested field** | `contact.first_name` |
| **Repeatable group** | `items[instance1].quantity`, `items[instance1].sku`, `items[instance2].quantity`, `items[instance2].sku` |

You rarely need to work with these paths directly, but they help when building workflows or automations.

## Tips

- Group related fields together.
- Split very long pages into several pages.
- Avoid several levels of nested groups.
- Use consistent naming for labels and field IDs.

## Next steps

- [Versions and publishing](https://docs.sparklayer.io/help/forms/versions.md): Preview your draft and publish it as the live version.
- [Embed and style a form](https://docs.sparklayer.io/help/forms/embedding-and-styling.md): Add the form to your store.
- [Form workflows](https://docs.sparklayer.io/help/forms/workflows.md): Send emails and approve customers automatically.