Swiper v9 loop rewrite: slide sizing contract with slidesPerView 'auto' and centeredSlides after upgrading from v8

The Sizing Contract for Auto-Width Loops

In Swiper v9 and later, the loop mechanism was rewritten to move away from simple cloning toward a more dynamic rearrangement of elements. When using slidesPerView: 'auto' and centeredSlides: true, Swiper calculates the transition offset based on the computed width of the slides at the moment of initialization.

Requirements for Slide Widths

For the loop to function without jumps or offsets, Swiper requires that slide dimensions are stable and available in the DOM before the internal loop calculations occur. The "contract" is as follows:

• Fixed CSS Widths: Slides must have a defined width (via CSS width or flex-basis) that does not rely on the Swiper container's internal calculations.
• Avoid Transitions on Init: CSS transitions or animations applied to the slide widths during page load can cause Swiper to capture incorrect dimensions, leading to the offsets you are experiencing.
• Margin Inclusion: Swiper includes margin-right (or spaceBetween) in its total offset calculations. If margins are applied inconsistently across slides, the loop center will shift.

RealIndex vs. ActiveIndex

After the v9 rewrite, realIndex is the only stable reference for the actual data slide being viewed. Because the loop now rearranges elements to create the illusion of infinity, activeIndex refers to the position within the rendered DOM (including duplicates), which changes as the user swipes. Use realIndex for all logic tied to your data source; it remains stable regardless of the internal rearrangement.

Handling Late-Loading CSS

If your CSS is loaded asynchronously or applied after Swiper initializes, the initial measurements will be wrong. The intended fix is to trigger a recalculation once the styles are active.

// After CSS is confirmed to be loaded
swiper.update();

While update() refreshes dimensions, if the loop structure itself was calculated with 0px widths, you may need to destroy and re-initialize the instance to ensure the loop duplicates are correctly positioned.

Verification Steps

1. Inspect the .swiper-slide-duplicate elements in the DevTools. Ensure their computed width exactly matches the original slides.
2. Check if loopedSlides is explicitly set. When using slidesPerView: 'auto', Swiper may not always guess the correct number of clones needed to fill the viewport, causing a gap during the loop transition.

Diagnostic Question: Are you using a CSS-in-JS library or a framework (like Vue/React) where the slides are rendered before the styles are injected into the document head?