ProductGridItem

Purpose

ProductGridItem renders the grid-view product card used in listing, category, and search result pages.

It coordinates product media, pricing/labels, quick actions, and add-to-cart interactions for card-based layouts.

Where it's rendered

It’s rendered in multiple places:

Components/FilterList/Default.liquid

Components/LastVisitedProducts/Default.liquid

Components/ProductComparison/Default.liquid

Components/ProductsBlock/Default.liquid

`Components/ProductsCarousel/Default.liqu## Services / API calls

This reusable's JS uses servicesreusabledefault for cart/quantity-related operations (see Reusables/ProductGridItem/Default.js).

servicesreusabledefault.hydrateProductPrices(products)

Called on mount (or when the card enters the viewport) to load personalized/ERP prices client-side. The server renders cards from a cached price-free view model; prices are fetched separately.

servicesreusabledefault.hydrateProductConstraints(product)

Called on mount (or on-viewport) to load personalized quantity constraints client-side (non-blocking). Fires as a batched request shared by all cards on the page.

servicesreusabledefault._applyDefaultConstraints(product)

Applied as a fallback when hydrateProductConstraints fails, keeping the card orderable with permissive defaults (min: 1, step: 1, max: 999999).

Components/RelatedProducts/Default.liquid

Components/Wishlist/Default.liquid

From Components/FilterList/Default.liquid:

{% render 'Reusables\\ProductGridItem\\Default',
                                    product: product,
                                    modelId: id,
                                    colorExists: colorExists,
                                    listName: listName,
                                    position: forloop.index0,
                                    description: descriptionField
                                %}

Inputs (Liquid render parameters)

Named parameters:

product

The product object shown in the card.

modelId

Used to build a unique key (modelId-product.id) for DOM scoping.

colorExists

A precomputed boolean used by parent components to indicate whether any product has a color dimension (used for layout decisions in some parents).

listName

Used for GA list tracking (select-item events).

position

Used for GA list tracking (select-item events).

Template behavior (Liquid + Alpine)

High-level rendering:

Builds productImage from product.mediaItems[0] when available.

Renders a wrapper card that:

is keyboard focusable

redirects on click / Enter / Space to /product/{{ product.alias }}

sends GA select-item events

initializes Alpine via:

x-data='productgriditemreusabledefault.initComponent({{ product | serialize | escape }}, "{{ Reusables.ProductGridItem.Translations.AddToCartErrorMessage }}", "{{ Reusables.ProductGridItem.Translations.UpdateProductQuantityErrorMessage }}")'

The reusable also interacts with $store.productModal (for variant selection flows when needed).

Quick actions:

Comparison: Reusables/ProductComparisonButton

Wishlist: Reusables/WishlistButton

Shopping lists: Reusables/ShoppingListsButton

Each is gated by feature flags:

GlobalData.Settings.ShowProductComparison

GlobalData.Settings.EnableWishlist

GlobalData.Settings.EnableShoppingLists

Brand:

If product.brand.* exists, the card renders a brand badge (image when available, otherwise text).

Category + title:

Uses product.categoryName / product.categoryLink (when present).

Uses product.title and links to /product/{{ product.alias }}.

SKU/MPN and variants:

SKU/MPN blocks are shown when product.isMpnVisible and/or product.isSkuVisible.

Variant picker UI appears when product.productVariants.size > 1.

Dimension UI is driven by product.dimension1 / product.dimension2 (and their .type, .items).

Image fallback:

If there is no image link it falls back to GlobalData.Settings.noImage.link or /Assets/images/no-image.svg.

Data contract (JS runtime)

Model shape (storefront example)

Example (from a real product list response) keeping only the relevant fields used by this reusable:

{
  "id": "Product Id",
  "title": "Sample title",
  "alias": "sample",
  "categoryName": "Sample text",
  "categoryLink": "/category/sample",
  "isMpnVisible": true,
  "isSkuVisible": true,
  "mpn": "Sample text",
  "sku": "Sample text",
  "mediaItems": [
    {
      "id": "Media Id",
      "link": "https://example.com/sample",
      "position": 0,
      "alt": "Sample text",
      "mediaType": "Image"
    },
    ...
  ],
  "icoTags": [
    {
      "id": "Tag Id",
      "name": "Sample text",
      "backgroundColor": "Sample text",
      "textColor": "Sample text",
      "icon": { "link": "https://example.com/sample" }
    },
    ...
  ],
  "brand": {
    "name": "Sample text",
    "link": "/brand/sample",
    "image": { "link": "https://example.com/sample", "alt": "Sample text" }
  },
  "dimension1": {
    "type": "Color",
    "name": "Sample text",
    "items": [ { "id": "Dim Item Id", "value": "Sample text", "textColor": "Sample text" }, ... ]
  },
  "dimension2": {
    "type": "Size",
    "name": "Sample text",
    "items": [ { "id": "Dim Item Id", "value": "Sample text" }, ... ]
  },
  "productVariants": [
    {
      "id": "Variant Id",
      "dimension1ItemId": "Dim Item Id",
      "dimension2ItemId": "Dim Item Id",
      "finalPrice": 25,
      "finalPriceText": "25,00 €",
      "originalPrice": 35,
      "originalPriceText": "35,00 €",
      "canOrder": true,
      "sellOutOfStock": false,
      "quantity": 2,
      "minOrderQuantity": 1,
      "orderQuantityStep": 1
    },
    ...
  ],
  "startPrice": 25,
  "startPriceText": "25,00 €",
  "hasPriceRange": false,
  "inWishlist": false
}

Fields consumed directly by Liquid

The Liquid template reads (non-exhaustive, but direct reads visible in Default.liquid):

product.id, product.title, product.alias

product.categoryName, product.categoryLink

product.mediaItems[0].link, product.mediaItems[0].alt

product.icoTags[] (label rendering)

product.brand.name, product.brand.link, product.brand.image.link, product.brand.image.alt

product.isMpnVisible, product.mpn

product.isSkuVisible, product.sku

product.productVariants (size, iteration, JS state)

product.dimension1, product.dimension2 and nested .type, .name, .items[]

JavaScript

Global object

Global object: productgriditemreusabledefault

Liquid wiring:

x-data="productgriditemreusabledefault.initComponent(product, addToCartErrorMessage, updateProductQuantityErrorMessage)"

initSwiper(refs)

What it does

Creates a Swiper instance for dimension pickers (used by the color dimension UI).

When the container has no width yet (e.g. the inline variant picker is hidden at the current breakpoint), construction is deferred via ResizeObserver until it gets a width, so Swiper does not measure zero and leave dead navigation. Returns null in that case.

create

Local factory inside initSwiper that builds the Swiper (slidesPerView: "auto", spaceBetween: 8, prev/next navigation from refs). Called immediately, or by the observer once the container is laid out.

initComponent(product, addToCartErrorMessage, updateProductQuantityErrorMessage, isProductSection = false)

What it does

Initializes local Alpine state for:

selected dimensions and selected variant

responsive behavior

quantity state and debounced update behavior

Sends GA select-item events via sendSelectEvent(...) and sendSelectEventAndRedirect(...).

Key behaviors / edge cases

If there are no dimensions, it selects the first variant.

If a dimension has only one item, it auto-selects it.

This reusable serializes the full product object into the DOM ({{ product | serialize | escape }}). Keep the product payload reasonably sized.

getTitleCatHeight

Measures the title/category block and writes a CSS variable used for consistent layout.

runPriceHydration

Hydrates the personalized price client-side via servicesreusabledefault.hydrateProductPrices(this.product), since the server renders the card from a common/cached price. Clears pricePending in a finally block once the call settles (success or failure), and logs a console error on failure.

schedulePriceHydration

Triggers runPriceHydration() immediately, unless hydrateOnViewport is enabled, in which case it defers the call until the card scrolls into view (elementInView(this.$el, ..., { rootMargin: "200px", threshold: 0, once: true })). No-ops if a price hydration isn't pending. Viewport mode suits unpaginated surfaces (carousels, blocks) where many cards are off-screen.

runConstraintsHydration

Hydrates personalized quantity constraints client-side via servicesreusabledefault.hydrateProductConstraints(this.product), since the server renders the card from a cached, personalization-free view model.

Key behaviors / edge cases

On failure, falls back to servicesreusabledefault._applyDefaultConstraints(this.product) to keep the card orderable with permissive defaults; the server still revalidates on the actual add-to-cart call.

Once hydration settles, clamps the quantity input up to the hydrated minimum (when the current quantity is missing or below it), since init()/updateSelectedVariant() may have already set a fallback of 1 before hydration resolved.

scheduleConstraintsHydration

Triggers runConstraintsHydration() immediately, unless hydrateOnViewport is enabled, in which case it defers the call until the card scrolls into view (same elementInView pattern as schedulePriceHydration).

handleClickEvents

Wires middle-click/Ctrl-click handling so the card can open in a new tab while sending GA tracking.

updateSelectedVariant

Finds and sets the current selected variant based on dimension selections and updates dependent UI state.

selectedVariant

Getter that returns the selected variant (or null when selection is incomplete).

hasMultipleVariants

Getter that returns whether the product has multiple variants.

allDimensionsSelected

Getter that returns whether required dimension selections are completed.

isMultiVariant

Getter that returns whether the product behaves as multi-variant.

isSingleVariant

Getter that returns whether the product behaves as single-variant.

useInlineVariants

Getter that returns true when variants are picked inline on the card: variantDisplay is "Inline", the viewport is at least 1024px wide, the product has multiple variants and no group children.

usePopupVariants

Getter that returns true for multi-variant products without group children that do not use inline variants, so a variant is always reachable through the modal at any viewport.

shouldShowAddToCartButton

Getter that shows the add-to-cart button whenever usePopupVariants is false.

showMobileModalButton

Getter that shows the “choose variant” modal button when usePopupVariants is true.

displayStartPrice

Getter controlling whether the start/range price should be displayed.

displayFinalPrice

Getter controlling whether final price is displayed for the current selection.

displayOriginalPrice

Getter controlling whether original/discounted price UI is displayed.

canAddToCart

Returns whether the current variant selection is orderable and not blocked by quantity constraints.

handleAddToCart

Adds the selected variant to the cart via servicesreusabledefault.addToCart(...) and updates quantity constraints from the response.

updateHeaderHeight

Measures the header height used for sticky positioning in product single sections.

updateStickyElementTop

Computes the sticky element top offset used by scroll behavior.

updateStickyState

Updates whether the card is in sticky mode based on scroll position.

updateActiveButtonOnScroll

Updates which sticky action button is currently active based on scroll.

updateHeaderHeight

Measures header height for sticky calculations.

init() (returned by initComponent)

What it does

Initializes runtime state and event listeners.

Detects which dimension is Color (dimension1 or dimension2) and sets colorDimKey / otherDimKey.

Auto-selects dimension items when a dimension has exactly one option.

If the product has no dimensions, preselects the first variant and calls updateSelectedVariant().

Wires click handling for middle-click / Ctrl-click selection tracking via handleClickEvents().

When isProductSection is true, also initializes sticky/scroll helpers for product single sections.

Key behaviors / edge cases

Relies on window.innerWidth < 1440 to determine mobile behavior.

init

Alpine lifecycle method that initializes dimension selection defaults, registers listeners, and (optionally) enables sticky behavior for product sections.

getTitleCatHeight()

What it does

Measures .product-card__title-cat height and sets the CSS variable --heightTitleCat.

sendSelectEvent(product, listName, position)

What it does

Sends GA selectItem for the clicked product.

sendSelectEventAndRedirect(product, listName, position)

What it does

Sends GA selectItem and then navigates to /product/${product.alias}.

handleClickEvents()

What it does

Adds a mousedown handler to the card.

If the user middle-clicks or Ctrl/Meta-clicks, it:

computes the GA position based on the closest list container ([data-product-list-double] or [data-product-list])

sends GA selectItem

opens the product in a new tab

setSelectedColor(id, label)

What it does

Sets the selected Color dimension ids/labels (selectedDimColor* and the corresponding selectedDim1* / selectedDim2*).

Calls updateSelectedVariant().

setSelectedOther(id, label)

What it does

Sets the selected non-color dimension ids/labels (selectedDimOther* and the corresponding selectedDim1* / selectedDim2*).

Calls updateSelectedVariant().

setDimension(key, id, label)

What it does

Generic setter for selectedDim1* / selectedDim2*.

Calls updateSelectedVariant().

updateSelectedVariant()

What it does

Finds the variant matching the currently selected dimension ids.

Sets selectedVariant and selectedVariantIndex.

Updates quantity state by calling updateQuantity(...).

When there are multiple variants and all required dimension selections are done, it also updates the active image via getActiveImage(...).

Key behaviors / edge cases

Uses quantity constraints (quantityConstraints.additive.minimum) as the default quantity when a variant is selected.

selectedVariant (getter)

What it does

Computes the selected variant from dimension selections.

Returns null when not enough dimensions are selected.

isSingleVariant / isMultiVariant (getters)

What they do

Convenience flags based on product.productVariants.length.

shouldShowAddToCartButton (getter)

What it does

On desktop: always true.

On mobile: shows the add-to-cart button only for single-variant products.

showMobileModalButton (getter)

What it does

On mobile + multi-variant products: shows a modal trigger button.

handleAddToCart()

What it does

Guards against duplicate attempts (isAdding) and checks canAddToCart().

Calls servicesreusabledefault.addToCart(productId, variantId, quantity, finalPrice, originalPrice).

On failure: shows $store.toast with addToCartErrorMessage.

On success:

finds the added cart item in the response

updates variant.quantityConstraints

refreshes quantity by calling updateQuantity(...)

hasMultipleVariants (getter)

What it does

Returns true when (product.productVariants || []).length > 1.

allDimensionsSelected (getter)

What it does

Returns whether the required dimension selections are complete.

isGroupPriceRange (getter)

What it does

Returns true when the product is a group master that spans a price range (product.hasGroupChildren and product.startPriceText are both set).

Key behaviors / edge cases

A group master is not sold itself — the shopper picks one of its children — so its card shows the range the children span even though the master has no variants of its own to choose between.

A group master without startPriceText is not treated as a range; displayFinalPrice returns "" for it.

displayStartPrice / displayEndPrice / displayFinalPrice / displayOriginalPrice (getters)

What they do

displayStartPrice: true when isGroupPriceRange is set, or when the product has multiple variants, dimensions are not fully selected, and product.hasPriceRange is set.

displayEndPrice: returns product.endPriceText when isGroupPriceRange is set, otherwise "". This is the upper bound of the "from X to Y" range shown on group-master cards.

displayFinalPrice: returns the selected variant price text, or a fallback price text.

displayOriginalPrice: returns the selected variant original price text, or a fallback.

isOtherOptionOrderable(otherId)

What it does

For 2-dimension products, checks whether a given "other" dimension value is orderable with the currently selected color.

isSingleOptionOrderable(dimId, isDim1)

What it does

Determines whether a dimension option is orderable by checking whether any matching variant has quantityConstraints.additive.isValid.

canAddToCart()

What it does

With no dimensions: returns true if any variant is orderable.

With dimensions: returns true only when selectedVariant.quantityConstraints.additive.isValid.

variantOrDefault(path, displayNullLine = false)

What it does

Reads a nested value from the selected variant first, then falls back to the product.

Updates customColorActive when stockAvailability.label === 'Custom' and a color exists.

Key behaviors / edge cases

Returns '-' when displayNullLine is true and the value is missing.

getDynamicLabelClass(el)

What it does

Computes a CSS class for availability labels based on variantOrDefault('stockAvailability.label').

Removes an initial Liquid-injected class once if the label changes.

swiperInitSingleProductImages(id, isSwiperInline)

What it does

Initializes Swiper carousels for product single image galleries.

Integrates LightGallery for zoom/fullscreen.

Computes the initial slide based on the variant-linked media item.

getActiveImage(mediaItemId)

What it does

Locates the image matching a media item id and slides the main carousel to it.

updateHeaderHeight() / updateStickyElementTop() / updateStickyState()

What they do

Helpers to keep a product-single sticky element aligned under the header.

Used only when isProductSection === true.

scrollToTop(selector)

What it does

Scrolls smoothly to a section and updates activeButton.

updateActiveButtonOnScroll()

What it does

Tracks which product-single section is currently active and updates activeButton.

increaseQuantity(groupVariant = {}) / decreaseQuantity(groupVariant = {})

What they do

Adjust the internal quantity using quantityConstraints.additive.step and min/max.

debounceUpdateProduct(newQuantity, product, productVariantId, checkQuantity, delay = 800)

What it does

Debounces calls to updateQuantity(...) per product id.

Cancels in-flight quantity-check requests via Axios cancel tokens.

updateQuantity(newQuantity, product, productVariantId, checkQuantity = false, useDebounce = true)

What it does

When checkQuantity is true, calls servicesreusabledefault.updateProductQuantity(...) to validate/normalize quantity server-side.

When checkQuantity is false, it updates this.quantity directly.

Key behaviors / edge cases

Uses $store.toast for error feedback when the API call fails.

Stock loading

Stock is loaded client-side through servicesreusabledefault.hydrateProductStock(product); with hydrateOnViewport it waits until the card is near the viewport (scheduleStockHydration / runStockHydration).

stockPending — true until stock has loaded. The template shows a fixed-height placeholder meanwhile, so the card does not shift.

currentStock() — the selected variant, else the only variant, else the product-level stockAvailability. Grouped parents (hasGroupChildren) never load stock and show nothing.

stockText(availableText, outOfStockText) — Available / OutOfStock use the translations, Varies (multi-variant product, no selection) shows -, other labels show the merchant message. Built on the component-local stockTextFor and formatStockQuantity helpers.

The availability image is rendered outside the colored badge, with a small gap.

stockQuantityText() — the formatted stockQuantity of the selected variant (or the only variant), or "" when no quantity is available.

The availability label and the quantity ({{ model.Translations.StockQuantity }}: …) render only after loading. The server-rendered stock is cleared before the request, so if loading fails neither the availability label nor the quantity is shown.

Global Alpine stores

This reusable uses (indirectly via nested reusables and functions):

$store.toast (used by related actions like add-to-cart errors)

Services / API calls

This reusable’s JS uses servicesreusabledefault for cart/quantity-related operations (see Reusables/ProductGridItem/Default.js).

Dependencies

Liquid: Reusables/ProductGridItem/Default.liquid

JS: Reusables/ProductGridItem/Default.js

Translations: Reusables/ProductGridItem/Default.json

Nested reusables:

Reusables/ProductComparisonButton/Default

Reusables/WishlistButton/Default

Reusables/ShoppingListsButton/Default

Vendor JS: Swiper (dimension carousels)

Notes

The card navigates to /product/{{ product.alias }} on click and on Enter/Space when focused.

The template assumes product.mediaItems[0] is an image; in real data, the first item should be an Image mediaType for best results.

Some product fields are used only by JS (variant selection, cart interaction). Keep Liquid and JS contracts in sync.

ProductGridItem

Purpose#

Where it's rendered#

Inputs (Liquid render parameters)#

Template behavior (Liquid + Alpine)#

Data contract (JS runtime)#

Model shape (storefront example)#

Fields consumed directly by Liquid#

JavaScript#

Global object#

initSwiper(refs)#

create#

initComponent(product, addToCartErrorMessage, updateProductQuantityErrorMessage, isProductSection = false)#

getTitleCatHeight#

runPriceHydration#

schedulePriceHydration#

runConstraintsHydration#

scheduleConstraintsHydration#

handleClickEvents#

updateSelectedVariant#

selectedVariant#

hasMultipleVariants#

allDimensionsSelected#

isMultiVariant#

isSingleVariant#

useInlineVariants#

usePopupVariants#

shouldShowAddToCartButton#

showMobileModalButton#

displayStartPrice#

displayFinalPrice#

displayOriginalPrice#

canAddToCart#

handleAddToCart#

updateHeaderHeight#

updateStickyElementTop#

updateStickyState#

updateActiveButtonOnScroll#

updateHeaderHeight#

init() (returned by initComponent)#

init#

getTitleCatHeight()#

sendSelectEvent(product, listName, position)#

sendSelectEventAndRedirect(product, listName, position)#

handleClickEvents()#

setSelectedColor(id, label)#

setSelectedOther(id, label)#

setDimension(key, id, label)#

updateSelectedVariant()#

selectedVariant (getter)#

isSingleVariant / isMultiVariant (getters)#

shouldShowAddToCartButton (getter)#

showMobileModalButton (getter)#

handleAddToCart()#

hasMultipleVariants (getter)#

allDimensionsSelected (getter)#

isGroupPriceRange (getter)#

displayStartPrice / displayEndPrice / displayFinalPrice / displayOriginalPrice (getters)#

isOtherOptionOrderable(otherId)#

isSingleOptionOrderable(dimId, isDim1)#

canAddToCart()#

variantOrDefault(path, displayNullLine = false)#

getDynamicLabelClass(el)#

swiperInitSingleProductImages(id, isSwiperInline)#

getActiveImage(mediaItemId)#

updateHeaderHeight() / updateStickyElementTop() / updateStickyState()#

scrollToTop(selector)#

updateActiveButtonOnScroll()#

increaseQuantity(groupVariant = {}) / decreaseQuantity(groupVariant = {})#

debounceUpdateProduct(newQuantity, product, productVariantId, checkQuantity, delay = 800)#

updateQuantity(newQuantity, product, productVariantId, checkQuantity = false, useDebounce = true)#

Stock loading#

Global Alpine stores#

Services / API calls#

Dependencies#

Notes#

Purpose

Where it's rendered

Inputs (Liquid render parameters)

Template behavior (Liquid + Alpine)

Data contract (JS runtime)

Model shape (storefront example)

Fields consumed directly by Liquid

JavaScript

Global object

initSwiper(refs)

create

initComponent(product, addToCartErrorMessage, updateProductQuantityErrorMessage, isProductSection = false)

getTitleCatHeight

runPriceHydration

schedulePriceHydration

runConstraintsHydration

scheduleConstraintsHydration

handleClickEvents

updateSelectedVariant

selectedVariant

hasMultipleVariants

allDimensionsSelected

isMultiVariant

isSingleVariant

useInlineVariants

usePopupVariants

shouldShowAddToCartButton

showMobileModalButton

displayStartPrice

displayFinalPrice

displayOriginalPrice

canAddToCart

handleAddToCart

updateHeaderHeight

updateStickyElementTop

updateStickyState

updateActiveButtonOnScroll

updateHeaderHeight

init() (returned by initComponent)

init

getTitleCatHeight()

sendSelectEvent(product, listName, position)

sendSelectEventAndRedirect(product, listName, position)

handleClickEvents()

setSelectedColor(id, label)

setSelectedOther(id, label)

setDimension(key, id, label)

updateSelectedVariant()

selectedVariant (getter)

isSingleVariant / isMultiVariant (getters)

shouldShowAddToCartButton (getter)

showMobileModalButton (getter)

handleAddToCart()

hasMultipleVariants (getter)

allDimensionsSelected (getter)

isGroupPriceRange (getter)

displayStartPrice / displayEndPrice / displayFinalPrice / displayOriginalPrice (getters)

isOtherOptionOrderable(otherId)

isSingleOptionOrderable(dimId, isDim1)

canAddToCart()

variantOrDefault(path, displayNullLine = false)

getDynamicLabelClass(el)

swiperInitSingleProductImages(id, isSwiperInline)

getActiveImage(mediaItemId)

updateHeaderHeight() / updateStickyElementTop() / updateStickyState()

scrollToTop(selector)

updateActiveButtonOnScroll()

increaseQuantity(groupVariant = {}) / decreaseQuantity(groupVariant = {})

debounceUpdateProduct(newQuantity, product, productVariantId, checkQuantity, delay = 800)

updateQuantity(newQuantity, product, productVariantId, checkQuantity = false, useDebounce = true)

Stock loading

Global Alpine stores

Services / API calls

Dependencies

Notes