Awesome Swiper
- awesome-swiper has been renamed to @cycjimmy/awesome-swiper for scoped NPM package.
- awesome-swiper based on swiper 14. (Releases | Demo)
Install
# via npm
$ npm install @cycjimmy/awesome-swiper --save
# or via yarn
$ yarn add @cycjimmy/awesome-swiper
swiper is a peer dependency (^14), so npm 7+ installs it for you; install it
explicitly if your package manager does not install peers.
Module format
The package is ESM only:
| File | Format | Purpose |
|---|---|---|
dist/awesome-swiper.esm.js |
ESM | main, module and exports entry (bundlers, import) |
dist/awesome-swiper.umd.js |
UMD | unminified browser build for <script> tags, expects the Swiper global |
dist/awesome-swiper.umd.min.js |
UMD | minified browser/CDN build, expects the Swiper global |
dist/awesome-swiper.standalone.umd.min.js |
UMD | minified build with swiper and its stylesheet bundled in |
dist/index.d.ts |
Types | TypeScript declarations for types and the exports types condition |
- There is no CommonJS bundle. Node.js 22.12+ / 24 can
require()the ESM entry, because those versions load an ES module synchronously. - The stylesheet is not shipped as a separate
.cssfile: the CSS Modules output is inlined into the entry chunk and injected as a<style>element while the module is evaluated, so a plain<script>tag needs nothing else. See theinjectCssplugin invite.config.ts. swiper/bundleis the constructor used by default, so navigation, pagination, mousewheel and autoplay work out of the box. Bring your own constructor withnew AwesomeSwiper(SwiperModule)if you prefer the swiper core entry.- The toolchain itself needs Node.js
^22.22.2 || ^24.15.0 || >=26.0.0(seeenginesinpackage.jsonand CONTRIBUTING.md).
Usage
Awesome Swiper based on Swiper 14. Add Swiper of the same major version to your project first
import AwesomeSwiper from '@cycjimmy/awesome-swiper'
// Only needed when you want the swiper styles:
import 'swiper/css/bundle'
const awesomeSwiper = new AwesomeSwiper().init(context)
// if need thumbs
const awesomeSwiperWithThumbs = new AwesomeSwiper()
.init(context)
.addThumbs(thumbsContext)
init() and addThumbs() both accept optional config objects: init(context, config, overlayConfig) and addThumbs(thumbsContext, thumbsConfig, thumbsExtraConfig).
new AwesomeSwiper([SwiperModule]): Create new instance
- Params:
SwiperModule: [Object] Set custom swiper constructor. Defaults toswiper/bundle, which already installs the modules this wrapper configures. Any swiper 14+ constructor works.
- Return
awesomeSwiperinstance
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. A selector that matches nothing throws.- config: [Object]
speed: [Number] Duration of transition between slides (in ms). Default300.loop: [Boolean] Set totrueto enable loop. Defaultfalse. Swiper 14 needs enough slides for the loop to work (at leastslidesPerView + slidesPerGroup, plus one more whencenteredSlidesis on).autoplay: [Number] Set autoplay delay.0means close. Default0.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. Default0.slidesPerView: [Number | 'auto'] Number of slides per view. Default1.mousewheel: [Boolean] Set totrueto enable navigation through slides using mouse wheel. Defaultfalse.autoFixFullImg: [Boolean] Settrueto auto fix full images. Defaultfalse. Tip: Due to the impact of performance, not necessary not to set it.autoHeight: [Boolean] Set totrueand slider wrapper will adapt its height to the height of the currently active slide. Defaultfalse.pagination: [Object] Set pagination. If you do not want a pagination, setnull.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. Defaultfalse.
navigation: [Object] Set navigation. If you do not want a navigation, setnull.color: [String] Set color for navigation with a color name or a hex value. Default''is blue.size: [String | Number] Set size for navigation. A number is read as pixels.styles: [Object] Custom styleprev: [Object] Custom style for prevEl.next: [Object] Custom style for nextEl.
custom: [Object] Set custom navigation elements. Defaultnull. BothprevElandnextElare required.prevEl: [String | Element] Custom prev button element.nextEl: [String | Element] Custom next button element.
- overlayConfig: [Object] Use Custom swiper api to overlay config.
- Return
awesomeSwiperinstance
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. Default10.slidesPerView: [Number | 'auto'] Number of slides per view. Default'auto'.
- thumbsExtraConfig: [Object] Extra config for thumbs.
mouseOverMode: [Boolean] settrueto use mouse over mode. Defaultfalse.autoFixFullImg: [Boolean] Settrueto auto fix full images. Defaultfalse. Tip: Due to the impact of performance, not necessary not to set it.
- Return
awesomeSwiperinstance
setInitialSlide(initialSlide): Set index number of initial slide.
- Params:
initialSlide: [Number] Index number of initial slide.
- Return
awesomeSwiperinstance
on(event, handler): Add event handler
- Same as
swiper.on(event, handler) - Return
awesomeSwiperinstance
off(event, handler): Remove event handler
- Same as
swiper.off(event, handler) - Return
awesomeSwiperinstance
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="https://unpkg.com/swiper@14/swiper-bundle.min.css" rel="stylesheet">
<div id="basic" class="swiper">
<div class="swiper-wrapper">
<div class="swiper-slide">slide1</div>
...
</div>
</div>
<script src="https://unpkg.com/swiper@14/swiper-bundle.min.js"></script>
<script src="awesome-swiper.umd.min.js"></script>
<script>
new AwesomeSwiper().init('#basic');
</script>
or use standalone, which carries swiper and its styles:
<div id="basic" class="swiper">
...
</div>
<script src="awesome-swiper.standalone.umd.min.js"></script>
<script>
new AwesomeSwiper().init('#basic');
</script>
CDN
<script src="https://unpkg.com/@cycjimmy/awesome-swiper@4/dist/awesome-swiper.umd.min.js"></script>
<!-- standalone -->
<script src="https://unpkg.com/@cycjimmy/awesome-swiper@4/dist/awesome-swiper.standalone.umd.min.js"></script>
Migration from v3
- The CommonJS bundle (
dist/awesome-swiper.cjs) is gone. Bundlers and Node 22+ usedist/awesome-swiper.esm.js; there is nothing to configure forimport. swipermoved from a dependency to a peer dependency and is now^14. Themodule,navigation,pagination,mousewheelandautoplayparameters come fromswiper/bundle, which the default constructor already uses.swiper9 renamed.swiper-containerto.swiper; the markup in the docs and the demo now usesclass="swiper"only. The wrapper styles target the swiper 14 class names (.swiper-vertical,.swiper-pagination-bullet, ...).navigation.sizestyles the SVG arrows of swiper 14 instead of the old font icon.init()now throws when a selector matches nothing, instead of failing later with aTypeError, andnavigation.customrequires bothprevElandnextEl.setInitialSlide()uses the loop aware transition, so it also works withloop: true.
Compatibility
- Builds target ES2020 (
chrome >= 87,safari >= 14,firefox >= 78) and the browser baseline of swiper 14. - IE is not supported. Use awesome-swiper v2 if you need it.
See CONTRIBUTING.md for the development, test and release workflow.