Incomplete Documentation: loop mode centeredSlides and slidesPerView behavior not described despite update

[hannahb-cogapp]

Clear and concise description of the problem

As a developer using Swiper, I want the documentation for loop mode to state the correct minimum number of slides required when centeredSlides is enabled, since Swiper's internal logic increases this number compared to what is currently documented.

I see a previous update was made, but the documentation still isn't accurate.

Suggested solution

Update the documentation for Swiper loop mode (https://swiperjs.com/swiper-api#param-loop) to cover:

• What happens when centeredSlides: true is used with loop mode.
• The internal logic (found in src/core/loop/loopFix.mjs):
  swiper/src/core/loop/loopFix.mjs

// Lines 50 - 67  
let loopedSlides = bothDirections
    ? Math.max(slidesPerGroup, Math.ceil(slidesPerView / 2))
    : slidesPerGroup;

  if (loopedSlides % slidesPerGroup !== 0) {
    loopedSlides += slidesPerGroup - (loopedSlides % slidesPerGroup);
  }
  loopedSlides += params.loopAdditionalSlides;
  swiper.loopedSlides = loopedSlides;
  const gridEnabled = swiper.grid && params.grid && params.grid.rows > 1;

  if (
    slides.length < slidesPerView + loopedSlides ||
    (swiper.params.effect === 'cards' && slides.length < slidesPerView + loopedSlides * 2)
  ) {
    showWarning(
      'Swiper Loop Warning: The number of slides is not enough for loop mode, it will be disabled or not function properly. You need to add more slides (or make duplicates) or lower the values of slidesPerView and slidesPerGroup parameters',
    );
  }

• When using bothDirections (centeredSlides or slidesOffsetBefore/After), slidesPerView will be incremented by more than 1 internally.
• Implications for minimal required slide count, loopedSlides, or layouts.

Example

With the following set up the warning "Swiper Loop Warning: The number of slides is not enough for loop mode, it will be disabled or not function properly. You need to add more slides (or make duplicates) or lower the values of slidesPerView and slidesPerGroup parameters" is logged to the console:
slidesPerView = 5, slidesPerGroup = 1 (default), centeredSlides = true, slides.length = 7

Walk Through

1. Calculation of loopedSlides:

// Lines 50 - 52
let loopedSlides = bothDirections
    ? Math.max(slidesPerGroup, Math.ceil(slidesPerView / 2))
    : slidesPerGroup;

Since bothDirections is true:

Math.ceil(slidesPerView / 2) = Math.ceil(5 / 2) = Math.ceil(2.5) = 3
So loopedSlides = 3

2. The condition on line 61 - 64 is met, which throws the error:

// Lines 61 - 68
  if (
    slides.length < slidesPerView + loopedSlides ||
    (swiper.params.effect === 'cards' && slides.length < slidesPerView + loopedSlides * 2)
  ) {
    showWarning(
      'Swiper Loop Warning: The number of slides is not enough for loop mode, it will be disabled or not function properly. You need to add more slides (or make duplicates) or lower the values of slidesPerView and slidesPerGroup parameters',
    );
  }

7 < 5 + 3 which is TRUE so the error is thrown.

However the documentation states "total number of slides must be more than or equal to slidesPerView + slidesPerGroup (and + 1 in case of centeredSlides)", which would be 5 + 1 + 1 = 7

This will help users anticipate possible layout issues or differences between configuration and the actual displayed result.

Validations

• Follow our Code of Conduct

• Read the docs.

• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.