Skip to content

Latest commit

 

History

History
979 lines (711 loc) · 29.4 KB

swiper-api.mdx

File metadata and controls

979 lines (711 loc) · 29.4 KB
Raw

import { MDXProvider } from '@mdx-js/react'; import Heading from '@/components/Heading.js'; import ModuleTitle from '@/components/ModuleTitle.js'; import { WithSidebarLayout } from '@/layouts/WithSidebarLayout.js'; export const meta = { title: 'Swiper API', description: 'SwipersJS API', };

import ApiDivider from '@/components/ApiDivider';

import { SwiperOptions } from '@/components/api/SwiperOptions'; import { SwiperEvents } from '@/components/api/SwiperEvents'; import { Swiper } from '@/components/api/Swiper';

import { A11yOptions } from '@/components/api/A11yOptions'; import { A11yEvents } from '@/components/api/A11yEvents'; import { A11yMethods } from '@/components/api/A11yMethods';

import { AutoplayOptions } from '@/components/api/AutoplayOptions'; import { AutoplayEvents } from '@/components/api/AutoplayEvents'; import { AutoplayMethods } from '@/components/api/AutoplayMethods';

import { ControllerOptions } from '@/components/api/ControllerOptions'; import { ControllerEvents } from '@/components/api/ControllerEvents'; import { ControllerMethods } from '@/components/api/ControllerMethods';

import { CoverflowEffectOptions } from '@/components/api/CoverflowEffectOptions'; import { CoverflowEffectEvents } from '@/components/api/CoverflowEffectEvents'; import { CoverflowEffectMethods } from '@/components/api/CoverflowEffectMethods';

import { CubeEffectOptions } from '@/components/api/CubeEffectOptions'; import { CubeEffectEvents } from '@/components/api/CubeEffectEvents'; import { CubeEffectMethods } from '@/components/api/CubeEffectMethods';

import { FadeEffectOptions } from '@/components/api/FadeEffectOptions'; import { FadeEffectEvents } from '@/components/api/FadeEffectEvents'; import { FadeEffectMethods } from '@/components/api/FadeEffectMethods';

import { FlipEffectOptions } from '@/components/api/FlipEffectOptions'; import { FlipEffectEvents } from '@/components/api/FlipEffectEvents'; import { FlipEffectMethods } from '@/components/api/FlipEffectMethods';

import { CardsEffectOptions } from '@/components/api/CardsEffectOptions';

import { CreativeEffectOptions } from '@/components/api/CreativeEffectOptions';

import { FreeModeOptions } from '@/components/api/FreeModeOptions'; import { GridOptions } from '@/components/api/GridOptions';

import { HashNavigationOptions } from '@/components/api/HashNavigationOptions'; import { HashNavigationEvents } from '@/components/api/HashNavigationEvents'; import { HashNavigationMethods } from '@/components/api/HashNavigationMethods';

import { HistoryOptions } from '@/components/api/HistoryOptions'; import { HistoryEvents } from '@/components/api/HistoryEvents'; import { HistoryMethods } from '@/components/api/HistoryMethods';

import { KeyboardOptions } from '@/components/api/KeyboardOptions'; import { KeyboardEvents } from '@/components/api/KeyboardEvents'; import { KeyboardMethods } from '@/components/api/KeyboardMethods';

import { ManipulationMethods } from '@/components/api/ManipulationMethods';

import { MousewheelOptions } from '@/components/api/MousewheelOptions'; import { MousewheelEvents } from '@/components/api/MousewheelEvents'; import { MousewheelMethods } from '@/components/api/MousewheelMethods';

import { NavigationOptions } from '@/components/api/NavigationOptions'; import { NavigationEvents } from '@/components/api/NavigationEvents'; import { NavigationMethods } from '@/components/api/NavigationMethods';

import { ParallaxOptions } from '@/components/api/ParallaxOptions';

import { PaginationOptions } from '@/components/api/PaginationOptions'; import { PaginationEvents } from '@/components/api/PaginationEvents'; import { PaginationMethods } from '@/components/api/PaginationMethods';

