BannerCarousel

Purpose

The BannerCarousel component renders a responsive banner slider using Swiper.

It supports:

"full width" vs "container" rendering

multiple layout modes via columns

configurable height via bannerHeight

banners with:

background color

background image (desktop + mobile)

background video with fallback image

internal content blocks ("sets") per slide

Inputs (model contract)

Model shape (storefront example)

{
  "name": "BannerCarousel",
  "view": "Default",
  "section": "SectionA",
  "settings": {
    "bannerExtended": true,
    "bannerHeight": "Standard",
    "columns": "One",
    "banners": [
      {
        "backgroundImage": {
          "id": "Image Id",
          "galleryId": "Gallery Id",
          "link": "https://example.com/sample",
          "mediaType": "Image"
        },
        "backgroundImageMobile": {
          "id": "Mobile image Id",
          "galleryId": "Mobile gallery Id",
          "link": "https://example.com/sample",
          "mediaType": "Image"
        },
        "sets": [
          {
            "backgroundColor": true,
            "alignment": "Left",
            "header": "Sample header",
            "text": "<p>Sample text</p>\n",
            "buttonText": "Sample button text",
            "buttonLink": "/sample"
          },
          ...
        ]
      },
      ...
    ],
    "id": "Component Id",
    "section": "SectionA",
    "type": "NoirBannerCarousel",
    "name": "BannerCarousel",
    "configuredInContentApi": true,
    "view": "Default",
    "displayName": "Sample display name",
    "cssClass": "Sample cssClass"
  },
  "translations": {
    "clickToLearnMoreAbout": "Sample translation",
    "bannerLink": "Sample translation",
    "...": "..."
  }
}

Required fields

settings.id
Used to form deterministic ids:

wrapper: comp-{{ id }}

swiper container: banner-carousel-{{ id }}

settings.banners[]
Component renders only when banners exist and banners.length > 0.

Optional fields

settings.cssClass
Appended when non-empty and not (UNDEFINED).

settings.bannerExtended (boolean)
true renders full width; otherwise it uses container.

settings.columns (string)
Controls layout modifiers and Swiper configuration.
Observed values in storefront example: One
Template also supports: Two, Three, Four, TwoThirdOneThird, OneThirdTwoThird.

settings.bannerHeight (string)
Observed value: Standard
Template also supports: Small, FullHeight.

settings.CarouselAutoplay (boolean)
If true, Swiper autoplays through slides automatically.

settings.CarouselAutoplayDelay (number)
Delay in milliseconds between auto-advances. Defaults to 3000.

settings.CarouselPauseOnHover (boolean)
If true (default), autoplay pauses when the user hovers over the carousel.

settings.CarouselNavigation (string enum)
Controls which navigation UI is rendered. Defaults to 'Dots'.
Values: Dots, Arrows, Both.

Template behavior (Liquid + Alpine)

Describe rendering flow, state branches, and key Liquid/Alpine behavior.

JavaScript

Global object

The component exposes a global object:

It is used from Liquid via Alpine:

x-data="bannercarouseldefault.initComponent('{{ id }}', '{{ columns }}', {{ carouselAutoplay }}, {{ carouselAutoplayDelay }}, {{ carouselPauseOnHover }}, '{{ carouselNavigation }}')"

initComponent(...) returns the Alpine component state + methods and then boots Swiper.

initComponent

Factory that returns Alpine state + handlers for banner carousel layout + Swiper init.

It provides:

state: id, columns, navbarHeight, topbarHeight, bannersHeight, isMobile, carouselAutoplay, carouselAutoplayDelay, carouselPauseOnHover, carouselNavigation

lifecycle: init()

helpers: getBannersHeight(), updateNavbarHeight(), updateTopbarHeight(), swiperInit(id, columns)

Notes:

id and columns are passed as strings from Liquid.

init

Runs on Alpine mount.

It initializes banner height (via getBannersHeight()), wires a resize handler (with a small delay), and then initializes Swiper via swiperInit(this.id, this.columns).

getBannersHeight

Computes bannersHeight differently for desktop vs mobile.

On desktop it uses window.innerHeight - topbarHeight - navbarHeight. On mobile it uses "auto".

updateNavbarHeight

Reads .navbar height and stores it in navbarHeight.

Implementation summary:

Queries:

document.querySelector(".navbar")

If found:

this.navbarHeight = navbar.offsetHeight

updateTopbarHeight

Reads .topbar height and stores it in topbarHeight.

Implementation summary:

Queries:

document.querySelector(".topbar")

If found:

this.topbarHeight = topbar.offsetHeight

swiperInit

Initializes a Swiper instance on #banner-carousel-<id> with rules based on columns, a "Small height" mode, and the carousel navigation/autoplay settings.

It computes slides-per-view/spacing based on columns, resolves the carousel DOM (container + pagination), decides whether looping is enabled based on slide count, and creates the Swiper instance.

carouselNavigation controls which UI elements are shown: 'Dots' enables pagination only, 'Arrows' enables prev/next buttons only, 'Both' enables both.

carouselAutoplay enables automatic slide advancement; carouselAutoplayDelay (default 3000 ms) sets the interval; carouselPauseOnHover (default true) pauses autoplay on hover.

Dependencies

Swiper (CSS + JS)

Alpine.js

Notes

If Swiper isn't loaded, the carousel won't behave as a slider (slides may appear stacked).

FullHeight mode depends on .topbar and .navbar being present; if those class names change, height calculation may become inaccurate.

Some banner items may contain empty sets ({}) by design.

BannerCarousel

Purpose#

Inputs (model contract)#

Model shape (storefront example)#

Required fields#

Optional fields#

Template behavior (Liquid + Alpine)#

JavaScript#

Global object#

initComponent#

init#

getBannersHeight#

updateNavbarHeight#

updateTopbarHeight#

swiperInit#

Dependencies#

Notes#