Swiper Virtual Slides Synchronization with Framework State Stores

Direct Answer

The minimal contract is a one-way data flow: the store owns the slide list, Swiper owns the active index, and a driving-state flag mediates programmatic navigation. Pass a plain array to virtual.slides, batch swiper.update() after mutations, and write the index back to the store only from onTransitionEnd.

1. Minimal contract: plain arrays and batched updates

Swiper's Virtual Slides module expects a plain array at initialization and when assigning virtual.slides. Framework stores—Redux, Pinia, Vuex, or Svelte—expose reactive proxies or immutable snapshots. Passing a proxy directly can confuse Swiper's internal diffing and cause missed slides or incorrect index mapping. Normalize the store slice with Array.from() or .slice() before assignment.

Do not call swiper.update() on every store notification. For datasets beyond a few hundred items, per-mutation updates trigger layout thrashing. Instead, debounce or batch store changes and invoke update() once per navigation or filter cycle. This recalculates the virtual buffer without forcing repeated reflows.

2. Programmatic navigation without circular loops

slideTo() and slideNext() can safely drive store actions if you guard the write-back. Set a flag—e.g., isSwiperDriving—before calling the programmatic API. Inside onSlideChange or onTransitionEnd, skip the store dispatch while that flag is true, then clear it after the transition completes. Without this guard, the store mutation re-renders the component, Swiper updates, and the cycle repeats.

3. Authoritative index: onTransitionEnd

Use onTransitionEnd, not onSlideChange, as the authoritative write-back point. onSlideChange fires when the index changes but before the animation settles; rapid user gestures or interrupted transitions can produce intermediate values. onTransitionEnd fires after the animation completes, giving the final stable realIndex. Writing this value to the store avoids race conditions where the store index lags behind the visible slide.

Implementation sketch

const isSwiperDriving = useRef(false);

const handleStoreChange = (items) => {
  const plain = Array.from(items);
  swiper.virtual.slides = plain;
  debouncedUpdate();
};

const goToSlide = (index) => {
  isSwiperDriving.current = true;
  swiper.slideTo(index);
};

const handleTransitionEnd = () => {
  if (isSwiperDriving.current) {
    isSwiperDriving.current = false;
    return;
  }
  dispatch(setActiveIndex(swiper.realIndex));
};

Assumptions and verification

This assumes a recent Swiper version with the Virtual module enabled and slides that have stable, measurable dimensions. Fluid or CSS-in-JS-measured widths break the virtual buffer's index calculations; constrain slide width or configure slideSize explicitly. To verify, log swiper.realIndex and the store's active index after a transition—they should match without re-initializing Swiper.

If your slides use percentage-based widths inside a flex container, share how the container width is constrained; that detail changes whether you need explicit slideSize configuration or can rely on the default virtual buffer.