DOM structure

A Swiper instance expects a container, a wrapper, and one or more slides. Optional UI controls (navigation and pagination) can be placed inside or outside the container.

<div class="swiper-container" id="demo-swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide">Slide A</div>
    <div class="swiper-slide">Slide B</div>
    <div class="swiper-slide">Slide C</div>
  </div>
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>
  <div class="swiper-pagination"></div>
</div>

Initialization

new Swiper(container, params)

Instantiate with a CSS selector or element reference. When multiple carousels exist on a page, give each a distinct id or class. The class name swiper-container must remain on each container.

<div id="galleryA" class="swiper-container"> ... </div>
<div id="galleryB" class="swiper-container"> ... </div>

<script>
  const galleryA = new Swiper('#galleryA', { /* options */ });
  const galleryB = new Swiper('#galleryB', { /* options */ });
</script>

General options

1. initialSlide

Zero-based index of the starting slide. Default: 0.

<script>
  const slider = new Swiper('.swiper-container', {
    initialSlide: 1
  });
</script>

2. direction

Scroll axis: horizontal (default) or vertical (set a container height for vertical).

<script>
  const verticalView = new Swiper('.swiper-container', {
    direction: 'vertical'
  });
</script>

3. speed

Transition duration in milliseconds. Default: 300.

<script>
  const fastSwitch = new Swiper('.swiper-container', {
    speed: 500
  });
</script>

4. grabCursor

Shows a grab cursor on desktop when true. Default: false.

<script>
  const withCursor = new Swiper('.swiper-container', {
    grabCursor: true
  });
</script>

5. parallax

Enables parallax transitions across container/slide descendants via data attributes. Default: false.

• Position offset: data-swiper-parallax, or axis-specific data-swiper-parallax-x / -y
  • Accepts pixels (e.g., -300) or percentage of the element’s size (e.g., 25%).
• Opacity: data-swiper-parallax-opacity (0–1)
• Scale: data-swiper-parallax-scale (e.g., 0.7)
• Duration: data-swiper-parallax-duration (ms). Defaults to speed if not set.

Offset must be specified to opacity or scale effects to take effect.

<div class="swiper-container" id="parallax-ex">
  <div class="bg" style="background-image:url(/img/Parallax.jpg)"
       data-swiper-parallax="-20%"
       data-swiper-parallax-duration="2500"></div>
  <div class="swiper-wrapper">
    <div class="swiper-slide">
      <h2 class="title" data-swiper-parallax="-120">Title enters from right</h2>
      <h3 class="subtitle" data-swiper-parallax="-240">Subtitle enters further</h3>
      <div class="content"
           data-swiper-parallax="-320"
           data-swiper-parallax-duration="700">
        Parallax text with custom timing
      </div>
      <div data-swiper-parallax="0" data-swiper-parallax-opacity="0.4">Fades while sliding</div>
      <div data-swiper-parallax="0" data-swiper-parallax-scale="0.8">Scales while sliding</div>
    </div>
  </div>
</div>

<script>
  const parallaxSwiper = new Swiper('#parallax-ex', {
    parallax: true,
    speed: 600
  });
</script>

6. setWrapperSize

When true, Swiper explicitly sets wrapper width/height to the total slide size to improve certain flex layouts. Default: false.

<script>
  const sized = new Swiper('.swiper-container', {
    setWrapperSize: true
  });

  // Inspect total virtual size (sum of slide sizes)
  console.log('virtualSize:', sized.virtualSize);
  console.log('wrapper width:', sized.$wrapperEl.css('width'));
</script>

7. virtualTranslate

Simulates translation without moving slides in the DOM. Progress and callbacks still fire. Default: false.

<script>
  const ghost = new Swiper('.swiper-container', {
    virtualTranslate: true
  });
</script>

8. a11y

Accessibility module configuration. Enable to provide ARIA attributes and keyboard/screen-reader helpers.

<script>
  const accessible = new Swiper('.swiper-container', {
    a11y: { enabled: true }
  });
</script>

9. width

Forces a specific width (px). Useful when initializing in hidden containers where auto-measurement fails. Set undefined to re-enable auto sizing.

<script>
  const fixedWidth = new Swiper('.swiper-container', {
    width: 840,
    breakpoints: {
      1024: { width: 560 },
      768: { width: undefined } // restore auto width
    },
    on: {
      resize() {
        this.params.width = window.innerWidth; // full width on resize
        this.update();
      }
    }
  });
</script>

10. height

For vertical carousels, sets a fixed pixel height. Similar purpose as width for hidden-init cases.

<script>
  const tall = new Swiper('.swiper-container', {
    direction: 'vertical',
    height: 360 // or use window.innerHeight for full height
  });
</script>

11. roundLengths

Rounds slide sizes to whole pixels to mitigate blurry text/borders on some displays. Default: false.

<script>
  const crisp = new Swiper('.swiper-container', {
    roundLengths: true
  });
</script>

12. breakpoints

