Options & variants

My option selector (color/size) is empty

<change-option> needs to know which option to bind. With neither name nor group, it resolves no option and renders nothing (SSK-204). Add name="Color" or a 1-based group="1". Remember group is 1-based, so group="0" resolves nothing (SSK-207).

The picker shows on some products but not others / customers get the default variant

The classic multi-product-route trap. A change-option whose name doesn’t match any of the current product’s option names self-hides (display: none) instead of erroring - so a hardcoded name="Size"/name="Color" picker on a dynamic /products/[handle] page renders on products that happen to have those options and silently vanishes on the rest. The page looks fine; the shopper just has no control, and add-to-cart resolves to the default variant - the “wrong item ships” class of bug (SSK-208, and SSK-209 on server-rendered output). Fix: use the positional group="1"/"2"/"3" picker set (Shopify allows at most three option groups, so three blocks cover every product; extras self-hide) - blueprint in build-patterns §2.2 “Option pickers on multi-product routes”. Verify against products with different option shapes (a 1-option and a 3-option product at least) - testing the one product you were asked about and declaring the route fixed is exactly how this ships.

Option pills / swatches / radios don’t appear

<change-option> clones its first inner <option-value> (or <option>/radio wrapper) once per option value, so the first option-value is the template - and show-option-title/show-option-swatch must live inside an option-value, which must live inside change-option (SSK-108). If those pieces are misnested there’s no template to clone. Keep show-option-title (the value’s text) and show-option-swatch type="color|image" inside option-value. (The group name and the selected value are separate displayers - show-option-label and show-active-option-title.)

My value-option / show-label / show-swatch render nothing

Those tags were renamed in the option-system update: value-option → option-value, show-label → show-option-title, show-swatch → show-option-swatch. The old names are now unknown custom elements, so they never upgrade and stay inert. The validator flags each with SSK-301 and the exact new name - rename them.

empty-cart renders nothing (renamed) - and never use it as the empty-state message

empty-cart was renamed to clear-cart: it is a click-to-act control that removes every line from the cart. The old name read like “the empty-cart message box” and was getting used as a status container - which shipped a focusable, screen-reader-announced button that silently wiped the shopper’s cart when activated. That’s why no alias was kept. For an actual “your cart is empty” message, use a plain element styled off the cart root’s emptiness state: storesynk-cart[ss-empty] .cart-empty-message { display: block } (blueprint: build-patterns §2.6).

Selecting an option doesn’t update the price/SKU/stock

The variant-level displayers (show-price, show-compare-price, show-sku, show-barcode, show-stock, show-weight, show-unit-price) update only when <storesynk-product> re-emits sf:variant-change after an option change. If they never update, the displayer is likely outside the product (SSK-102) or the change-option isn’t resolving a real option (SSK-204), so no variant change ever fires.

The quantity stepper buttons do nothing

increase-quantity, decrease-quantity, and input-quantity are driven by their <change-quantity> parent, which owns the clamp logic. Outside change-quantity they have nothing to step (SSK-108). Nest them inside <change-quantity min="1" max="…">.

---

Imported from the Storesynk skill v0.1.0 (references/known-issues.md). To change this page, change it there.