import { ScrollbarOptions } from '@/components/api/ScrollbarOptions'; import { ScrollbarEvents } from '@/components/api/ScrollbarEvents'; import { ScrollbarMethods } from '@/components/api/ScrollbarMethods';

import { ThumbsOptions } from '@/components/api/ThumbsOptions'; import { ThumbsEvents } from '@/components/api/ThumbsEvents'; import { ThumbsMethods } from '@/components/api/ThumbsMethods';

import { VirtualOptions } from '@/components/api/VirtualOptions'; import { VirtualEvents } from '@/components/api/VirtualEvents'; import { VirtualMethods } from '@/components/api/VirtualMethods';

import { ZoomOptions } from '@/components/api/ZoomOptions'; import { ZoomEvents } from '@/components/api/ZoomEvents'; import { ZoomMethods } from '@/components/api/ZoomMethods';

{/* prettier-ignore */}

If you are upgrading from Swiper 9 to Swiper 10, check out{' '} Migration Guide to Swiper 10

Swiper Full HTML Layout

<!-- Slider main container -->
<div class="swiper">
  <!-- Additional required wrapper -->
  <div class="swiper-wrapper">
    <!-- Slides -->
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    <div class="swiper-slide">Slide 3</div>
    ...
  </div>
  <!-- If we need pagination -->
  <div class="swiper-pagination"></div>

  <!-- If we need navigation buttons -->
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>

  <!-- If we need scrollbar -->
  <div class="swiper-scrollbar"></div>
</div>

Styles

Swiper package contains different sets of CSS, Less and SCSS styles:

CSS Styles

CSS styles for bundle version:

  • swiper-bundle.css - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)
  • swiper-bundle.min.css - same as previous but minified

CSS styles for bundle version (package imports):

  • swiper/css - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)
  • swiper/css/bundle - same as previous but minified

CSS styles for core version and modules (package imports):

  • swiper/css - only core Swiper styles
  • swiper/css/a11y - styles required for A11y module
  • swiper/css/autoplay - styles required for Autoplay module
  • swiper/css/controller - styles required for Controller module
  • swiper/css/effect-cards - styles required for Cards Effect module
  • swiper/css/effect-coverflow - styles required for Coverflow Effect module
  • swiper/css/effect-creative - styles required for Creative Effect module
  • swiper/css/effect-cube - styles required for Cube Effect module
  • swiper/css/effect-fade - styles required for Fade Effect module
  • swiper/css/effect-flip - styles required for Flip Effect module
  • swiper/css/free-mode - styles required for Free Mode module
  • swiper/css/grid - styles required for Grid module
  • swiper/css/hash-navigation - styles required for Hash Navigation module
  • swiper/css/history - styles required for History module
  • swiper/css/keyboard - styles required for Keyboard module
  • swiper/css/manipulation - styles required for Manipulation module
  • swiper/css/mousewheel - styles required for Mousewheel module
  • swiper/css/navigation - styles required for Navigation module
  • swiper/css/pagination - styles required for Pagination module
  • swiper/css/parallax - styles required for Parallax module
  • swiper/css/scrollbar - styles required for Scrollbar module
  • swiper/css/thumbs - styles required for Thumbs module
  • swiper/css/virtual - styles required for Virtual module
  • swiper/css/zoom - styles required for Zoom module

Less Styles

Less styles are separate styles for core version and modules (package imports):

  • swiper/less - only core Swiper styles
  • swiper/less/bundle - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)
  • swiper/less/a11y - styles required for A11y module
  • swiper/less/autoplay - styles required for Autoplay module
  • swiper/less/controller - styles required for Controller module
  • swiper/less/effect-cards - styles required for Cards Effect module
  • swiper/less/effect-coverflow - styles required for Coverflow Effect module
  • swiper/less/effect-creative - styles required for Creative Effect module
  • swiper/less/effect-cube - styles required for Cube Effect module
  • swiper/less/effect-fade - styles required for Fade Effect module
  • swiper/less/effect-flip - styles required for Flip Effect module
  • swiper/less/free-mode - styles required for Free Mode module
  • swiper/less/grid - styles required for Grid module
  • swiper/less/hash-navigation - styles required for Hash Navigation module
  • swiper/less/history - styles required for History module
  • swiper/less/keyboard - styles required for Keyboard module
  • swiper/less/manipulation - styles required for Manipulation module
  • swiper/less/mousewheel - styles required for Mousewheel module
  • swiper/less/navigation - styles required for Navigation module
  • swiper/less/pagination - styles required for Pagination module
  • swiper/less/parallax - styles required for Parallax module
  • swiper/less/scrollbar - styles required for Scrollbar module
  • swiper/less/thumbs - styles required for Thumbs module
  • swiper/less/virtual - styles required for Virtual module
  • swiper/less/zoom - styles required for Zoom module

