Skip to content

cycjimmy/awesome-swiper

Repository files navigation

Awesome Swiper

libraries dependency status libraries sourcerank Release date rollup semantic-release npm license

English | 中文


Install

NPM version NPM bundle size npm download

# via npm
$ npm install @cycjimmy/awesome-swiper --save

# or via yarn
$ yarn add @cycjimmy/awesome-swiper

Usage

Awesome Swiper based on Swiper 5+. Add Script of swiper in your project first

import Swiper from 'swiper';
import AwesomeSwiper from '@cycjimmy/awesome-swiper';

// OR
const Swiper = require('swiper');
const AwesomeSwiper = require('@cycjimmy/awesome-swiper');
const awesomeSwiper = new AwesomeSwiper([SwiperModule]).init(context [, ...config] [, ...overlayConfig]);

// if need thumbs
const awesomeSwiper = new AwesomeSwiper([SwiperModule])
                        .init(context [, ...config] [, ...overlayConfig])
                        .addThumbs(thumbsContext [, ...thumbsConfig] [, ...thumbsExtraConfig]);

new AwesomeSwiper([SwiperModule]): Create new instance

  • Params:
    • SwiperModule: [Object] Set custom swiper constructor. Make sure the swiper version is 5+.
  • Return awesomeSwiper instance

Methods of awesomeSwiper instance:

init(context [, ...config] [, ...overlayConfig]): Initialize the main swiper instance:

  • Params:
    • context: [String | Element] the wrapper of swiper. Height and width of wrapper must be initialized.
    • config: [Object]
      • speed: [Number] Duration of transition between slides (in ms). Default 300.
      • loop: [Boolean] Set to true to enable loop. Default false.
      • autoplay: [Number] Set autoplay delay. 0 means close. Default 0.
      • direction: [String] Set direction. Could be 'horizontal' or 'vertical'. Default 'horizontal'.
      • themeColor: [String] Set theme color for the swiper instance with a color name or a hex value. Default '' is blue.
      • spaceBetween: [Number] Distance between slides in px. Default 0.
      • slidesPerView: [Number | 'auto'] Number of slides per view. Default 1.
      • mousewheel: [Boolean] Set to true to enable navigation through slides using mouse wheel. Default false.
      • autoFixFullImg: [Boolean] Set true to auto fix full images. Default false. Tip: Due to the impact of performance, not necessary not to set it.
      • autoHeight: [Boolean] Set to true and slider wrapper will adapt its height to the height of the currently active slide. Default false.
      • pagination: [Object] Set pagination. If you do not want a pagination, set null.
        • color: [String] Set color for pagination with a color name or a hex value. Default '' is blue.
        • style: [Object] Custom pagination style. Recommended to only adjust the position here.
        • dynamicBullets: [Boolean] Good to enable if you use bullets pagination with a lot of slides. So it will keep only few bullets visible at the same time. Default false. See Swiper Pagination
      • navigation: [Object] Set navigation. If you do not want a navigation, set null.
        • color: [String] Set color for navigation with a color name or a hex value. Default '' is blue.
        • size: [String | Number] Set size for navigation.
        • styles: [Object] Custom style
          • prev: [Object] Custom style for prevEl.
          • next: [Object] Custom style for nextEl.
        • custom: [Object] Set custom navigation elements. Default null.
          • prevEl: [String | Element] Custom prev button element.
          • nextEl: [String | Element] Custom next button element.
    • overlayConfig: [Object] Use Custom swiper api to overlay config.
  • Return awesomeSwiper instance

addThumbs(thumbsContext [, ...thumbsConfig] [, ...thumbsExtraConfig]): Add thumbs swiper instance

  • Params:
    • thumbsContext: [String | Element] the wrapper of thumbs. Height and width of wrapper must be initialized.
    • thumbsConfig: [Object] You can set it follow swiper api.
      • direction: [String] Set direction. Could be 'horizontal' or 'vertical'.
      • spaceBetween: [Number] Distance between slides in px. Default 10.
      • slidesPerView: [Number | 'auto'] Number of slides per view. Default 'auto'.
    • thumbsExtraConfig: [Object] Extra config for thumbs.
      • mouseOverMode: [Boolean] set true to use mouse over mode. Default false.
      • autoFixFullImg: [Boolean] Set true to auto fix full images. Default false. Tip: Due to the impact of performance, not necessary not to set it.
  • Return awesomeSwiper instance

setInitialSlide(initialSlide): Set index number of initial slide.

  • Params:
    • initialSlide: [Number] Index number of initial slide.
  • Return awesomeSwiper instance

on(event, handler): Add event handler

  • Same as swiper.on(event, handler)
  • Return awesomeSwiper instance

off(event, handler): Remove event handler

  • Same as swiper.off(event, handler)
  • Return awesomeSwiper instance

new css classes in AwesomeSwiper

  • .swiper-full-img: Full images container.
  • .swiper-full-bg: Full background container.
  • .swiper-explain: Explain text container.
  • .active-thumb: Active slide of thumbs.

Quick experience(Use in browser)

<link href="swiper.min.css" rel="stylesheet">

<div id="basic" class="swiper swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide">slide1</div>
    ...
  </div>
</div>

<script src="swiper.min.js"></script>
<script src="awesome-swiper.umd.min.js"></script>
<script>
  new AwesomeSwiper().init('#basic');
</script>

or use standalone:

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

<script src="awesome-swiper.standalone.umd.min.js"></script>
<script>
  new AwesomeSwiper().init('#basic');
</script>

CDN

<script src="https://unpkg.com/npm/@cycjimmy/awesome-swiper@3/dist/awesome-swiper.umd.min.js"></script>

// standalone
<script src="https://unpkg.com/npm/@cycjimmy/awesome-swiper@3/dist/awesome-swiper.standalone.umd.min.js"></script>

Compatibility

  • chrome >= 49
  • safari >= 11
  • firefox >= 31
  • ios >= 11
  • android >= 7
  • Samsung >= 5

Note: IE is not supported. If you need to be compatible with IE, please return to awesome-swiper