Home
Wiki
Home
Wiki
  1. 2. Components
  • Back to home
  • 1. Themes
  • Vs Code
    • Getting Started
  • Kitchenware
    • Layout
      • New Layout
      • Legacy Layout
    • Components
      • Announcement
      • Banner Carousel
      • Banner With Products Carousel
      • Blog Category List
      • Blog List
      • Brand List
      • Brands Carousel
      • Breadcrumb
      • Call To Action
      • Cart
      • Categories List
      • Change Password
      • Checkout
      • Cookie Manager
      • Filter list
      • Footer
      • Forgot Password
      • Form
      • Hero Carousel
      • Icon Block
      • Invitation
      • Last Visited Products
      • Layout
      • Login
      • Map
      • Nav Bar
      • Offer
      • Product Attachments
      • Product Attributes
      • Product Documentation
      • Product Expected
      • Product Modal
      • Products Block
      • Products Carousel
      • Product Single
      • Profile
      • Quote
      • Register
      • Related Products
      • Search
      • Stores
      • Subscribe Newsletter
      • Text with Image
      • Top Bar
      • Video
    • Reusables
      • Getting Started
    • Assets
      • Getting Started
    • SDK
      • Products
        • _findProductsByCategory
        • _findProductsByIds
        • _findProductsByTitle
        • _findProductsByFilter
        • _findProductsByCriteria
        • _findProductsAndCalculate
        • _findProductsThenCalculate
        • _getProductAttributeSet
        • _setLastVisited
      • Categories
        • _findCategoryTreeById
        • _findCategoriesByIds
        • _findCategoryByAlias
        • _findCategoryTreeByAlias
        • _getCategoryContent
      • Collections
        • _getCollectionContent
        • _findCollectionsByIds
        • _findCollectionsByIdsThenCalculate
      • Brands
        • _getBrandContent
        • _findBrandsByIds
      • Cart
        • _addToCartMulti
        • _addToCart
        • _setCart
        • _clearCart
        • _setCartListener
        • _removeFromCart
        • _calculateCart
      • Checkout
        • _startCheckout
        • _updateCheckout
        • _completeCheckout
      • Shopping Lists
        • _getShoppingLists
        • _updateShoppingList
        • _createShoppingList
        • _deleteShoppingList
        • _getShoppingListByAlias
      • Navigation
        • _getFooterMenu
        • _getHeaderMenu
      • Users
        • _getUserById
      • Utils
        • _calculateCurrency
        • _getCurrencySymbol
        • _getCulture
        • _subscribeToNewsletter
        • _findUnitsByIds
  • Noir
    • 0. Introduction
    • 1. Structure
      • Overview
      • LayoutA.liquid
      • ComponentsList.liquid
      • Metas.liquid
      • CssVariables.liquid
      • Json.liquid
      • GoogleTagManager.liquid
      • StagingButton.liquid
    • 2. Components
      • Overview
      • Announcement
      • BannerCarousel
      • BlogCategoryList
      • BlogList
      • BrandList
      • Breadcrumb
      • Cart
      • CategoriesList
      • ChangePassword
      • Checkout
      • CookieManager
      • FilterList
      • Footer
      • ForgotPassword
      • Form
      • IconBlock
      • Invitation
      • LastVisitedProducts
      • Login
      • Map
      • NavBar
      • ProductAttachments
      • ProductAttributes
      • ProductComparison
      • ProductDocumentation
      • ProductMixList
      • ProductsBlock
      • ProductsCarousel
      • ProductSingle
      • Profile
      • Register
      • RelatedProducts
      • SingleBlog
      • Stores
      • TextWithImage
      • ThankYouPage
      • TopBar
      • Wishlist
    • 3. Reusables
      • Overview
      • Addresses
      • BillingRetail
      • AddressForm
      • AnnouncementModal
      • BackToTop
      • Company
      • General
      • Login
      • LoginModal
      • Orders
      • Payment
      • ProductAttachments
      • ProductAttributes
      • ProductComparisonButton
      • ProductComparisonFloatingButton
      • ProductGridItem
      • ProductListItem
      • ShoppingListsButton
      • ProductModal
      • ProfileInfo
      • PromptModal
      • Register
      • Shipping
      • ShoppingLists
      • ShoppingListsNavbar
      • Toast
      • Users
      • VariantContent
      • WishlistButton
      • Services
    • 4. Assets
      • Fonts
      • Images
      • Templates
      • Javascript
        • Overview
        • theme.js
      • Css / Scss
        • Overview
        • ThemeClasses
    • 5. SDK
      • Overview
      • LiquidGlobals
      • ServicesSDK
  1. 2. Components

