Swiper React is available only via NPM as a part of the main Swiper library:
npm i swiper
swiper/react
exports 2 components: Swiper
and SwiperSlide
:
// Import Swiper React components
import { Swiper, SwiperSlide } from 'swiper/react';
// Import Swiper styles
import 'swiper/swiper.scss';
export default () => {
return (
<Swiper
spaceBetween={50}
slidesPerView={3}
onSlideChange={() => console.log('slide change')}
onSwiper={(swiper) => console.log(swiper)}
>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
<SwiperSlide>Slide 4</SwiperSlide>
...
</Swiper>
);
};
By default Swiper React uses core version of Swiper (without any additional components). If you want to use Navigation, Pagination and other components, you have to install them first.
Here is the list of additional modules imports:
Virtual
- Virtual Slides moduleKeyboard
- Keyboard Control moduleMousewheel
- Mousewheel Control moduleNavigation
- Navigation modulePagination
- Pagination moduleScrollbar
- Scrollbar moduleParallax
- Parallax moduleZoom
- Zoom moduleLazy
- Lazy moduleController
- Controller moduleA11y
- Accessibility moduleHistory
- History Navigation moduleHashNavigation
- Hash Navigation moduleAutoplay
- Autoplay moduleEffectFade
- Fade Effect moduleEffectCube
- Cube Effect moduleEffectFlip
- Flip Effect moduleEffectCoverflow
- Coverflow Effect moduleThumbs
- Thumbs module// import Swiper core and required components
import SwiperCore, { Navigation, Pagination, Scrollbar, A11y } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';
// Import Swiper styles
import 'swiper/swiper.scss';
import 'swiper/components/navigation/navigation.scss';
import 'swiper/components/pagination/pagination.scss';
import 'swiper/components/scrollbar/scrollbar.scss';
// install Swiper components
SwiperCore.use([Navigation, Pagination, Scrollbar, A11y]);
export default () => {
return (
<Swiper
spaceBetween={50}
slidesPerView={3}
navigation
pagination={{ clickable: true }}
scrollbar={{ draggable: true }}
onSwiper={(swiper) => console.log(swiper)}
onSlideChange={() => console.log('slide change')}
>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
<SwiperSlide>Slide 4</SwiperSlide>
...
</Swiper>
);
};
Note, Swiper React component will create required elements for Navigation, Pagination and Scrollbar if you pass these params without specifying its elements (e.g. without navigation.nextEl
, pagination.el
, etc.)
Swiper package contains different sets of CSS, Less and SCSS styles:
CSS styles for bundle version:
swiper-bundle.css
- all Swiper styles including all components styles (like Navigation, Pagination, etc.)swiper-bundle.min.css
- same as previous but minifiedCSS styles for core version and components:
swiper.min.css
- only core Swiper stylescomponents/a11y/a11y.min.css
- styles required for A11y componentcomponents/controller/controller.min.css
- styles required for A11y componentcomponents/effect-coverflow/effect-coverflow.min.css
- styles required for Coveflow Effect componentcomponents/effect-cube/effect-cube.min.css
- styles required for Cube Effect componentcomponents/effect-fade/effect-fade.min.css
- styles required for Fade Effect componentcomponents/effect-flip/effect-flip.min.css
- styles required for Flip Effect componentcomponents/lazy/lazy.min.css
- styles required for Lazy componentcomponents/navigation/navigation.min.css
- styles required for Navigation componentcomponents/pagination/pagination.min.css
- styles required for Pagination componentcomponents/scrollbar/scrollbar.min.css
- styles required for Scrollbar componentcomponents/thumbs/thumbs.min.css
- styles required for Thumbs componentcomponents/zoom/zoom.min.css
- styles required for Zoom componentLess styles are separate styles for core version and components:
swiper.less
- only core Swiper stylescomponents/a11y/a11y.less
- styles required for A11y componentcomponents/controller/controller.less
- styles required for Controller componentcomponents/effect-coverflow/effect-coverflow.less
- styles required for Coveflow Effect componentcomponents/effect-cube/effect-cube.less
- styles required for Cube Effect componentcomponents/effect-fade/effect-fade.less
- styles required for Fade Effect componentcomponents/effect-flip/effect-flip.less
- styles required for Flip Effect componentcomponents/lazy/lazy.less
- styles required for Lazy componentcomponents/navigation/navigation.less
- styles required for Navigation componentcomponents/pagination/pagination.less
- styles required for Pagination componentcomponents/scrollbar/scrollbar.less
- styles required for Scrollbar componentcomponents/thumbs/thumbs.less
- styles required for Thumbs componentcomponents/zoom/zoom.less
- styles required for Zoom componentSCSS styles are also separate styles for core version and components:
swiper.scss
- only core Swiper stylescomponents/a11y/a11y.scss
- styles required for A11y componentcomponents/controller/controller.scss
- styles required for Controller componentcomponents/effect-coverflow/effect-coverflow.scss
- styles required for Coveflow Effect componentcomponents/effect-cube/effect-cube.scss
- styles required for Cube Effect componentcomponents/effect-fade/effect-fade.scss
- styles required for Fade Effect componentcomponents/effect-flip/effect-flip.scss
- styles required for Flip Effect componentcomponents/lazy/lazy.scss
- styles required for Lazy componentcomponents/navigation/navigation.scss
- styles required for Navigation componentcomponents/pagination/pagination.scss
- styles required for Pagination componentcomponents/scrollbar/scrollbar.scss
- styles required for Scrollbar componentcomponents/thumbs/thumbs.scss
- styles required for Thumbs componentcomponents/zoom/zoom.scss
- styles required for Zoom componentSwiper
propsSwiper
React component receive all Swiper parameters as component props, plus some extra props:
Prop | Type | Default | Description |
---|---|---|---|
tag | string | 'div' | Main Swiper container HTML element tag |
wrapperTag | string | 'div' | Swiper wrapper HTML element tag |
onSwiper | (swiper) => void | Callback that receives Swiper instance |
Also it supports all Swiper events in on{Eventname}
format. For example slideChange
event becomes onSlideChange
prop:
<Swiper
onSlideChange={() => {/*...*/}}
onReachEnd={() => {/*...*/}}
...
>
SwiperSlide
propsProp | Type | Default | Description |
---|---|---|---|
tag | string | 'div' | Swiper Slide HTML element tag |
zoom | boolean | false | Enables additional wrapper required for zoom mode |
virtualIndex | number | Actual swiper slide index. Required to be set for virtual slides |
SwiperSlide
render functionSwiperSlide
component can accept render function that receives an object with the following properties:
isActive
- true when current slide is activeisPrev
- true when current slide is the previous from activeisNext
- true when current slide is the next from activeisVisible
- true when current slide is visible (watchSlidesVisibility
Swiper parameter must be enabled)isDuplicate
- true when current slide is a duplicate slide (when loop
mode enabled)For example:
<Swiper>
<SwiperSlide>
{({isActive}) => (
<div>Current slide is {isActive ? 'active' : 'not active'}</div>
)}
</SwiperSlide>
</Swiper>
Swiper React uses "slots" for content distribution. There are 4 slots available
container-start
- element will be added to the beginning of swiper-containercontainer-end
(default) - element will be added to the end of swiper-containerwrapper-start
- element will be added to the beginning of swiper-wrapperwrapper-end
- element will be added to the end of swiper-wrapperFor example:
<Swiper>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<span slot="container-start">Container Start</span>
<span slot="container-end">Container End</span>
<span slot="wrapper-start">Wrapper Start</span>
<span slot="wrapper-end">Wrapper End</span>
</Swiper>
Will be rendered as:
<div class="swiper-container">
<span slot="container-start">Container Start</span>
<div class="swiper-wrapper">
<span slot="wrapper-start">Wrapper Start</span>
<div class="swiper-slide">Slide 1</div>
<div class="swiper-slide">Slide 2</div>
<span slot="wrapper-end">Wrapper End</span>
</div>
<span slot="container-end">Container End</span>
</div>
Virtual Slides rendering here is fully handled by React and not required anything except setting virtual:true
property and setting virtualIndex
on slides:
import SwiperCore, { Virtual } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';
// install Virtual module
SwiperCore.use([Virtual]);
export default () => {
// Create array with 1000 slides
const slides = Array.from({ length: 1000 }).map((el, index) => `Slide ${index + 1}`);
return (
<Swiper spaceBetween={50} slidesPerView={3} virtual>
{slides.map((slideContent, index) => {
<SwiperSlide key={slideContent} virtualIndex={index}>{slideContent}</SwiperSlide>;
})}
</Swiper>
);
};
Controller requires to pass one Swiper instance to another:
import React, { useState } from 'react';
import SwiperCore, { Controller } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';
// install Swiper's Controller component
Swiper.use([Controller]);
const App = () => {
// store controlled swiper instance
const [controlledSwiper, setControlledSwiper] = useState(null);
return (
<main>
{/* Main Swiper -> pass controlled swiper instance */}
<Swiper controller={{ control: controlledSwiper }} ...>
{/* ... */}
</Swiper>
{/* Controlled Swiper -> store swiper instance */}
<Swiper onSwiper={setControlledSwiper} ...>
{/* ... */}
</Swiper>
</main>
)
}
For two-way control (when both Swipers control each other) it should be like this:
import React, { useState } from 'react';
import SwiperCore, { Controller } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';
// install Swiper's Controller component
Swiper.use([Controller]);
const App = () => {
// store swiper instances
const [firstSwiper, setFirstSwiper] = useState(null);
const [secondSwiper, setSecondSwiper] = useState(null);
return (
<main>
<Swiper onSwiper={setFirstSwiper} controller={{ control: secondSwiper }}>
{/* ... */}
</Swiper>
<Swiper onSwiper={setSecondSwiper} controller={{ control: firstSwiper }}>
{/* ... */}
</Swiper>
</main>
)
}
Same as with controller we need to store thumbs instance and pass it to main gallery:
import React, { useState } from 'react';
import SwiperCore, { Thumbs } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';
// install Swiper's Thumbs component
Swiper.use([Thumbs]);
const App = () => {
// store thumbs swiper instance
const [thumbsSwiper, setThumbsSwiper] = useState(null);
return (
<main>
{/* Main Swiper -> pass thumbs swiper instance */}
<Swiper thumbs={{ swiper: thumbsSwiper }} ...>
{/* ... */}
</Swiper>
{/* Thumbs Swiper -> store swiper instance */}
{/* It is also required to set watchSlidesVisibility and watchSlidesProgress props */ }
<Swiper
onSwiper={setThumbsSwiper}
watchSlidesVisibility
watchSlidesProgress
...
>
{/* ... */}
</Swiper>
</main>
)
}
The following effects are available:
To use effects you have to import and install them first (as all other modules) (Fade example):
import SwiperCore, {EffectFade} from 'swiper';
SwiperCore.use([EffectFade]);
You can find running effect demos here.
import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import SwiperCore, {EffectFade} from 'swiper';
import 'swiper/swiper.scss';
import 'swiper/components/effect-fade/effect-fade.scss';
SwiperCore.use([EffectFade]);
export default () => {
return (
<Swiper effect="fade">
{[1, 2, 3].map((i, el) => {
return <SwiperSlide>Slide {el}</SwiperSlide>;
})}
</Swiper>
);
};
For a more comprehensive hands-on tutorial have a look at this 15-min getting-started video