SCSS Styles

SCSS styles are also separate styles for core version and modules (package imports):

  • swiper/scss - only core Swiper styles
  • swiper/scss/bundle - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)
  • swiper/scss/a11y - styles required for A11y module
  • swiper/scss/autoplay - styles required for Autoplay module
  • swiper/scss/controller - styles required for Controller module
  • swiper/scss/effect-cards - styles required for Cards Effect module
  • swiper/scss/effect-coverflow - styles required for Coverflow Effect module
  • swiper/scss/effect-creative - styles required for Creative Effect module
  • swiper/scss/effect-cube - styles required for Cube Effect module
  • swiper/scss/effect-fade - styles required for Fade Effect module
  • swiper/scss/effect-flip - styles required for Flip Effect module
  • swiper/scss/free-mode - styles required for Free Mode module
  • swiper/scss/grid - styles required for Grid module
  • swiper/scss/hash-navigation - styles required for Hash Navigation module
  • swiper/scss/history - styles required for History module
  • swiper/scss/keyboard - styles required for Keyboard module
  • swiper/scss/manipulation - styles required for Manipulation module
  • swiper/scss/mousewheel - styles required for Mousewheel module
  • swiper/scss/navigation - styles required for Navigation module
  • swiper/scss/pagination - styles required for Pagination module
  • swiper/scss/parallax - styles required for Parallax module
  • swiper/scss/scrollbar - styles required for Scrollbar module
  • swiper/scss/thumbs - styles required for Thumbs module
  • swiper/scss/virtual - styles required for Virtual module
  • swiper/scss/zoom - styles required for Zoom module

Initialize Swiper

Now, when we have Swiper's HTML, we need to initialize it using the following function:

new Swiper(swiperContainer, parameters)- initialize swiper with options

  • swiperContainer - HTMLElement or string (with CSS Selector) of swiper container HTML element. Required.
  • parameters - object - object with Swiper parameters. Optional.
  • Method returns initialized Swiper instance

For example:

const swiper = new Swiper('.swiper', {
  speed: 400,
  spaceBetween: 100,
});

After you initialize Swiper it is possible to access to Swiper's instance on its HTMLElement. It is swiper property of Swiper's HTML container element:

const swiper = document.querySelector('.swiper').swiper;

// Now you can use all slider methods like
swiper.slideNext();

Parameters

Let's look on list of all available parameters:

Methods & Properties

After we initialize Slider we have its initialized instance in variable (like swiper variable in example above) with helpful methods and properties:

Events

Swiper comes with a bunch of useful events you can listen. Events can be assigned in two ways:

  1. Using on parameter on swiper initialization:

    const swiper = new Swiper('.swiper', {
  // ...
  on: {
    init: function () {
      console.log('swiper initialized');
    },
  },
});

  2. Using on method after swiper initialization.

    const swiper = new Swiper('.swiper', {
  // ...
});
swiper.on('slideChange', function () {
  console.log('slide changed');
});

{/* prettier-ignore */}

Please note, that this keyword within event handler always points to Swiper instance

Modules

Navigation Parameters

Navigation Methods

Navigation Events

Navigation CSS Custom Properties

 {
  --swiper-navigation-size: 44px;
  --swiper-navigation-top-offset: 50%;
  --swiper-navigation-sides-offset: 10px;
  --swiper-navigation-color: var(--swiper-theme-color);
}

Pagination Parameters

Pagination Methods

Pagination Events