ProductsCarousel

Purpose#

The ProductsCarousel component renders a Swiper carousel of products.
It:
renders a header/description area (from settings.header + settings.description)
renders one product per slide using Reusables\\ProductGridItem\\Default
optionally renders a “learn more” button that links to collectionUrl
sends a GA4 viewItemList event when the carousel enters the viewport

Inputs (model contract)#

Model shape (storefront example)#

{
  "products": [
    {
      "vatIncluded": true,
      "vatRate": 25,
      "reducedVatRate": 5,
      "unitText": "Sample text",
      "isMpnVisible": true,
      "isSkuVisible": true,
      "title": "Sample product title",
      "description": "<p>Sample description</p>",
      "alias": "sample-product-alias",
      "status": "Active",
      "brandId": "Brand Id",
      "categoryId": "Category Id",
      "categoryName": "Sample category name",
      "categoryLink": "/category/sample",
      "tags": [
        "sample-tag",
        "..."
      ],
      "pathCategories": [
        "Path Category Id",
        "..."
      ],
      "availability": "Available",
      "stockAvailabilityModelId": "Stock Availability Model Id",
      "isBundle": false,
      "id": "Product Id",
      "companyId": "Company Id",
      "link": "product/sample-product",
      "mediaItems": [
        {
          "id": "Media Item Id",
          "link": "https://example.com/media/sample.jpg",
          "position": 0,
          "alt": "sample.jpg",
          "mediaType": "Image"
        },
        "..."
      ],
      "maxPrice": 155,
      "minPrice": 120,
      "maxRetailPrice": 30,
      "minRetailPrice": 10,
      "updateDate": "2026-01-01T00:00:00.0000000+00:00",
      "insertDate": "2026-01-01T00:00:00.0000000+00:00",
      "variantCount": 3,
      "additionalFeatures": {
        "icoTags": [
          {
            "id": "IcoTag Id",
            "name": "Sample text"
          },
          "..."
        ]
      },
      "searchAttributes": [
        "Sample text",
        "..."
      ],
      "productVariants": [
        {
          "quantityConstraints": {
            "additive": {
              "minimum": 1,
              "maximum": 999999,
              "step": 1,
              "isValid": true
            },
            "absolute": {
              "minimum": 1,
              "maximum": 999999,
              "step": 1,
              "isValid": true
            }
          },
          "id": "Variant Id",
          "mediaItem": {
            "id": "Media Item Id"
          },
          "title": "Sample text",
          "mpn": "Sample text",
          "sku": "Sample text",
          "initialPrice": 33,
          "unitPrice": 30,
          "price": 30,
          "quantity": 0,
          "retail": {
            "initialPrice": 33,
            "price": 30,
            "unitId": "(UNDEFINED)",
            "salesUnitId": "Sales Unit Id",
            "unitPrice": 30
          },
          "dimension1ItemId": "Attribute Item Id",
          "dimension2ItemId": "Attribute Item Id",
          "sellOutOfStock": true,
          "requiresShipping": false,
          "translation": {},
          "canOrder": true,
          "additionalFeatures": {},
          "bundleItems": [],
          "shoppingLists": [],
          "startQuantity": 1,
          "finalPriceText": "Sample price text",
          "finalPrice": 30,
          "originalPriceText": "Sample price text",
          "originalPrice": 33
        },
        "..."
      ],
      "attributes": [
        {
          "attributeId": "Attribute Id",
          "attributeItemId": "Attribute Item Id",
          "attributeItemValue": "Sample text",
          "name": "Sample text",
          "slug": "sample-slug",
          "usedAsFilter": false,
          "displayOnProduct": true,
          "displayOnList": true,
          "displayOnCompare": true
        },
        "..."
      ],
      "brand": {
        "name": "Sample text",
        "link": "/brand/sample",
        "image": {
          "link": "https://example.com/media/sample.jpg"
        }
      },
      "icoTags": [
        {
          "id": "IcoTag Id",
          "name": "Sample text",
          "icon": {
            "alt": "Sample text"
          }
        },
        "..."
      ],
      "labels": [
        {
          "id": "Label Id",
          "name": "Sample text",
          "icon": {
            "alt": "Sample text"
          }
        },
        "..."
      ],
      "dimension1": {
        "id": "Dimension Id",
        "attributeId": "Attribute Id",
        "name": "Sample text",
        "translation": {},
        "type": "Color",
        "usedAsFilter": true,
        "displayOnProduct": true,
        "displayOnList": true,
        "displayOnCompare": true,
        "items": [
          {
            "textColor": "#000000",
            "id": "Attribute Item Id",
            "value": "Sample text"
          },
          "..."
        ]
      },
      "dimension2": {
        "id": "Dimension Id",
        "attributeId": "Attribute Id",
        "name": "Sample text",
        "translation": {},
        "type": "Items",
        "usedAsFilter": false,
        "displayOnProduct": true,
        "displayOnList": true,
        "displayOnCompare": true,
        "items": [
          {
            "id": "Attribute Item Id",
            "value": "Sample text"
          },
          "..."
        ]
      },
      "startPriceText": "Sample price text",
      "startPrice": 10,
      "hasPriceRange": true,
      "inWishlist": false
    },
    "..."
  ],
  "collectionUrl": "/collection/sample",
  "name": "ProductsCarousel",
  "view": "Default",
  "section": "SectionA",
  "settings": {
    "collectionIds": [
      "Collection Id",
      "..."
    ],
    "buttonText": "Sample button text",
    "description": "<p>Sample description</p>",
    "displayLinkToCollection": true,
    "backgroundColor": false,
    "layoutMode": "Inline",
    "inlineContentAlignment": "Left",
    "id": "Component Id",
    "section": "SectionA",
    "type": "NoirProductsCarousel",
    "name": "ProductsCarousel",
    "configuredInContentApi": true,
    "view": "Default",
    "displayName": "Sample text",
    "cssClass": "",
    "header": "Sample text",
    "alignment": "Left"
  },
  "translations": {
    "clickToLearnMoreAbout": "Sample text",
    "productsCarousel": "Sample text"
  }
}

