Theme integration

Optical Form works on any Shopify theme with no developer. 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 nests them under the main product line and hides their controls, mirroring how the bundle reads at checkout.

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.