DEV Community

Patrick Moore
Patrick Moore

Posted on

Getting Started with Swiper: Building Image Carousels in React

#react #webdev #tutorial #beginners

Swiper is a modern, touch-enabled slider and carousel library for React applications. It provides smooth animations, touch gestures, navigation controls, and extensive customization options for creating professional image galleries and content sliders. This guide walks through setting up and creating carousels using Swiper with React, from installation to a working implementation.

Prerequisites

Before you begin, make sure you have:

  • Node.js version 14.0 or higher installed
  • npm, yarn, or pnpm package manager
  • A React project (version 16.8 or higher) or create-react-app setup
  • Basic knowledge of React components
  • Familiarity with JavaScript/TypeScript

Installation

Install Swiper using your preferred package manager:

npm install swiper
Enter fullscreen mode Exit fullscreen mode

Or with yarn:

yarn add swiper
Enter fullscreen mode Exit fullscreen mode

Or with pnpm:

pnpm add swiper
Enter fullscreen mode Exit fullscreen mode

After installation, your package.json should include:

{
  "dependencies": {
    "swiper": "^11.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Project Setup

Import the CSS file in your main entry file:

// src/index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import 'swiper/css';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
Enter fullscreen mode Exit fullscreen mode

First Example / Basic Usage

Let's create a simple image carousel. Create a new file src/SwiperExample.jsx:

// src/SwiperExample.jsx
import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import 'swiper/css';

function SwiperExample() {
  const images = [
    'https://via.placeholder.com/800x400/007bff/ffffff?text=Slide+1',
    'https://via.placeholder.com/800x400/28a745/ffffff?text=Slide+2',
    'https://via.placeholder.com/800x400/ffc107/000000?text=Slide+3',
    'https://via.placeholder.com/800x400/dc3545/ffffff?text=Slide+4'
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '800px', margin: '0 auto' }}>
      <h2>Basic Swiper Example</h2>
      <Swiper
        spaceBetween={50}
        slidesPerView={1}
        onSlideChange={() => console.log('slide change')}
        onSwiper={(swiper) => console.log(swiper)}
      >
        {images.map((image, index) => (
          <SwiperSlide key={index}>
            <img
              src={image}
              alt={`Slide ${index + 1}`}
              style={{ width: '100%', height: '400px', objectFit: 'cover' }}
            />
          </SwiperSlide>
        ))}
      </Swiper>
    </div>
  );
}

export default SwiperExample;
Enter fullscreen mode Exit fullscreen mode

Update your App.jsx:

// src/App.jsx
import React from 'react';
import SwiperExample from './SwiperExample';
import './App.css';

function App() {
  return (
    <div className="App">
      <SwiperExample />
    </div>
  );
}

export default App;
Enter fullscreen mode Exit fullscreen mode

This creates a basic carousel with touch support and navigation.

Understanding the Basics

Swiper provides React components:

  • Swiper: Main slider container component
  • SwiperSlide: Individual slide component
  • Modules: Navigation, Pagination, Scrollbar, etc.
  • CSS imports: Import styles for modules you use
  • Touch support: Built-in swipe gestures
  • Responsive: Automatic responsive behavior

Key concepts:

  • Components: Use Swiper and SwiperSlide components
  • Props: Configure behavior through props
  • Modules: Import and use modules for additional features
  • Styling: Import CSS for each module you use
  • Event handlers: Use onSlideChange, onSwiper callbacks

Here's an example with navigation and pagination:

// src/AdvancedSwiperExample.jsx
import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Navigation, Pagination } from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';

function AdvancedSwiperExample() {
  const images = [
    'https://via.placeholder.com/800x400/007bff/ffffff?text=Slide+1',
    'https://via.placeholder.com/800x400/28a745/ffffff?text=Slide+2',
    'https://via.placeholder.com/800x400/ffc107/000000?text=Slide+3',
    'https://via.placeholder.com/800x400/dc3545/ffffff?text=Slide+4'
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '800px', margin: '0 auto' }}>
      <h2>Advanced Swiper with Navigation</h2>
      <Swiper
        modules={[Navigation, Pagination]}
        spaceBetween={50}
        slidesPerView={1}
        navigation
        pagination={{ clickable: true }}
        onSlideChange={() => console.log('slide change')}
      >
        {images.map((image, index) => (
          <SwiperSlide key={index}>
            <img
              src={image}
              alt={`Slide ${index + 1}`}
              style={{ width: '100%', height: '400px', objectFit: 'cover' }}
            />
          </SwiperSlide>
        ))}
      </Swiper>
    </div>
  );
}