Required fields#

settings.id
products[]
If missing/empty, the component renders nothing.

Optional fields#

settings.cssClass
settings.header (if empty, the title is omitted; translations.productsCarousel becomes the list name for GA)
settings.description
settings.displayLinkToCollection
settings.buttonText
collectionUrl
Carousel config:
settings.layoutMode (Inline or FullWidth)
settings.inlineContentAlignment (used only when layoutMode == "Inline")
settings.backgroundColor
settings.alignment (Left, Center, Right)
translations.*
Used for GA button aria label and header fallback.

JavaScript#

Global object#

Components/ProductsCarousel/Default.js exposes a global object:
Liquid binds it via Alpine:
<section
  x-data='productscarouseldefault.initComponent("{{ id }}", "{{ layoutMode }}", {{ products | serialize | escape }}, "{{ header | default: model.Translations.ProductsCarousel }}")'
>

initComponent(id, layoutMode, products, headerTitle)#

What it does
Creates and returns the Alpine state object used by the carousel.
Key behaviors / edge cases
Always calls swiperInit(...) even if there’s only one product; the template itself prevents rendering when empty.
Advice
Keep headerTitle consistent with the visible header, because it’s used as the GA4 list name.

init()#

What it does
1.
Initializes the Swiper instance.
2.
Registers an “in view” hook that sends GA4 viewItemList when 25% of the carousel is visible.
Key behaviors / edge cases
Uses elementInView("#products-carousel-" + id, ...) which expects the DOM id to match the Liquid template.
GA items are built via prepareListProducts(products).
Advice
If you change the DOM structure/ids in Liquid, update the selector in JS.

swiperInit(id, layoutMode)#

What it does
Creates a Swiper on #products-carousel-<id>.
Enables pagination in .swiper-pagination-<id>.
Chooses desktop slides-per-view based on layoutMode:
FullWidth → 4
otherwise → 3
Key behaviors / edge cases
Enables looping only when there are more slides than slidesPerView.
Breakpoints:
< 1024: 1 per view
>= 1024: 2 per view
>= 1440: slidesPerView (3 or 4)
Advice
Avoid changing the pagination classname pattern (swiper-pagination-{{ id }}), it’s used as a selector.

Dependencies#

Alpine.js
Swiper
Reusables\\ProductGridItem\\Default
Theme utilities:
elementInView(...)
prepareListProducts(...)
sendGAEvent(...)

Notes#

The component renders nothing when products is missing/empty.
The component searches for color dimensions across products to set colorExists for ProductGridItem.
The GA4 listName is settings.header when present, else translations.productsCarousel.

Extras#

Template behavior (Liquid + Alpine)#

Computes alignmentClass from settings.alignment.
Computes sectionClasses from:
layout (layoutMode, inlineContentAlignment)
optional settings.cssClass
settings.backgroundColor
Decides whether product color exists by checking product.dimension1.type == "Color" or product.dimension2.type == "Color".
Renders an optional collection button twice:
desktop-only button inside the header area (Inline only)
bottom button for all layouts (mobile-only for Inline)
Modified at 2026-04-14 13:18:56
Previous
ProductsBlock
Next
ProductSingle
Built with