Theme integration

Optical Form works on any Online Store 2.0 theme — the ones that let you add blocks from the theme editor — and needs no developer to install. It is verified on Dawn and Horizon; for custom themes there are adapters and the hooks below. This page summarizes the integration layer for anyone who wants to customize it. For the block and embed visual settings, see Button & cart (theme).

Variant resolution (theme-agnostic)

The drawer and trigger are standalone web components that are not re-rendered on variant change. So Optical Form resolves the current variant lazily (at open and at add-to-cart), in this priority order:

1. Merchant hook: window.OpticalFormHooks.getVariantId(triggerEl)
2. Configurable block selector (the Variant input selector setting)
3. Standard product form input [name="id"] (Dawn/Horizon and most themes)
4. URL parameter ?variant=
5. Fallback to the server-rendered value

Hooks (no fork required)

window.OpticalFormHooks = {
  // Return the selected variant id (highest priority).
  getVariantId(triggerEl) { return /* variant id */; },
  // Optional: override the price (in cents) for a variant.
  getVariantPrice(variantId, triggerEl) { return undefined; },
  // Optional: turn off cart bundle grouping.
  disableCartGrouping: false,
};

Cart grouping

Add-ons and accessories are added as separate line items linked via parent_id (Shopify’s native bundle — needed for cascade-remove, checkout and order emails). Since themes render them as flat rows, CartBridge reorders them so each child sits directly under its parent line, and tags them ofd-bundle-parent / ofd-bundle-child.

That’s where it stops: it does not hide the children’s quantity or remove controls, and the app ships no cart CSS at all. Hiding a control never prevented the action — the line can still be changed and removed through the API — and that same row is shared by other apps (warranties, shipping insurance), so hiding their remove button would strand the shopper with a third party’s charge. Keeping the order coherent is the server’s job, not CSS’s.

To fine-tune how it looks there are two levers on the app embed: the Compact the add-on lines in the cart checkbox (cart_tidy_addons, off by default) and the Custom CSS field. See Design & cart.

Cart selectors and the after-add behavior are set in the app embed — see Button & cart. CartBridge auto-detects most themes’ patterns; you only need to override selectors on non-standard themes.

Full reference

The technical detail (resolver, CartBridge, selectors) lives in INTEGRATION.md inside the app extension: extensions/optical-form-ext/INTEGRATION.md.