For most stores, the theme setup wizard handles everything. This guide is for developers building custom themes or needing manual control over option placement and behavior.
App Embed vs App Block
Product Options uses two integration methods:
App Embed - A global script that loads on every page. Handles form submission, validation, and cart integration. Enable in: Theme Editor > App embeds > Product Options
App Block - Placed on product pages to render the options form. Add in: Theme Editor > Add block > Apps > Product Options
Both must be enabled for full functionality.
Manual Block Placement
For custom product templates:
Open your theme code
Navigate to the product template (e.g.,
sections/main-product.liquid)Ensure the template supports app blocks in the product form area
The block will be available for placement via the theme editor
For vintage themes without app block support, contact support for manual integration code.
Block Settings
Click the placed block in the theme editor to configure it.
Layout
Form Elements - every option rendered one after another, the way a normal form reads
Accordion Collapsible - each option is a collapsible row showing the chosen value in its header, with Add to Product and Skip buttons in the panel. Skipping clears whatever was entered in that option, so a skipped option carries no value and no charge.
Value image size - how big value images are, from 40 to 240 pixels. Everything else positions itself from this, so images stay aligned whatever you choose.
Title and Description - optional text above the options.
Colours - accent (used for the selected state), border, card background, and the completed and skipped colours for accordion rows.
Form Fields - background, hover background, max width, border width, border colour, corner radius and dropdown chevron size. These apply to every field type at once: native dropdowns, text inputs, the colour and image dropdowns, the quantity picker, and the file-upload buttons.
Button Text - the wording of the accordion’s Add and Skip buttons, and the title of the additional-options group.
Layout & Spacing - block border width, the gap below each option, and padding around the block.
After Adding to Cart - stay on the page, go to the cart, or go straight to checkout.
Form Integration
Product Options integrates with the product form automatically. When customers submit the form:
Options are validated (required fields checked)
Selections are added to cart as line item properties
Priced options add additional line items or modify the product price
The app handles this integration through the app embed script.
Customizing Option Display
For advanced styling beyond Custom CSS:
Identify the option’s HTML structure using browser dev tools
Target elements with your theme’s CSS
Use the CSS class reference from the Custom CSS article
Remember that the app generates HTML dynamically—avoid overly specific selectors that might break with updates.
Cart and Checkout
Selected options appear in cart and checkout as line item properties. The property format is:
property_name: selected_value
Your theme’s cart template should display line item properties. Most modern themes do this automatically. If not, add to your cart template:
{% for property in item.properties %}
{% unless property.last == blank %}
<p>{{ property.first }}: {{ property.last }}</p>
{% endunless %}
{% endfor %}