SwCarousel

SwCarousel is an auto-rotating carousel built on transform: translateX, for banners / hero images. It clones the first and last slides for a seamless loop (when reaching a clone frame it jumps back to the real frame without animation — no visible flicker), with built-in autoplay, touch threshold paging, and dots / thumbnail indicators.

items-based: pass :items data + a #default="{ item, index }" scoped slot to render each slide (the component clones based on items; index is the real logical index).

The #default slot is required: the component doesn't know how to render your item. Passing :items without a #default slot renders blank frames (dev console warns).

Use SwRail for free horizontal scrolling: SwCarousel is "one screen at a time + autoplay"; for "a row of N items that scrolls" use SwRail.

Basic usage

<SwCarousel :items="banners" aria-label="Homepage banner">
  <template #default="{ item }">
    <SwLink :to="item.link"><SwImage :src="item.img" ratio="16/9" /></SwLink>
  </template>
</SwCarousel>

Banner links (SwCarousel has no built-in link)

SwCarousel provides no link / text / button of its own — each banner's content (image / title / button / target URL) comes entirely from item data, rendered via the #default="{ item, index }" scoped slot. For clickable banners, pick one of the two shapes below:

• Image-only banner (whole slide clickable): wrap the whole slide in SwLink (see Basic usage above).
• Banner with text + button: put the SwLink / SwButton CTA inside the slide, and don't wrap the whole thing in <a> (nesting interactive elements inside a link is invalid HTML).

<!-- Real banner: image + title + CTA button, link from item.link -->
<SwCarousel :items="banners" aria-label="Homepage banner">
  <template #default="{ item }">
    <div class="banner">
      <SwImage :src="item.img" ratio="12/5" />
      <h3 class="title">{{ item.title }}</h3>
      <SwLink :to="item.link" class="cta">{{ item.cta }}</SwLink>
    </div>
  </template>
</SwCarousel>

Autoplay & pausing

Autoplay is on by default (autoplayDelay controls dwell time per slide in ms, default 4000 — enough time to read banners with text; pass 3000 for image-only). It auto-pauses on desktop hover, keyboard focus, pointer drag, and when the page goes to the background (visibilitychange), resuming on leave / return; it does not autoplay when the system "reduce motion" preference is active. A single slide or :autoplay="false" disables it. Manual navigation (indicators / thumbnails / keyboard / ref methods) resets the autoplay timer — the slide you just picked gets the full autoplayDelay, instead of being swapped away by an imminent tick.

<SwCarousel :items="banners" :autoplay-delay="5000" :pause-on-hover="true" />
<SwCarousel :items="banners" :autoplay="false" />  <!-- autoplay off -->

Loop & single-slide degradation

• loop (default true): seamless loop. With :loop="false" it stops at the first / last slide without wrapping.
• Single-slide auto-degradation: when items.length <= 1, no clones, no autoplay, no indicator.

Touch paging

On mobile, a finger swipe beyond dragThreshold (fraction of container width, default 0.15) pages; otherwise it springs back.

Indicators (dots / thumbnails / custom)

indicator is 'dots' (default) / 'thumbnails' / 'none'; position is controlled by the unified indicatorPlacement (shared by dots and thumbnails):

Dot styling