Pagination CSS Custom Properties

 {
  --swiper-pagination-color: var(--swiper-theme-color);
  --swiper-pagination-left: auto;
  --swiper-pagination-right: 8px;
  --swiper-pagination-bottom: 8px;
  --swiper-pagination-top: auto;
  --swiper-pagination-fraction-color: inherit;
  --swiper-pagination-progressbar-bg-color: rgba(0, 0, 0, 0.25);
  --swiper-pagination-progressbar-size: 4px;
  --swiper-pagination-bullet-size: 8px;
  --swiper-pagination-bullet-width: 8px;
  --swiper-pagination-bullet-height: 8px;
  --swiper-pagination-bullet-inactive-color: #000;
  --swiper-pagination-bullet-inactive-opacity: 0.2;
  --swiper-pagination-bullet-opacity: 1;
  --swiper-pagination-bullet-horizontal-gap: 4px;
  --swiper-pagination-bullet-vertical-gap: 6px;
}

Scrollbar Parameters

Scrollbar Methods

Scrollbar Events

Scrollbar CSS Custom Properties

 {
  --swiper-scrollbar-border-radius: 10px;
  --swiper-scrollbar-top: auto;
  --swiper-scrollbar-bottom: 4px;
  --swiper-scrollbar-left: auto;
  --swiper-scrollbar-right: 4px;
  --swiper-scrollbar-sides-offset: 1%;
  --swiper-scrollbar-bg-color: rgba(0, 0, 0, 0.1);
  --swiper-scrollbar-drag-bg-color: rgba(0, 0, 0, 0.5);
  --swiper-scrollbar-size: 4px;
}

Autoplay Parameters

Autoplay Methods

Autoplay Events

Free Mode Parameters

Grid Parameters

Manipulation module adds useful Swiper methods to manipulate slides. It makes sense to use it only with Swiper Core version, not intended to be uses with Swiper React or Vue.

Manipulation Methods

Swiper supports parallax transition effects for swiper/slides nested elements. There are two types of parallax elements supported:

  • Direct child elements of swiper. Parallax effect for such elements will depend on total slider progress. Useful for parallax backgrounds
  • Slides child elements. Parallax effect for such elements will depend on slide progress

To enable parallax effects you need to init Swiper with passed parallax:true parameter and add one of the following (or mix) attributes to required elements:

  • data-swiper-parallax - enable transform-translate parallax transition. This attribute may accept:
    • number - value in px (as for title, subtitle in example above) to move element depending on progress. In this case such element will be moved on ± this value in px depending on slide position (next or previous)
    • percentage - (as for "parallax-bg") to move element depending on progress and on its size. In this case such element will be moved on ± this percentage of its size (width in horizontal direction, and height in vertical direction) depending on slide position (next or previous). So if element has 400px width and you specified data-swiper-parallax="50%" then it will be moved on ± 200px
  • data-swiper-parallax-x - same but for x-axis direction
  • data-swiper-parallax-y - same but for y-axis direction
  • data-swiper-parallax-scale - scale ratio of the parallax element when it is in "inactive" (not on active slide) state
  • data-swiper-parallax-opacity - opacity of the parallax element when it is in "inactive" (not on active slide) state
  • data-swiper-parallax-duration - custom transition duration for parallax elements
<div class="swiper">
  <!-- Parallax background element -->
  <div
    class="parallax-bg"
    style="background-image:url(path/to/image.jpg)"
    data-swiper-parallax="-23%"
  ></div>
  <div class="swiper-wrapper">
    <div class="swiper-slide">
      <!-- Each slide has parallax title -->
      <div class="title" data-swiper-parallax="-100">Slide 1</div>
      <!-- Parallax subtitle -->
      <div class="subtitle" data-swiper-parallax="-200">Subtitle</div>
      <!-- And parallax text with custom transition duration -->
      <div
        class="text"
        data-swiper-parallax="-300"
        data-swiper-parallax-duration="600"
      >
        <p>Lorem ipsum dolor sit amet, ...</p>
      </div>
      <!-- Opacity parallax -->
      <div data-swiper-parallax-opacity="0.5">I will change opacity</div>
      <!-- Scale parallax -->
      <div data-swiper-parallax-scale="0.15">I will change scale</div>
    </div>
    ...
  </div>