export default AdvancedSwiperExample;
Enter fullscreen mode Exit fullscreen mode

Practical Example / Building Something Real

Let's build a comprehensive image gallery with navigation and thumbnails:

// src/ImageGallerySwiper.jsx
import React, { useState } from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Navigation, Pagination, Thumbs } from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/thumbs';

function ImageGallerySwiper() {
  const [thumbsSwiper, setThumbsSwiper] = useState(null);

  const images = [
    {
      full: 'https://via.placeholder.com/1200x800/007bff/ffffff?text=Image+1',
      thumb: 'https://via.placeholder.com/150x100/007bff/ffffff?text=1',
      title: 'Image 1'
    },
    {
      full: 'https://via.placeholder.com/1200x800/28a745/ffffff?text=Image+2',
      thumb: 'https://via.placeholder.com/150x100/28a745/ffffff?text=2',
      title: 'Image 2'
    },
    {
      full: 'https://via.placeholder.com/1200x800/ffc107/000000?text=Image+3',
      thumb: 'https://via.placeholder.com/150x100/ffc107/000000?text=3',
      title: 'Image 3'
    },
    {
      full: 'https://via.placeholder.com/1200x800/dc3545/ffffff?text=Image+4',
      thumb: 'https://via.placeholder.com/150x100/dc3545/ffffff?text=4',
      title: 'Image 4'
    },
    {
      full: 'https://via.placeholder.com/1200x800/6c757d/ffffff?text=Image+5',
      thumb: 'https://via.placeholder.com/150x100/6c757d/ffffff?text=5',
      title: 'Image 5'
    }
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '1000px', margin: '0 auto' }}>
      <h1>Image Gallery with Swiper</h1>
      <div style={{ marginBottom: '20px' }}>
        <Swiper
          modules={[Navigation, Pagination, Thumbs]}
          spaceBetween={10}
          navigation
          pagination={{ clickable: true }}
          thumbs={{ swiper: thumbsSwiper && !thumbsSwiper.destroyed ? thumbsSwiper : null }}
        >
          {images.map((image, index) => (
            <SwiperSlide key={index}>
              <img
                src={image.full}
                alt={image.title}
                style={{
                  width: '100%',
                  height: '600px',
                  objectFit: 'cover',
                  borderRadius: '8px'
                }}
              />
            </SwiperSlide>
          ))}
        </Swiper>
      </div>
      <Swiper
        onSwiper={setThumbsSwiper}
        modules={[Thumbs]}
        spaceBetween={10}
        slidesPerView={4}
        freeMode={true}
        watchSlidesProgress={true}
      >
        {images.map((image, index) => (
          <SwiperSlide key={index}>
            <img
              src={image.thumb}
              alt={`Thumbnail ${index}`}
              style={{
                width: '100%',
                height: '100px',
                objectFit: 'cover',
                borderRadius: '4px',
                cursor: 'pointer'
              }}
            />
          </SwiperSlide>
        ))}
      </Swiper>
    </div>
  );
}

export default ImageGallerySwiper;
Enter fullscreen mode Exit fullscreen mode

Now create a product carousel:

// src/ProductCarouselSwiper.jsx
import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Navigation } from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';

