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.

settings.Animation (string enum)
Entrance animation for the visible slides. Defaults to 'None'.
Values: None, SlideFade, RiseSlide, ExpandZoom.

Template behavior (Liquid + Alpine)

Until Swiper has initialised, the slides are shown as skeleton placeholders by the shared .swiper:not(.swiper-initialized) .swiper-slide rule, with or without an animation, so the area is never blank. The skeleton height follows settings.BannerHeight: 220px for Small (and on mobile), 590px for Standard and the full viewport height for FullHeight from the md breakpoint, via the heightSmall / heightStandard / heightFull class on .carousel-wrap. The slides fade in once Swiper initialises. See ThemeClasses.

Until Swiper initialises, only the first slide is displayed, so the layout does not jump.

The first slide's fallback image gets fetchpriority="high"; the others get loading="lazy". Videos use preload="metadata" on the first slide and preload="none" on the rest, with the slide image as poster.

When settings.Animation is not None, the section also gets bannerCarousel--anim plus one of bannerCarousel--anim-slideFade, bannerCarousel--anim-riseSlide or bannerCarousel--anim-expandZoom.

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.

Loading state and entrance animation

Handled inside Swiper's init callback:

On the next animation frame after Swiper initialises, it removes bannerCarousel--loading from the section (present only when an animation is configured).

If the section has bannerCarousel--anim, it then watches the carousel with an IntersectionObserver. When 30% of it (or 30% of the viewport height) is visible, the slides in view get is-animated and is-animating.

On every slide change, the slides are reset and the newly visible ones are animated again, halfway through the transition.

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#

Loading state and entrance animation#

Dependencies#

Notes#