CategoriesList

Purpose

The CategoriesList component renders a visual list of categories (category cards), optionally as a Swiper slider.

It supports:

Optional header/description area

Optional “Show all categories” button linking to /categories

Category cards linking to /<path>/<alias>

Optional slider mode with pagination dots

Inputs (model contract)

Model shape (storefront example)

{
  "description": null,
  "showAllCategoriesButton": null,
  "enableSlider": null,
  "categories": [
    {
      "title": "Sample category title",
      "alias": "sample-category-alias",
      "path": "category",
      "mediaItem": {
        "id": "Image Id",
        "link": "https://example.com/sample",
        "mediaType": "Image"
      }
    },
    ...
  ],
  "name": "CategoriesList",
  "view": "Default",
  "section": "SectionA",
  "settings": {
    "categoryIds": [],
    "id": "Component Id",
    "section": "SectionA",
    "type": "NoirCategoriesList",
    "name": "CategoriesList",
    "configuredInContentApi": true,
    "view": "Default",
    "displayName": "Sample display name",
    "cssClass": "(UNDEFINED)",
    "header": "Sample header",
    "alignment": "Left"
  },
  "translations": {
    "showAllCategories": "Sample translation",
    "clickToLearnMoreAbout": "Sample translation"
  }
}

Required fields

settings.id
Used for:

wrapper id: comp-{{ id }}

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

pagination class suffix: swiper-pagination-{{ id }} (when slider is enabled)

categories[]
Component renders only when categories exists and categories.length > 0.

Optional fields

settings.cssClass
Applied to wrapper only when non-empty and not (UNDEFINED).

settings.header (string)
Used as the title, unless a breadcrumb label overrides it (see “Template behavior”).

settings.description (string)
Optional description shown under the header.

settings.alignment (string enum)
Controls header alignment classes:

Left (default)

Center

Right

settings.enableSlider (boolean)
If true:

Swiper is initialized

pagination dots are rendered

settings.showAllCategoriesButton (boolean)
If true, renders a CTA button linking to /categories.

settings.categoryIds (array)
Present in the model; the template doesn’t use it directly (it can be part of server-side selection/filtering).

JavaScript

Global object

The component exposes a global object:

It’s triggered from the template via Alpine x-init:

x-init="categorieslistdefault.swiperInit('{{ id }}', {{ enableSlider }})"

This component doesn’t return Alpine reactive state; Alpine is used only to run initialization on mount.

`swiperInit(id, enableSlider)`

What it does
Initializes a Swiper instance for the CategoriesList carousel when slider mode is enabled.

1) Guard clauses (early exits)

If enableSlider is falsy:

returns immediately (no Swiper).

Finds the carousel element:

#categories-carousel-<id>

If not found: returns.

Advice

This is the correct “fail-safe” pattern: if the markup isn’t present, nothing breaks.

Keep enableSlider as a boolean. If it ever becomes a string (e.g. "false"), it will be truthy—so if you suspect data-type issues, normalize it before using it.

2) Resolve pagination element

Finds pagination container:

.swiper-pagination-<id>

Then passes it to Swiper’s pagination.el.

Advice

If pagination markup is not rendered when slider is enabled, paginationEl will be null and Swiper pagination can break or behave unexpectedly.
If you want extra resilience, add:

pagination: paginationEl ? { el: paginationEl, clickable: true } : false

3) Swiper configuration (base + breakpoints)
Base config (mobile-first):

loop: false

slidesPerView: 1

spaceBetween: 24

slidesPerGroup: 1

grid: { rows: 1, fill: "row" }

pagination: { el: paginationEl, clickable: true }

Breakpoints:

≥ 1024

slidesPerView: 2

slidesPerGroup: 2

spaceBetween: 0

grid: { rows: 2 }

≥ 1440

slidesPerView: 4

slidesPerGroup: 4

spaceBetween: 24

grid: { rows: 2 }

Finally:

new Swiper(carousel, swiperConfig);

Advice

This uses Swiper “grid” mode (rows) on tablet/desktop. That’s great for showing many categories in a compact space, but:

make sure the slide markup is compatible with grid (each .swiper-slide is treated as one grid cell).

loop is intentionally disabled. Loop + grid typically creates confusing UX and can be buggy unless heavily tuned.

If you change the styling so that spacing is handled via CSS gap instead, keep spaceBetween consistent or set it to 0 to avoid double spacing.

Swiper must be loaded globally before this runs; otherwise new Swiper(...) will throw.

Dependencies

Swiper (CSS + JS) when slider is enabled

Alpine.js (only for x-init, not for reactive state)

Notes

If enableSlider = false, the list is rendered without Swiper behavior.

If Swiper isn’t loaded and enableSlider = true, the carousel won’t behave as intended.

Title may be overridden by Root.Page.Breadcrumbs[2].label when present; this is useful for category pages but can surprise you if breadcrumb structure changes.

Category links depend on path being correct (category vs categories), since the template builds URLs directly from it.

Extras

Template behavior (Liquid + Alpine)

If available, the component can use a breadcrumb label as the title:

Root.Page.Breadcrumbs[2].label

Priority order:

Root.Page.Breadcrumbs[2].label (if present)

settings.header (if present)

Slider initialization

If enableSlider is true, Swiper is initialized via:

x-init="categorieslistdefault.swiperInit('{{ id }}', {{ enableSlider }})"

If enableSlider is false, no Swiper is created.

Category cards

Each category card:

renders an image background (or fallback)

shows the category title in an overlay

links to /<path>/<alias>

includes an accessibility aria-label based on translations + title

“Show all categories” button

If showAllCategoriesButton is true:

renders a CTA linking to /categories

label comes from translations.showAllCategories

CategoriesList

Purpose#

Inputs (model contract)#

Model shape (storefront example)#

Required fields#

Optional fields#

JavaScript#

Global object#

swiperInit(id, enableSlider)#

Dependencies#

Notes#

Extras#

Template behavior (Liquid + Alpine)#

Header title source (Breadcrumb override)#

Slider initialization#

Category cards#

“Show all categories” button#

Purpose

Inputs (model contract)

Model shape (storefront example)

Required fields

Optional fields

JavaScript

Global object

`swiperInit(id, enableSlider)`

Dependencies

Notes

Extras

Template behavior (Liquid + Alpine)

Header title source (Breadcrumb override)

Slider initialization

Category cards

“Show all categories” button