Skip to content

How It Works

A walkthrough of the storefront experience as a shopper sees it, from page load to add-to-cart.

1. Page load

A shopper lands on a product page that has at least one diagram assigned. The Parts Diagram block:

  • Renders a placeholder skeleton inside its assigned section so the page layout stabilizes immediately.
  • Reads the product ID from the page and asks the API for the diagram(s) attached to that product.
  • Loads the storefront settings (layout, hover, display toggles) from the same API call.
  • Replaces the skeleton with the live diagram once data arrives, typically in under 300 ms on a warm cache.

2. First paint

The shopper sees:

  • The diagram image.
  • Numeric badges (1, 2, 3, …) on each hotspot, if hotspot numbers are enabled.
  • A side panel — or overlay, depending on layout — listing every hotspot with its label, price, and SKU.

If the diagram contains many parts, the side panel scrolls independently of the page.

3. Hover / focus

Pointing at a hotspot or its side-panel row:

  • Highlights both — the hotspot pulses or spotlights (depending on the hover effect setting), and the matching side-panel row gets a colored border.
  • Surfaces the part's label as a tooltip on the image.

Keyboard users can Tab through the side-panel rows; the same highlight pairing applies.

4. Click

Clicking a hotspot or its side-panel row opens the product popup:

  • The popup header shows the part's number badge.
  • The popup body shows:
    • Bold title (the hotspot's label, falling back to the product title if no label is set).
    • Thumbnail (clickable — links to the underlying product page).
    • Sale price + regular price struck through, if on sale.
    • SKU (if enabled).
    • Variant picker (if the hotspot is mapped to a product, not a specific variant, and the product has more than the auto-default variant).
    • Quantity stepper.
    • Add to cart button (or Sold out when stock = 0).

Clicking the thumbnail or the bold title navigates to the underlying Shopify product page in a new tab.

5. Add to cart

Clicking Add to cart in the popup:

  • Sends a Shopify cart request via the standard Cart API.
  • Shows a success state on the button.
  • Updates the cart count in the theme's header.
  • Optionally opens the cart drawer or navigates to /cart, depending on the shop setting.

The popup stays open so shoppers can add multiple parts in succession without re-finding them on the diagram.

Edge cases

  • Sold-out variant — quantity stepper and add-to-cart button are disabled; the popup reads Sold out.
  • Product missing — if the hotspot's mapped product was deleted on Shopify after the diagram was edited, the hotspot still renders but the popup shows a "This part is currently unavailable" message. This case is also flagged on the admin dashboard.
  • No JavaScript — the block renders a <noscript> fallback asking the shopper to enable JavaScript. The diagram is JS-driven and cannot fall back to a static list.

For accessibility specifics, see Accessibility.