function ProductCarouselSwiper() {
  const products = [
    { id: 1, name: 'Product 1', price: '$99', image: 'https://via.placeholder.com/300x300/007bff/ffffff?text=Product+1' },
    { id: 2, name: 'Product 2', price: '$149', image: 'https://via.placeholder.com/300x300/28a745/ffffff?text=Product+2' },
    { id: 3, name: 'Product 3', price: '$199', image: 'https://via.placeholder.com/300x300/ffc107/000000?text=Product+3' },
    { id: 4, name: 'Product 4', price: '$249', image: 'https://via.placeholder.com/300x300/dc3545/ffffff?text=Product+4' },
    { id: 5, name: 'Product 5', price: '$299', image: 'https://via.placeholder.com/300x300/6c757d/ffffff?text=Product+5' }
  ];

  return (
    <div style={{ padding: '20px', maxWidth: '1200px', margin: '0 auto' }}>
      <h2>Product Carousel</h2>
      <Swiper
        modules={[Navigation]}
        spaceBetween={20}
        slidesPerView={1}
        navigation
        breakpoints={{
          640: {
            slidesPerView: 2,
            spaceBetween: 20
          },
          768: {
            slidesPerView: 3,
            spaceBetween: 30
          },
          1024: {
            slidesPerView: 4,
            spaceBetween: 40
          }
        }}
      >
        {products.map((product) => (
          <SwiperSlide key={product.id}>
            <div style={{
              padding: '15px',
              textAlign: 'center',
              backgroundColor: '#f8f9fa',
              borderRadius: '8px',
              height: '100%'
            }}>
              <img
                src={product.image}
                alt={product.name}
                style={{
                  width: '100%',
                  height: '250px',
                  objectFit: 'cover',
                  borderRadius: '4px',
                  marginBottom: '10px'
                }}
              />
              <h3 style={{ margin: '0 0 5px 0' }}>{product.name}</h3>
              <p style={{ margin: 0, fontWeight: 'bold', color: '#007bff' }}>{product.price}</p>
            </div>
          </SwiperSlide>
        ))}
      </Swiper>
    </div>
  );
}

export default ProductCarouselSwiper;
Enter fullscreen mode Exit fullscreen mode

Update your App.jsx:

// src/App.jsx
import React from 'react';
import ImageGallerySwiper from './ImageGallerySwiper';
import ProductCarouselSwiper from './ProductCarouselSwiper';
import './App.css';

function App() {
  return (
    <div className="App">
      <ImageGallerySwiper />
      <ProductCarouselSwiper />
    </div>
  );
}

export default App;
Enter fullscreen mode Exit fullscreen mode

This example demonstrates:

  • Image gallery with thumbnail navigation
  • Product carousel with responsive breakpoints
  • Navigation and pagination
  • Touch/swipe gestures
  • Custom styling

Common Issues / Troubleshooting

  1. Swiper not displaying: Make sure you've imported the CSS file (import 'swiper/css'). The Swiper requires styles to render correctly.

  2. Navigation not showing: Import the Navigation module and its CSS. Add modules={[Navigation]} and navigation prop to enable navigation arrows.

  3. Pagination not working: Import the Pagination module and its CSS. Add modules={[Pagination]} and pagination={{ clickable: true }} prop.

  4. Thumbnails not syncing: For thumbnail galleries, use the Thumbs module. Set thumbs={{ swiper: thumbsSwiper }} on the main swiper and use onSwiper={setThumbsSwiper} on the thumbnail swiper.

  5. Responsive not working: Use the breakpoints prop with an object. Each breakpoint key should be a media query string (e.g., '640' for 640px).

  6. Modules not working: Make sure you're importing modules from 'swiper/modules' and passing them to the modules prop as an array.

Next Steps

Now that you have a basic understanding of Swiper:

  • Learn about all available modules (Autoplay, Effect, etc.)
  • Explore advanced configuration options
  • Implement lazy loading for images
  • Add custom animations and effects
  • Create vertical sliders
  • Learn about other slider libraries (react-slick, keen-slider)
  • Check the official documentation: https://swiperjs.com/react

Summary

You've successfully set up Swiper in your React application and created image galleries and product carousels with navigation, pagination, and responsive breakpoints. Swiper provides a powerful, feature-rich solution for creating professional sliders with excellent touch support.

SEO Keywords

swiper
React Swiper
swiper tutorial
React carousel component
swiper installation
React image slider
swiper example
React touch slider
swiper setup
React slider library
swiper customization
React Swiper modules
swiper navigation
React carousel slider
swiper getting started

Top comments (0)