</div>

Parallax Parameters

Since version 9 Swiper doesn't have a specific lazy loading API, as it relies on native browser lazy loading feature. To use lazy loading, we just need to set loading="lazy" on images and add preloader element:

<div class="swiper">
  <div class="swiper-wrapper">
    <!-- Lazy image -->
    <div class="swiper-slide">
      <img src="path/to/picture-1.jpg" loading="lazy" />
      <div class="swiper-lazy-preloader"></div>
    </div>

    <!-- Lazy image with srcset -->
    <div class="swiper-slide">
      <img
        src="path/to/logo-small.png"
        srcset="path/to/logo-large.png 2x"
        loading="lazy"
      />
      <div class="swiper-lazy-preloader"></div>
    </div>
  </div>
</div>

As you see:

  • Lazy image must have loading="lazy" attribute
  • Add animated preloader spinner to slide which will be removed automatically after image loaded:
<div class="swiper-lazy-preloader"></div>

Or white one for dark layout:

<div class="swiper-lazy-preloader swiper-lazy-preloader-white"></div>

Be sure to have the effect param set to 'fade' in order for this to work.

{/* prettier-ignore */}

Note that crossFade should be set to true in order to avoid seeing content behind or underneath.

Fade Effect Parameters

Be sure to have the effect param set to 'coverflow' in order for this to work.

Coverflow Effect Parameters

Be sure to have the effect param set to 'flip' in order for this to work.

Flip Effect Parameters

Be sure to have the effect param set to 'cube' in order for this to work.

Cube Effect Parameters

Be sure to have the effect param set to 'cards' in order for this to work.

Cards Effect Parameters

Be sure to have the effect param set to 'creative' in order for this to work.

Creative Effect Parameters

In addition to Controller component Swiper comes with Thumbs component that is designed to work with additional thumbs swiper in a more correct way than Controller which is used for syncing two swipers.

Thumbs Parameters

Thumbs Methods

Swiper supports zoom images functionality (similar to what you see on iOS when browsing single photo) where you can zoom-in image by pinch gesture and or by zoom-in/out by double tap on it. In this case, additional layout is required:

<div class="swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide">
      <div class="swiper-zoom-container">
        <img src="path/to/image1.jpg" />
      </div>
    </div>
    <div class="swiper-slide">
      <div class="swiper-zoom-container">
        <img src="path/to/image2.jpg" />
      </div>
    </div>
    <div class="swiper-slide">Plain slide with text</div>
    <div class="swiper-slide">
      <!-- Override maxRatio parameter -->
      <div class="swiper-zoom-container" data-swiper-zoom="5">
        <img src="path/to/image1.jpg" />
      </div>
    </div>
  </div>
</div>
  • All "zoomable" images should be wrapped with the div with swiper-zoom-container class.
  • By default it expects to zoom one of the img, picture or canvas element. If you want to make zoom on some other custom element, then just add swiper-zoom-target class to this element. For example: 
    <div class="swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide">
      <div class="swiper-zoom-container">
        <!-- custom zoomable element -->
        <div
          class="swiper-zoom-target"
          style="background-image: url(...)"
        ></div>
      </div>
    </div>
  </div>
</div>
  • You can override maxRatio parameter for specific slides by using data-swiper-zoom attribute on zoom container.

Zoom Parameters

Zoom Methods

Zoom Events

Keyboard Control Parameters

Keyboard Control Methods

Keyboard Events

Mousewheel Control Parameters

Mousewheel Control Methods

Mousewheel Events

Virtual Slides module allows to keep just required amount of slides in DOM. It is very useful in terms in performance and memory issues if you have a lot of slides, especially slides with heavyweight DOM tree or images.

{/* prettier-ignore */}

Note that according to Virtual Slides realization it doesn't work with Grid module and slidesPerView: 'auto'

Virtual Slides Parameters

Virtual Slides Methods

Virtual Slides Dom

Since version 9, Swiper virtual slides can work with slides originally rendered in DOM. On initialize it will remove them from DOM, cache and then re-use the ones which are required:

<div class="swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    ...
    <div class="swiper-slide">Slide 100</div>
  </div>
</div>
<script>
  const swiper = new Swiper('.swiper', {
    virtual: {
      enabled: true,
    },
  });
</script>

Hash navigation is intended to have a link to specific slide that allows to load page with specific slide opened.

To make it work, you need to enable it by passing hashNavigation:true parameter and adding slides hashes in data-hash attribute:

<div class="swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide" data-hash="slide1">Slide 1</div>
    <div class="swiper-slide" data-hash="slide2">Slide 2</div>
    <div class="swiper-slide" data-hash="slide3">Slide 3</div>
    <div class="swiper-slide" data-hash="slide4">Slide 4</div>
    <div class="swiper-slide" data-hash="slide5">Slide 5</div>
    ...
  </div>
</div>
const swiper = new Swiper('.swiper', {
  //enable hash navigation
  hashNavigation: true,
});

Hash Navigation Parameters

Hash Navigation Events

History Navigation Parameters

Controller Parameters

Controller Methods

Accessibility Parameters

Custom Build

You have two options of making custom version of Swiper.

Using JS Modules

If you use bundler with JS modules support in your project you can import only the modules you need:

// Import Swiper and modules
import Swiper from 'swiper';
import { Navigation, Pagination, Scrollbar } from 'swiper/modules';

// Now you can use Swiper
const swiper = new Swiper('.swiper', {
  // Install modules
  modules: [Navigation, Pagination, Scrollbar],
  speed: 500,
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
  // ...
});

The following modules are exported:

  • Virtual - Virtual Slides module
  • Keyboard - Keyboard Control module
  • Mousewheel - Mousewheel Control module
  • Navigation - Navigation module
  • Pagination - Pagination module
  • Scrollbar - Scrollbar module
  • Parallax - Parallax module
  • FreeMode - Free Mode module
  • Grid - Grid module
  • Manipulation - Slides manipulation module (only for Core version)
  • Zoom - Zoom module
  • Controller - Controller module
  • A11y - Accessibility module
  • History - History Navigation module
  • HashNavigation - Hash Navigation module
  • Autoplay - Autoplay module
  • EffectFade - Fade Effect module
  • EffectCube - Cube Effect module
  • EffectFlip - Flip Effect module
  • EffectCoverflow - Coverflow Effect module
  • EffectCards - Cards Effect module
  • EffectCreative - Creative Effect module
  • Thumbs - Thumbs module

Using Build Script

Swiper comes with gulp builder that allows to build custom library version where you may include only required modules. We need the following:

  1. Download and unzip Swiper GitHub repository to local folder

  2. Install Node.js (if not installed)

  3. Now, we need to install required dependencies. Go to the folder with downloaded and unzipped Swiper repository and execute in terminal:

    $ npm install

  4. Open scripts/build-config.js file:

    module.exports = {
  // remove modules you don't need
  modules: [
    'virtual',
    'keyboard',
    'mousewheel',
    'navigation',
    'pagination',
    'scrollbar',
    'parallax',
    'zoom',
    'controller',
    'a11y',
    'history',
    'hash-navigation',
    'autoplay',
    'thumbs',
    'free-mode',
    'grid',
    'manipulation',
    'effect-fade',
    'effect-cube',
    'effect-flip',
    'effect-coverflow',
    'effect-creative',
    'effect-cards',
  ],
};

  5. Now, we are ready to build custom version of Swiper:

    $ npm run build:prod

  6. That is all. Generated CSS and JS files and their minified versions will be available in dist/ folder.

TypeScript Definitions

Swiper is fully typed, it exports Swiper and SwiperOptions types:

// main.ts
import Swiper from 'swiper';
import { SwiperOptions } from 'swiper/types';

const swiperParams: SwiperOptions = {
  slidesPerView: 3,
  spaceBetween: 50,
};

const swiper = new Swiper('.swiper', swiperParams);

You can also check auto generated TypeScript definitions explorer for all the types, options, properties and methods.

export default function Page({ children }) { const components = { h1: Heading.h1, h2: Heading.h2, h3: Heading.h3, h4: Heading.h4, }; return ( {children} ); }