Responsive parameter overrides applied at or below the specified widths (similar to CSS max-width queries). Only options that don’t change structural layout (e.g., slidesPerView, spaceBetween, slidesPerGroup) are supported; properties like loop, direction, effect, slidesPerColumn are ignored here.

<script>
  const responsive = new Swiper('.swiper-container', {
    slidesPerView: 4,
    spaceBetween: 40,
    breakpoints: {
      // ≤ 360px
      360: {
        slidesPerView: 1,
        spaceBetween: 8
      },
      // ≤ 480px
      480: {
        slidesPerView: 2,
        spaceBetween: 16
      },
      // ≤ 768px
      768: {
        slidesPerView: 3,
        spaceBetween: 24
      }
    }
  });
</script>

13. breakpointsInverse

Calculates breakpoint rules as min-width (applies at or above). Default: false.

<script>
  const upwards = new Swiper('.swiper-container', {
    breakpointsInverse: true,
    slidesPerView: 1,
    spaceBetween: 12,
    breakpoints: {
      // ≥ 360px
      360: { slidesPerView: 2, spaceBetween: 16 },
      // ≥ 480px
      480: { slidesPerView: 3, spaceBetween: 24 },
      // ≥ 768px
      768: { slidesPerView: 4, spaceBetween: 32 }
    }
  });
</script>

14. autoHeight

When enabled, container and wrapper height adapt to the active slide’s height. Default: false.

<script>
  const adaptive = new Swiper('.swiper-container', {
    autoHeight: true
  });
</script>

15. uniqueNavElements

When true (default) and navigation/pagination selectors are strings, Swiper searches only within the container for matching elements. Set to false to use controls outside the container or shared across instances.

<div class="controls">
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>
  <div class="swiper-pagination"></div>
</div>

<script>
  const externalControls = new Swiper('.swiper-container', {
    pagination: { el: '.swiper-pagination' },
    navigation: {
      nextEl: '.swiper-button-next',
      prevEl: '.swiper-button-prev'
    },
    uniqueNavElements: false
  });
</script>

16. nested

For nested carousels with the same direction, enable nested on the child so dragging inside it doesn’t trigger the parent.

<div id="outer" class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide">
      <div id="inner" class="swiper-container">
        <div class="swiper-wrapper">
          <div class="swiper-slide">Inner 1</div>
          <div class="swiper-slide">Inner 2</div>
        </div>
      </div>
    </div>
    <div class="swiper-slide">Outer 2</div>
  </div>
</div>

<script>
  const outer = new Swiper('#outer');
  const inner = new Swiper('#inner', {
    nested: true,
    resistanceRatio: 0 // dampens propagation to the parent
  });
</script>

17. runCallbacksOnInit

If initialSlide isn’t 0 or loop: true, Swiper normally fires transition/slide change callbacks during init. Set this to false to suppress those initial callbacks. Default: true.

<script>
  const controlled = new Swiper('.swiper-container', {
    loop: true,
    runCallbacksOnInit: false,
    on: {
      slideChangeTransitionStart() {
        console.log('This will not fire on initial init with runCallbacksOnInit=false');
      }
    }
  });
</script>

18. watchOverflow

Disables Swiper and hides controls when there aren’t enough slides to scroll (e.g., a single slide). Has no effect with loop: true because slides are duplicated. Default: false.

<div class="swiper-container" id="overflow-demo">
  <div class="swiper-wrapper">
    <div class="swiper-slide">Only one slide</div>
  </div>
  <div class="swiper-pagination"></div>
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>
  <div class="swiper-scrollbar"></div>
</div>

<script>
  const overflowDemo = new Swiper('#overflow-demo', {
    watchOverflow: true,
    navigation: {
      nextEl: '.swiper-button-next',
      prevEl: '.swiper-button-prev'
    },
    pagination: { el: '.swiper-pagination' },
    scrollbar: { el: '.swiper-scrollbar' }
  });
</script>

19. on

Register event listeners. In side callbacks, this refers to the Swiper instance.

<script>
  const eventsA = new Swiper('.swiper-container', {
    on: {
      slideChange() {
        console.log('Active index:', this.activeIndex);
      }
    }
  });

  // Alternatively, attach after creation
  const eventsB = new Swiper('.swiper-container');
  eventsB.on('slideChange', function () {
    console.log('Changed to', this.activeIndex);
  });
</script>

20. init

Create without immediately initializing; call .init() manually later. Default: true.

<script>
  const lazyInit = new Swiper('.swiper-container', { init: false });
  // Do layout work or show hidden container...
  lazyInit.init();
</script>

21. preloadImages

Forces eager loading of all images in slides when true. Default: true.

<script>
  const noPreload = new Swiper('.swiper-container', {
    preloadImages: false
  });
</script>

22. updateOnImagesReady

Recalculates Swiper after embedded images finish loading. Effective when preloadImages: true. Default: true.

<script>
  const autoUpdate = new Swiper('.swiper-container', {
    preloadImages: true,
    updateOnImagesReady: true
  });
</script>