By default dots are white with a shadow (visible on any background, not tied to the brand color); the active dot becomes an elongated bar with animation (longer when horizontal / taller when vertical). Dots also have an enlarged click hit-area (transparent, doesn't change the visuals) for easier tapping. All styling is customizable via CSS variables:

<SwCarousel
  :items="banners"
  style="--sw-carousel-dot-active-color: var(--primary); --sw-carousel-dot-size: 0.625rem"
>
  <template #default="{ item }"><SwImage :src="item.img" ratio="16/9" /></template>
</SwCarousel>

Thumbnail navigation

indicator="thumbnails" + :thumbnails (an image array, length must match items) renders a thumbnail strip. The active thumbnail uses a white box-shadow outline (not a hard border, reflow-safe); inactive ones are dimmed via brightness and brighten on hover. With many thumbnails the strip becomes a horizontal-scroll filmstrip that auto-scrolls the active one into view on change (the mouse wheel also scrolls it).

thumbnailTrigger controls how thumbnails switch slides: 'click' (default, click to switch) / 'hover' (hover switches immediately).

thumbnailLabels supplies each outer thumbnail button with its complete accessible name, for example :thumbnail-labels="movies.map(m => m.title)". The full label remains available when visual titles are truncated or #thumbnail renders custom content. Leading/trailing whitespace is trimmed; omitted, blank or missing entries retain localized ordinal names. Keep labels and thumbnails equal in length and order. A length mismatch warns in development: supplied labels remain usable and missing entries fall back per index. aria-current, keyboard and touch behavior remain unchanged.

Thumbnails render as bare <img> by default (no SwImage, no decryption). To customize how each thumbnail renders — most typically for .bnc encrypted images (broken with a bare img) — use the #thumbnail scoped slot ({ thumb, index, active }) with SwImage; without the slot the behavior is exactly as before:

<SwCarousel :items="movies" indicator="thumbnails" :thumbnails="movies.map((m) => m.cover)">
  <template #default="{ item }"><SwImage :src="item.cover" alt="" fill /></template>
  <!-- the bare-img fallback cannot decrypt; SwImage fill fills the thumb button and decrypts .bnc -->
  <template #thumbnail="{ thumb }"><SwImage :src="thumb" alt="" fill /></template>
</SwCarousel>

<!-- Thumbnail nav (vertical, right, hover to switch) -->
<SwCarousel
  :items="list"
  indicator="thumbnails"
  :thumbnails="list.map(x => x.thumb)"
  indicator-placement="right"
  thumbnail-trigger="hover"
>
  <template #default="{ item }"><SwImage :src="item.img" ratio="16/9" /></template>
</SwCarousel>

Custom indicator

For a fully custom indicator (progress bar / counter / titled thumbnails) use the #indicator slot:

<SwCarousel :items="list">
  <template #default="{ item }"><img :src="item.img"></template>
  <template #indicator="{ current, count, goTo }">
    <div class="my-pager">{{ current + 1 }} / {{ count }}</div>
  </template>
</SwCarousel>

CSS variables

Indicator (dots / thumbnails) styling is fully customizable via CSS variables — no need to override internal selectors:

Imperative control

<script setup>
const carouselRef = ref()
</script>

<template>
  <SwCarousel ref="carouselRef" :items="list"><template #default="{ item }">…</template></SwCarousel>
  <button @click="carouselRef.next()">Next</button>
</template>

Multiple slides per view (slidesPerView)

The classic "N cards per row, auto-rotating" recommendation-row shape — slidesPerView sets how many slides fit per view (responsive via semantic breakpoints), gap sets spacing; stepping is always one slide, and loop / autoplay / dragging / dots all keep working. Complements SwRail (free scrolling, no loop/autoplay): pick this component for auto-rotation, SwRail for free scrolling.

Props

Per-slide exposure tracking (:track)

A carousel's exposure semantics differ from SwLink's "entered viewport once": under loop / autoplay, non-active slides are translated out of the visible area, so IntersectionObserver on a slot-level SwLink is unreliable — only the carousel engine knows "which slide is showing", hence the component-level :track:

<SwCarousel :items="banners" :track="{
  exposure: (item, index) => ({
    event: 'appPageitemExposure',
    payload: {
      item_id: (item as Banner).id, item_type: 'banner', item_name: (item as Banner).title,
      parent_item_id: '', position: index + 1, page_key: 'home', page_name: 'Home',
    },
  }),
}">
  <template #default="{ item }">
    <SwLink :to="item.link"><SwImage :src="item.img" ratio="16/9" /></SwLink>
  </template>
</SwCarousel>

• Timing: each slide reports when it becomes current and the container has entered the viewport (one-shot IO ≥50%); each slide reports at most once per component instance (autoplay loops don't re-report); replacing items (new content) resets the dedupe set.
• exposure(item, index) maps a carousel item to a tracking spec; returning undefined skips that slide.
• Click tracking is not built in — slide content is a business slot; click semantics belong to the SwLink :track.click on the content (see example above).
• Reporting goes through useTracker (silent no-op when the tracker gate is off).

Events

Slots

Exposed methods (defineExpose)

Notes

• items-based + required #default: render each slide via the #default="{ item, index }" scoped slot; index is the real logical index (clone frames also map back to the real index). Passing :items without a #default slot renders blank frames and warns in the dev console.
• Banner links come from item data: the component has no built-in link; wrap the whole slide in SwLink for image-only banners, or put the CTA (SwLink / SwButton) inside the slide for banners with buttons — don't wrap the whole thing in <a>.
• Muted media for autoplay: if a slide contains a video, autoplay scenarios follow browser policy (muted).
• Use SwRail for horizontal scrolling: SwCarousel is a one-screen-at-a-time carousel, not a free rail.

active is true only for the current real slide, never for loop clones. autoplay is reactive: disable it while video prepares/plays, then enable it after poster fallback to restart the full image delay. See SwVideoBackground.