{"title":"Form - Liquid Tag Reference","slug":"form-tag-reference","url":"https://support.storeconnect.com/articles/form-tag-reference","url_markdown":"https://support.storeconnect.com/articles/form-tag-reference.md","subtitle":null,"summary":"The `{% form %}` block tag generates an HTML form with built-in handling for submissions, validation, field access, and error display. Access form fields and errors through the form drop, and handle validation with per-field and form-level error objects.","type":"Developer_Documentation","video_url":"","keywords":"liquid, tags, form, block tag, form drop, form fields, form errors, form validation, storeconnect forms, form structure","last_modified":"2026-08-31T05:22:00+0000","body_markdown":"The `{% form %}` block tag generates an HTML form with built-in handling for submissions and validation. It automatically wraps content in a `\u003cform\u003e` element, includes CSRF protection, and provides a `form` drop that exposes fields, their attributes, and validation errors.\n\n## Syntax\n\n\n```liquid\n\n{% form \"form-type\" [, option: value, ...] %}\n  \u003c!-- Form fields and content --\u003e\n{% endform %}\n```\n\n\n| Property | Value |\n|----------|-------|\n| **Tag Name** | `form` |\n| **Type** | Block tag |\n| **Source** | Hydrofoil (core) |\n\n## Description\n\nThe `form` tag provides form rendering and submission handling in StoreConnect Liquid templates. It handles:\n- Automatic form wrapping with correct `action`, `method`, and CSRF protection\n- Field definitions and accessibility attributes through the **form drop**\n- Validation error tracking and display\n- Submission state preservation for re-displaying user input on validation failure\n\nFor comprehensive usage patterns, see [Liquid forms guide](liquid-forms-guide).\n\n## Form drop structure\nInside a `{% form %}` block, you can access a `form` drop with the following attributes:\n\n### Form drop attributes\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `fields` | Collection[FormField] | Every field the form type defines, looked up by name as `form.fields[\"field_name\"]` |\n| `errors` | Collection[FormError] | Every validation error on the form, including those not tied to a single field |\n| `path` | String | The form's submission URL path |\n\n`fields`, `errors` and `path` are the whole drop. There is no shorthand attribute for a field.\n\n### Field access pattern\nEvery field is reached through `fields`, keyed by the field name:\n\n\n```liquid\n\n{{ form.fields[\"email\"].value }}\n```\n\n\nA 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.\n\nThe key can be a variable, so a field name can be built at render time:\n\n\n```liquid\n\n{% assign field_name = \"email\" %}\n{{ form.fields[field_name].value }}\n```\n\n\n## Field attributes\nEach field in a form has the following attributes:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `name` | String | The HTML `name` attribute for the field. Use this in `\u003cinput\u003e` elements. |\n| `id` | String | The HTML `id` attribute for the field (if assigned by the form) |\n| `value` | String | The current value of the field. Preserved on re-render after validation failure. |\n| `original_value` | String | The value of the field before the current request (useful for detecting changes) |\n| `required?` | Boolean | Whether the field is required |\n| `errors` | Array | Array of error messages specific to this field |\n\nA field carries no label. Write the label text yourself and wire it to the field with `for` and `id`.\n\n### Field rendering example\n\n```liquid\n\n\u003cdiv class=\"field\"\u003e\n  \u003clabel for=\"{{ form.fields[\"email\"].id }}\"\u003eEmail address\u003c/label\u003e\n  \u003cinput \n    type=\"email\" \n    id=\"{{ form.fields[\"email\"].id }}\"\n    name=\"{{ form.fields[\"email\"].name }}\" \n    value=\"{{ form.fields[\"email\"].value }}\"\n    {% if form.fields[\"email\"].required? %}required{% endif %}\u003e\n  {% assign email = form.fields[\"email\"] %}\n  {% if email.errors != blank %}\n    \u003cspan class=\"error-message\"\u003e{{ email.errors.messages | join: \"; \" }}\u003c/span\u003e\n  {% endif %}\n\u003c/div\u003e\n```\n\n\n## Error handling\n`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.\n\n| On a FormError | Type | Holds |\n|----------------|------|-------|\n| `field` | String | The field the error belongs to, or `base` for the form itself |\n| `messages` | Collection[String] | The messages, without the field name |\n| `full_messages` | Collection[String] | The messages, each prefixed with the field name |\n\nBecause each error holds a list, rendering them takes two loops:\n\n\n```liquid\n\n{% for error in form.errors %}\n  {% for message in error.full_messages %}\n    \u003cli\u003e{{ message }}\u003c/li\u003e\n  {% endfor %}\n{% endfor %}\n```\n\n\nOutputting `{{ error }}` directly renders the drop, not the message.\n\n`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.\n\nField values survive a failed submission through `form.fields[\"email\"].value`, so a re-rendered form keeps what the customer typed.\n\nFor the display patterns built on this, see [Liquid forms guide](liquid-forms-guide).\n\n## Form parameters\nWhen creating a form, you can pass options that control the form's behavior:\n\n### Standard parameters\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `product` | ProductDrop | The product for `add-to-cart` forms (preferred over `product_id`) |\n| `product_id` | String | The product ID for `add-to-cart` forms (use `product` instead when possible) |\n| `id` | String | HTML `id` attribute for the `\u003cform\u003e` element |\n| `class` | String | HTML `class` attribute for the `\u003cform\u003e` element |\n| `data-*` | String | Custom data attributes are passed through to the form element |\n\n### Form-specific parameters\nDifferent form types accept different parameters. For example:\n\n\n```liquid\n\n{% form \"remove-voucher\", voucher: current_voucher %}\n  \u003cbutton type=\"submit\"\u003eRemove\u003c/button\u003e\n{% endform %}\n\n{% form \"add-to-cart\", product: current_product, id: \"ProductForm\" %}\n  \u003c!-- Fields --\u003e\n{% endform %}\n\n{% form \"checkout-customer-information\", class: \"form-compact\" %}\n  \u003c!-- Fields --\u003e\n{% endform %}\n```\n\n\n## Registered form names\nStoreConnect provides many built-in form types. See [Liquid forms reference](liquid-forms-reference) for the complete list, including:\n\n- **Authentication:** `login`, `register`, `forgot-password`, `reset-password`, `accept-invitation`\n- **Cart \u0026 Checkout:** `add-to-cart`, `cart`, `checkout-customer-information`, `checkout-shipping-information`, `payment`\n- **Promotions:** `apply-voucher`, `remove-voucher`, `apply-promo-code`\n- **Account:** `account`, `account-missing-details`\n- **Custom:** `custom-form` (for CMS-defined forms)\n- **Other:** `privacy-settings`, `geolocation-select`, `booking-attendee-add`, and more\n\n## Common form patterns\n### Pattern 1: basic form with field rendering\n\n```liquid\n\n{% form \"register\" %}\n  \u003cdiv class=\"form-group\"\u003e\n    \u003clabel for=\"{{ form.fields[\"firstname\"].id }}\"\u003eFirst name\u003c/label\u003e\n    \u003cinput \n      type=\"text\" \n      id=\"{{ form.fields[\"firstname\"].id }}\"\n      name=\"{{ form.fields[\"firstname\"].name }}\" \n      value=\"{{ form.fields[\"firstname\"].value }}\"\n      {% if form.fields[\"firstname\"].required? %}required{% endif %}\u003e\n  \u003c/div\u003e\n\n  \u003cdiv class=\"form-group\"\u003e\n    \u003clabel for=\"{{ form.fields[\"email\"].id }}\"\u003eEmail address\u003c/label\u003e\n    \u003cinput \n      type=\"email\" \n      id=\"{{ form.fields[\"email\"].id }}\"\n      name=\"{{ form.fields[\"email\"].name }}\" \n      value=\"{{ form.fields[\"email\"].value }}\"\n      {% if form.fields[\"email\"].required? %}required{% endif %}\u003e\n  \u003c/div\u003e\n\n  \u003cbutton type=\"submit\"\u003eCreate Account\u003c/button\u003e\n{% endform %}\n```\n\n\n### Pattern 2: error display\n\n```liquid\n\n{% form \"login\" %}\n  {% render \"form_errors\", errors: form.errors %}\n\n  {% assign username = form.fields[\"username\"] %}\n  \u003cdiv class=\"form-group {% if username.errors != blank %}has-error{% endif %}\"\u003e\n    \u003clabel for=\"username\"\u003eUsername\u003c/label\u003e\n    \u003cinput \n      type=\"text\" \n      id=\"username\"\n      name=\"{{ form.fields[\"username\"].name }}\" \n      value=\"{{ form.fields[\"username\"].value }}\"\n      class=\"{% if username.errors != blank %}is-invalid{% endif %}\"\u003e\n    {% if username.errors != blank %}\n      \u003csmall class=\"form-text text-danger\"\u003e{{ username.errors.messages | join: \"; \" }}\u003c/small\u003e\n    {% endif %}\n  \u003c/div\u003e\n\n  \u003cbutton type=\"submit\"\u003eLog in\u003c/button\u003e\n{% endform %}\n```\n\n\n### Pattern 3: add to cart with product context\n\n```liquid\n\n{% form \"add-to-cart\", product: current_product, id: \"AddToCartForm\" %}\n  \u003cdiv class=\"form-group\"\u003e\n    \u003clabel for=\"quantity\"\u003eQuantity\u003c/label\u003e\n    \u003cinput \n      type=\"number\" \n      id=\"quantity\"\n      name=\"{{ form.fields[\"quantity\"].name }}\" \n      value=\"{{ form.fields[\"quantity\"].value | default: 1 }}\"\n      min=\"1\"\n      max=\"100\"\u003e\n  \u003c/div\u003e\n\n  {% render \"form_errors\", errors: form.errors %}\n\n  \u003cbutton type=\"submit\" class=\"btn btn-primary\"\u003eAdd to Cart\u003c/button\u003e\n{% endform %}\n```\n\n\n### Pattern 4: custom form from CMS\n\n```liquid\n\n{% if my_contact_form %}\n  {% form \"custom-form\", custom_form: my_contact_form, id: \"ContactForm\" %}\n    {% for question in my_contact_form.questions %}\n      \u003cdiv class=\"form-group {% if question.is_required %}required{% endif %}\"\u003e\n        \u003clabel for=\"q_{{ question.id }}\"\u003e{{ question.label }}\u003c/label\u003e\n        \n        {% case question.question_type %}\n        {% when \"text\" %}\n          \u003cinput \n            type=\"text\" \n            id=\"q_{{ question.id }}\"\n            name=\"{{ question.input_name }}\" \n            value=\"{{ question.answer_value }}\"\n            {% if question.is_required %}required{% endif %}\u003e\n        \n        {% when \"text_area\" %}\n          \u003ctextarea \n            id=\"q_{{ question.id }}\"\n            name=\"{{ question.input_name }}\"\n            {% if question.is_required %}required{% endif %}\u003e{{ question.answer_value }}\u003c/textarea\u003e\n        \n        {% when \"picklist\" %}\n          \u003cselect \n            id=\"q_{{ question.id }}\"\n            name=\"{{ question.input_name }}\"\n            {% if question.is_required %}required{% endif %}\u003e\n            \u003coption value=\"\"\u003e-- Select --\u003c/option\u003e\n            {% for option in question.picklist_values %}\n              \u003coption value=\"{{ option }}\" {% if question.answer_value == option %}selected{% endif %}\u003e\n                {{ option }}\n              \u003c/option\u003e\n            {% endfor %}\n          \u003c/select\u003e\n        {% endcase %}\n      \u003c/div\u003e\n    {% endfor %}\n\n    {% render \"form_errors\", errors: form.errors %}\n\n    \u003cbutton type=\"submit\"\u003eSend\u003c/button\u003e\n  {% endform %}\n{% endif %}\n```\n"}