---
title: "Form - Liquid Tag Reference"
source: https://support.storeconnect.com/articles/form-tag-reference
type: article
format: markdown
site: StoreConnect Support — product and developer documentation for StoreConnect
site_index: https://storeconnect.com/llms.txt
docs_index: https://support.storeconnect.com/llms.txt
note: Append .md to any page or article URL on this site to get its Markdown form.
---
# Form - Liquid Tag Reference

The `{% form %}` block tag generates an HTML form with built-in handling for submissions and validation. It automatically wraps content in a `<form>` element, includes CSRF protection, and provides a `form` drop that exposes fields, their attributes, and validation errors.

## Syntax


```liquid

{% form "form-type" [, option: value, ...] %}
  <!-- Form fields and content -->
{% endform %}
```


| Property | Value |
|----------|-------|
| **Tag Name** | `form` |
| **Type** | Block tag |
| **Source** | Hydrofoil (core) |

## Description

The `form` tag provides form rendering and submission handling in StoreConnect Liquid templates. It handles:
- Automatic form wrapping with correct `action`, `method`, and CSRF protection
- Field definitions and accessibility attributes through the **form drop**
- Validation error tracking and display
- Submission state preservation for re-displaying user input on validation failure

For comprehensive usage patterns, see [Liquid forms guide](liquid-forms-guide).

## Form drop structure
Inside a `{% form %}` block, you can access a `form` drop with the following attributes:

### Form drop attributes
| Attribute | Type | Description |
|-----------|------|-------------|
| `fields` | Collection[FormField] | Every field the form type defines, looked up by name as `form.fields["field_name"]` |
| `errors` | Collection[FormError] | Every validation error on the form, including those not tied to a single field |
| `path` | String | The form's submission URL path |

`fields`, `errors` and `path` are the whole drop. There is no shorthand attribute for a field.

### Field access pattern
Every field is reached through `fields`, keyed by the field name:


```liquid

{{ form.fields["email"].value }}
```


A bare `form.username` is not a field. `FormDrop` defines no such attribute, so the expression renders as an empty string and the rest of the page renders normally. The failure is silent in the page: nothing marks the spot, and `undefined method username` is reported only to the Console.

The key can be a variable, so a field name can be built at render time:


```liquid

{% assign field_name = "email" %}
{{ form.fields[field_name].value }}
```


## Field attributes
Each field in a form has the following attributes:

| Attribute | Type | Description |
|-----------|------|-------------|
| `name` | String | The HTML `name` attribute for the field. Use this in `<input>` elements. |
| `id` | String | The HTML `id` attribute for the field (if assigned by the form) |
| `value` | String | The current value of the field. Preserved on re-render after validation failure. |
| `original_value` | String | The value of the field before the current request (useful for detecting changes) |
| `required?` | Boolean | Whether the field is required |
| `errors` | Array | Array of error messages specific to this field |

A field carries no label. Write the label text yourself and wire it to the field with `for` and `id`.

### Field rendering example

```liquid

<div class="field">
  <label for="{{ form.fields["email"].id }}">Email address</label>
  <input 
    type="email" 
    id="{{ form.fields["email"].id }}"
    name="{{ form.fields["email"].name }}" 
    value="{{ form.fields["email"].value }}"
    {% if form.fields["email"].required? %}required{% endif %}>
  {% assign email = form.fields["email"] %}
  {% if email.errors != blank %}
    <span class="error-message">{{ email.errors.messages | join: "; " }}</span>
  {% endif %}
</div>
```


## Error handling
`form.errors` is a collection of **FormError** objects: one per field that failed, plus one carrying the field name `base` for errors that belong to the form as a whole. It is not a list of strings.

| On a FormError | Type | Holds |
|----------------|------|-------|
| `field` | String | The field the error belongs to, or `base` for the form itself |
| `messages` | Collection[String] | The messages, without the field name |
| `full_messages` | Collection[String] | The messages, each prefixed with the field name |

Because each error holds a list, rendering them takes two loops:


```liquid

{% for error in form.errors %}
  {% for message in error.full_messages %}
    <li>{{ message }}</li>
  {% endfor %}
{% endfor %}
```


Outputting `{{ error }}` directly renders the drop, not the message.

`form.errors.size` is the test for whether a submission failed. A field carries its own `form.fields["email"].errors`, but that is a single FormError rather than a collection, so test it with `!= blank` rather than `.size`, which raises on it.

Field values survive a failed submission through `form.fields["email"].value`, so a re-rendered form keeps what the customer typed.

For the display patterns built on this, see [Liquid forms guide](liquid-forms-guide).

## Form parameters
When creating a form, you can pass options that control the form's behavior:

### Standard parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `product` | ProductDrop | The product for `add-to-cart` forms (preferred over `product_id`) |
| `product_id` | String | The product ID for `add-to-cart` forms (use `product` instead when possible) |
| `id` | String | HTML `id` attribute for the `<form>` element |
| `class` | String | HTML `class` attribute for the `<form>` element |
| `data-*` | String | Custom data attributes are passed through to the form element |

### Form-specific parameters
Different form types accept different parameters. For example:


```liquid

{% form "remove-voucher", voucher: current_voucher %}
  <button type="submit">Remove</button>
{% endform %}

{% form "add-to-cart", product: current_product, id: "ProductForm" %}
  <!-- Fields -->
{% endform %}

{% form "checkout-customer-information", class: "form-compact" %}
  <!-- Fields -->
{% endform %}
```


## Registered form names
StoreConnect provides many built-in form types. See [Liquid forms reference](liquid-forms-reference) for the complete list, including:

- **Authentication:** `login`, `register`, `forgot-password`, `reset-password`, `accept-invitation`
- **Cart & Checkout:** `add-to-cart`, `cart`, `checkout-customer-information`, `checkout-shipping-information`, `payment`
- **Promotions:** `apply-voucher`, `remove-voucher`, `apply-promo-code`
- **Account:** `account`, `account-missing-details`
- **Custom:** `custom-form` (for CMS-defined forms)
- **Other:** `privacy-settings`, `geolocation-select`, `booking-attendee-add`, and more

## Common form patterns
### Pattern 1: basic form with field rendering

```liquid

{% form "register" %}
  <div class="form-group">
    <label for="{{ form.fields["firstname"].id }}">First name</label>
    <input 
      type="text" 
      id="{{ form.fields["firstname"].id }}"
      name="{{ form.fields["firstname"].name }}" 
      value="{{ form.fields["firstname"].value }}"
      {% if form.fields["firstname"].required? %}required{% endif %}>
  </div>

  <div class="form-group">
    <label for="{{ form.fields["email"].id }}">Email address</label>
    <input 
      type="email" 
      id="{{ form.fields["email"].id }}"
      name="{{ form.fields["email"].name }}" 
      value="{{ form.fields["email"].value }}"
      {% if form.fields["email"].required? %}required{% endif %}>
  </div>

  <button type="submit">Create Account</button>
{% endform %}
```


### Pattern 2: error display

```liquid

{% form "login" %}
  {% render "form_errors", errors: form.errors %}

  {% assign username = form.fields["username"] %}
  <div class="form-group {% if username.errors != blank %}has-error{% endif %}">
    <label for="username">Username</label>
    <input 
      type="text" 
      id="username"
      name="{{ form.fields["username"].name }}" 
      value="{{ form.fields["username"].value }}"
      class="{% if username.errors != blank %}is-invalid{% endif %}">
    {% if username.errors != blank %}
      <small class="form-text text-danger">{{ username.errors.messages | join: "; " }}</small>
    {% endif %}
  </div>

  <button type="submit">Log in</button>
{% endform %}
```


### Pattern 3: add to cart with product context

```liquid

{% form "add-to-cart", product: current_product, id: "AddToCartForm" %}
  <div class="form-group">
    <label for="quantity">Quantity</label>
    <input 
      type="number" 
      id="quantity"
      name="{{ form.fields["quantity"].name }}" 
      value="{{ form.fields["quantity"].value | default: 1 }}"
      min="1"
      max="100">
  </div>

  {% render "form_errors", errors: form.errors %}

  <button type="submit" class="btn btn-primary">Add to Cart</button>
{% endform %}
```


