Theme selectors

The app finds your product form, price, variant picker, and cart lines by CSS selector. It ships a tuned set for every supported theme and a broad default set for the rest, which is why it works on most themes with no help.

A heavily customized theme can still put something where the defaults do not reach. There are two ways to fix that, and the first is almost always the better one.

1. Add the app’s own attribute

Nearly every selector begins with a data-gpo-… attribute that exists purely as a hook for you. Put that attribute on the element in your theme and the app finds it, with no selector to maintain and nothing that a theme update can rename.

<form action="/cart/add" method="post" data-gpo-product-form>
  …
  <button type="submit" data-gpo-product-atc>Add to cart</button>
</form>

The attribute for each selector is in the tables below.

2. Override the selector

Use this when you cannot edit the markup — a section you do not control, or an app rendering the form. Set it before the app’s script runs, in theme.liquid above </body>:

<script>
  window.GPOConfigs = window.GPOConfigs || {};
  window.GPOConfigs.theme = window.GPOConfigs.theme || {};
  window.GPOConfigs.theme.product = {
    ...(window.GPOConfigs.theme.product || {}),
    form: ['#my-product-form'],
    addToCartButton: '.my-atc-button'
  };
</script>

Your values are merged over the app’s, so you override only the keys you name.

Before either of these, check whether a setting does it. Widget placement moves the widget, and an app block positions it in the theme editor.

And tell us when a theme needs an override — a theme we fix is fixed for every store running it. See Contact support.

product

Used on product pages, and on featured-product sections elsewhere.

Key	Attribute hook	What the app does with it
form	data-gpo-product-form	The product form. This is the anchor for everything else — the options are rendered into it and validated on submit. Takes an array, tried in order
addToCartButton	data-gpo-product-atc	The add-to-cart button. Used to place the widget above it, and to block the submit when validation fails
paymentButton	—	The accelerated payment button. Hidden on products with options, because it would skip the form
quantity	—	The quantity input. Read so add-on quantities can follow the main product quantity
unitPrice	data-gpo-product-unit-price	The displayed price. Rewritten as the customer picks priced options
compareAtPrice	data-gpo-product-compare-at-price	The compare-at price, updated alongside it
variantSelector	data-gpo-product-variant-selector	The hidden input holding the chosen variant id. Read to know which variant is selected
variantActivator	data-gpo-product-variant-activator	The controls the customer clicks to change variant. Watched so variant conditions can react
variantWrapper	data-gpo-product-variant-wrapper	The block containing the variant pickers. Used to position the widget relative to them
imageContainer	data-gpo-product-image-container	The main image area. Where the Personalizer draws its live preview
image	data-gpo-product-image	The main product image itself
images	data-gpo-product-images	The gallery images, for the preview's Apply to setting
imageButton	data-gpo-product-image-button	The gallery thumbnails or arrows, watched so the preview follows the image on show
sticky.atcButton	data-gpo-sticky-atc	The add-to-cart button in a sticky bar, so it validates like the real one
sticky.variantActivator	data-gpo-sticky-variant-activator	The variant control in a sticky bar

form is the one that matters most. If the app cannot find the form, no options render at all — every other selector depends on it.

A sticky add-to-cart bar whose button is not covered by addToCartButton or sticky.atcButton can add to cart without validating, which produces orders with required options empty. See Theme and third-party notes.

collection

Used for quickview popups on collection pages.

Key	Attribute hook	What the app does with it
wrapper	data-gpo-collection-wrapper	The collection section, the area the app watches
item	data-gpo-collection-item	One product card inside it
productLink	data-gpo-collection-productLink	The link to the product, read to know which product a card is
quickViewActivator	data-gpo-collection-qvActivator	The control that opens the quickview, watched so the app knows to render
quickViewProductForm	data-gpo-collection-qvForm	The product form inside the quickview, where the options go

cart

Used on the cart page and in the cart drawer, for editing options and for keeping add-on lines tied to their parent item.

Key	Attribute hook	What the app does with it
form	data-gpo-cart-form	The cart form. Takes an array, tried in order
page	see below	How to read a line item on the cart page. Takes an array of shapes, tried in order
drawer	see below	The same for the cart drawer

page and drawer each hold a lineItem describing the parts of one cart row:

Part	Attribute hook (cart page)	What it is
key	data-gpo-cart-item-key	The row itself, carrying the line item key
image	data-gpo-cart-item-image	The row's thumbnail
details	data-gpo-cart-item-details	The title and properties block, where Edit Options is added
quantity.wrapper	data-gpo-cart-item-qty-wrapper	The quantity control, hidden on add-on lines
quantity.input	data-gpo-cart-item-qty	The quantity field
quantity.decrease / increase	data-gpo-cart-item-qty-decrease / -increase	The minus and plus buttons
removeButton	data-gpo-cart-item-remove-button	The remove link, hidden on add-on lines

The drawer uses the same parts with data-gpo-drawer-item-… instead of data-gpo-cart-item-….

These only matter if you use Hide quantity box and remove button for add-on products or Show “Edit Options” button in cart. With both off, the app does not touch the cart. See Cart page.

Notes

• Keys taking an array are tried in order and the first match wins, so you can add yours in front of the defaults rather than replacing them.
• Overriding a selector changes only where the app looks. It does not change what the options collect or how they are priced.
• An override applies to every product page on the store. For one product, target it in the selector itself.

Was this helpful?

Report an issue