Skip to main content

​
Overview

Product detail pages in Site Store Pro are powered by Alpine.js and deliver a fully interactive shopping experience — including hover zoom, a lightbox gallery, dynamic variant selectors, live price updates, and configurable product customization forms — all without a full page reload. Route: GET /items/{seo_slug}
Every product page displays a full recursive ancestor breadcrumb trail built from the category hierarchy. The trail always begins with “Shop” and drills down through every parent category to the product name:
Breadcrumbs are generated dynamically from the category tree. If you restructure your category hierarchy, breadcrumbs update automatically on next page load — no manual changes needed.

​
Quick Admin Edit Shortcut

Users with the Admin role see an “Edit Product (Admin)” button displayed next to the breadcrumbs. Clicking it navigates directly to the product’s edit page in the Admin panel, enabling fast corrections without leaving the storefront.
The product gallery is built with Alpine.js and supports hover zoom, lightbox, and seamless variant image syncing.

​
Hover Zoom (Lens Magnifier)

When a customer hovers over the main product image, a 200% resolution zoomed lens follows the cursor. The magnified region is rendered at double the display resolution for sharp detail on high-DPI screens.

​
Click-to-Open Lightbox Modal

Clicking the main image opens a full-screen frosted-glass lightbox modal with:
  • Previous / Next navigation arrows
  • Custom image_alt tag displayed as accessible alt text
  • Custom zoom_label caption displayed below the image in the lightbox
  • Keyboard navigation support (← → arrow keys, Esc to close)

​
Thumbnail Strip

A row of thumbnails is displayed below the primary image. Clicking a thumbnail:
  1. Swaps the main image to the selected thumbnail
  2. Updates the active variant to match
  3. Refreshes the displayed price and available options
The thumbnail strip is automatically hidden when a product has only one image total — keeping the layout clean for single-image products.
Thumbnails are center-aligned below the primary image.

​
Variant Color Deduplication

The thumbnail strip enforces one unique image per color/shade/tint. If a product has a “Midnight Black” color in sizes S, M, and L — all sharing the same photo — only one thumbnail appears for that color. Switching between sizes of the same color does not reset or re-render the gallery.

​
Variant–Gallery Sync

Selecting any variant option (color swatch, size button, etc.) automatically:
  • Swaps the main image to the first image for that variant
  • Updates the active thumbnail highlight
  • Refreshes the price display, including any variant_fee surcharge

​
Product Page Layouts

Admins can choose one of 5 layout options per product, set under: Admin → Products → Edit → Advanced Settings → Product Page Layout Option
The standard two-column layout.
Mirrors the default — gallery moves to the left column and the buy box shifts right. Useful for products where imagery should lead the browsing experience.
Same two-column layout as the default for the upper section. The product video is pulled out of the columns and rendered full-width below both, giving video content maximum visual impact.
A single-column centered layout ideal for editorial-style product pages.
Video is the hero element. Ideal for product launches or demonstration-heavy items.

​
Variant Selectors

​
Dynamic Drill-Down Selectors

When Use Dependent Selectors (dependent_variants) is enabled for a product, variant selection becomes a guided, progressive flow:
  1. Color is selected first — all available colors are shown
  2. Size options are then filtered to only combinations that are actually in stock for the chosen color
This eliminates “add to cart → out of stock” frustration by only presenting valid combinations.

​
Reactive Price & Fee Updates

Every variant can carry a variant_fee — an additional charge on top of the base product price (e.g., for a premium finish, a larger size, or an engraved option). The displayed price updates instantly when a variant is selected, showing:
  • Base price
  • variant_fee (if any)
  • Combined total price
  • Strikethrough original price (if a discount is active)

​
Quantity & Server-Side Validation

The quantity input accepts integers between 1 and 10,000. Non-numeric values and out-of-range inputs are sanitized server-side before the add-to-cart action is processed.

​
Product Customization Forms (Product Builder)

Admins can attach a fully custom form to any product, enabling shoppers to specify personalizations before adding to cart. Field types available: Pricing rules for customization forms can be set independently for retail and wholesale customers.

​
Discounts & Pricing Display

When a product or variant has an active discount, the product page displays:
  • The regular (original) price with a strikethrough
  • The sale price prominently alongside
This strikethrough display is driven entirely by the active discount record — no manual price overrides needed.

​
Gift Wrapping & Personalization

If gift wrapping is enabled for a product, a checkbox appears in the buy box. Checking it reveals a text area where the customer can enter a gift message or engraving text.
The gift wrap fee is added as a separate line item on the cart, keeping the product price and the wrapping charge clearly itemized in the order summary.
Below the product description, Site Store Pro displays a horizontally scrollable carousel of related products. Related products are drawn from the same category and/or brand as the current product.

​
Cross-Selling

Admins can attach cross-sell items to any product. Cross-sells have two display modes, controlled per cross-sell record: The post-cart cross-sell page presents the recommended items before the customer proceeds to checkout, maximizing upsell opportunity at the peak moment of purchase intent.

​
Advanced Per-Product Settings

These options are found under Admin → Products → Edit → Advanced Settings:
When enabled, the quantity selector is disabled and the quantity is locked at 1. Use this for limited-edition items, event tickets, or one-per-customer offers.
Bypasses the cart entirely. After clicking “Add to Cart”, the customer is sent directly to checkout. Useful for fast-purchase single items.
Implies checkout_redirect. Additionally blocks mixing this product with other items in the same cart session. Ideal for subscriptions or special order items that require isolated fulfillment.
Enables the progressive drill-down variant flow — Color first, then Size filtered to valid combinations for that color.
Suppresses the “X in stock” indicator on the product page. The item remains purchasable; customers simply don’t see the inventory count.

​
Quick Reference

Product Detail Route

GET /items/{seo_slug}

Post-Cart Cross-Sells

GET /cart/recommendations/{productId}

Admin Edit Shortcut

Visible to Admin role only — button next to breadcrumbs

Dependent Variants

Enable per-product via dependent_variants in Advanced Settings