### Pattern 4: custom form from CMS

```liquid

{% if my_contact_form %}
  {% form "custom-form", custom_form: my_contact_form, id: "ContactForm" %}
    {% for question in my_contact_form.questions %}
      <div class="form-group {% if question.is_required %}required{% endif %}">
        <label for="q_{{ question.id }}">{{ question.label }}</label>
        
        {% case question.question_type %}
        {% when "text" %}
          <input 
            type="text" 
            id="q_{{ question.id }}"
            name="{{ question.input_name }}" 
            value="{{ question.answer_value }}"
            {% if question.is_required %}required{% endif %}>
        
        {% when "text_area" %}
          <textarea 
            id="q_{{ question.id }}"
            name="{{ question.input_name }}"
            {% if question.is_required %}required{% endif %}>{{ question.answer_value }}</textarea>
        
        {% when "picklist" %}
          <select 
            id="q_{{ question.id }}"
            name="{{ question.input_name }}"
            {% if question.is_required %}required{% endif %}>
            <option value="">-- Select --</option>
            {% for option in question.picklist_values %}
              <option value="{{ option }}" {% if question.answer_value == option %}selected{% endif %}>
                {{ option }}
              </option>
            {% endfor %}
          </select>
        {% endcase %}
      </div>
    {% endfor %}

    {% render "form_errors", errors: form.errors %}

    <button type="submit">Send</button>
  {% endform %}
{% endif %}
```

---

## Follow StoreConnect

- [Email Newsletter](https://storeconnect.com/c/lp-newsletter)
- [LinkedIn Newsletter](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7444956928444862464)
- [YouTube](https://www.youtube.com/channel/UCngKdP2x8l1wcbAKW3tvU8g)
- [LinkedIn](https://www.linkedin.com/company/storeconnect)
- [X / Twitter](https://x.com/storeconnecthq)

## Popular Links

- [Partners](https://storeconnect.com/partners)
- [Become a Partner](https://storeconnect.com/become-a-partner)
- [News](https://storeconnect.com/articles/news)
- [Events](https://storeconnect.com/articles/events)
- [Feature Comparison](https://storeconnect.com/how-we-compare)
- [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT)
- [Book a Demo](https://storeconnect.com/contact)

## Documentation

- [Help documentation](https://support.storeconnect.com/help-documentation)
- [AI agents](https://support.storeconnect.com/ai)
- [Videos & tutorials](https://support.storeconnect.com/videos-tutorials)
- [Developer reference](https://support.storeconnect.com/developer-reference)
- [Release notes](https://support.storeconnect.com/release-notes)
- [Troubleshooting](https://support.storeconnect.com/troubleshooting)
- [Trust Center](https://trust.getstoreconnect.com/)
- [Status Page](https://status.storeconnect.com/)

## Contact

- info@getstoreconnect.com
- US +1 415 745 3230
- AUS +61 2 8365 2308

100 S Ashley Dr, Suite 600-2461
Tampa FL 33602-600 USA

Level 22, Sydney Place
180 George Street
Sydney, NSW, 2000, AUS

## Machine-readable

- [Site index for agents](https://storeconnect.com/llms.txt): curated map of the StoreConnect site in llms.txt format
- [Documentation index for agents](https://support.storeconnect.com/llms.txt): full technical and product documentation map

Every page and article on this site has a Markdown rendering: append `.md` to its URL.

Continue in Markdown: [Help documentation](https://support.storeconnect.com/help-documentation.md) · [Developer reference](https://support.storeconnect.com/developer-reference.md) · [Videos & tutorials](https://support.storeconnect.com/videos-tutorials.md) · [Release notes](https://support.storeconnect.com/release-notes.md)

---

StoreConnect Support — https://support.storeconnect.com/articles/form-tag-reference