@shopify/theme-product-form

Theme Product Form helps theme developers create and manage the state of their product forms. The library is decoupled from any rendering logic, allowing it to be used across any number of rendering engines, e.g. Liquid, VanillaJS, Handlebars, React, Vue.js, etc.

Browser Support

This library is compatible with the following browsers:

Getting Started

Theme Scripts can be used in any theme project. To take advantage of the benefits of semantic versioning and easy updates, we recommend using NPM or Yarn to include them in your project:

yarn add @shopify/theme-product-form

or

npm install --save @shopify/theme-product-form

and then import the functions you wish to use through ES6 imports:

import {ProductForm} from '@shopify/theme-product-form'

NOTE: This package has a peerDependency on @shopify/theme-product.

If you prefer not to use a package manager, you can download the latest version of Theme Product Form and include it in your project manually from the following links:

• theme-product-form.js
• theme-product-form.min.js

NOTE: Because theme-product-form.js dependents on theme-product.js, include theme-product.js before theme-product-form.js.

Methods

ProductForm(formElement, product, options)

Creates a new instance of a product form controller. This controller binds itself to form inputs and fires optional callback functions whenever the product form state changes.

A basic product form example in Liquid that is compatible with ProductForm would look something like the following:

  {% form 'product', product, data-product-form: '', data-product-handle: product.handle %}
    {% unless product.has_only_default_variant %}
      {% for option in product.options_with_values %}
        <div class="js-enabled">

            <label for="Option{{ option.position }}">
              {{ option.name }}
            </label>

            {% comment %}
              All inputs that have `name=options[Name]` will be picked up by
              ProductForm, registered as an option input, and made available
              at ProductForm.optionsInputs
            {% endcomment %}

            <select name="options[{{ option.name | escape }}]" id="Option{{ option.position }}">
              {% for value in option.values %}
                <option value="{{ value | escape }}">
                    {{ value }}
                </option>
              {% endfor %}
            </select>
        </div>
      {% endfor %}
    {% endunless %}

    {% comment %}
      In order for this form to submit, it needs to contain an input with name="id".
      ProductForm() will automatically create this input (or make sure it has the
      right value set if it already exists) on form submit based on the
      currently selected variant. However, if JS is disabled we need a fallback.

      Include a single <select> element which allows users to select all variants
      as a fallback and present it only when JS is disabled. In addition,
      make sure you hide the option inputs declared above, like we do with the
      `.js-enabled` class which only shows its contents when JS is enabled.
    {% endcomment %}
    
      </select>
        {% for variant in product.variants %}
          <option value="{{ variant.id }}">
              {{ variant.title }}
          </option>
        {% endfor %}
      
    

    {% comment %}
      Any input with `name="quantity"` will be picked up by ProductForm and
      registered as a quantity input. If a quantity input is not included, a
      default quantity of 1 is assumed.
    {% endcomment %}
    <label for="Quantity">{{ 'products.product.quantity' | t }}</label>
    <input min="1" value="1" name="quantity" id="Quantity" type="number">

    {% comment %}
      Line Item property inputs with `name="properties[NAME]"` will be picked up
      by ProductForm and registered as a properties input.
    {% endcomment %}
    <label for="Details">{{ 'products.product.details' | t }}</label>
    <textarea name="properties[Details]" id="Details"></textarea>

    <button type="submit">
        {{ 'products.product.add_to_cart' | t }}
    </button>

    {% comment %}
      Don't forget about the Dynamic Checkout buttons!
      https://help.shopify.com/en/themes/customization/store/dynamic-checkout-buttons
    {% endcomment %}
    {{ form | payment_button }}
  {% endform %}

To create a new instance of a product form controller, include the following in your theme:

import { ProductForm } from '@shopify/theme-product-form';

const formElement = document.querySelector('[data-product-form]');
const productHandle = formElement.dataset.productHandle;

// Fetch the product data from the .js endpoint because it includes
// more data than the .json endpoint. Alternatively, you could inline the output
// of {{ product | json }} inside a