Swiper React コンポーネント

インストール

Swiper Reactは、メインのSwiperライブラリの一部として、NPM経由でのみ利用可能です。

  npm i swiper

使い方

swiper/reactは、2つのコンポーネントSwiperとSwiperSlideをエクスポートします。

// Import Swiper React components
import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/css';

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>
  );
};

swiper/modulesからの追加モジュールのインポートのリストを次に示します。

• Virtual - 仮想スライドモジュール
• Keyboard - キーボード制御モジュール
• Mousewheel - マウスホイール制御モジュール
• Navigation - ナビゲーションモジュール
• Pagination - ページネーションモジュール
• Scrollbar - スクロールバーモジュール
• Parallax - パララックスモジュール
• FreeMode - フリーモードモジュール
• Grid - グリッドモジュール
• Manipulation - スライド操作モジュール（コアバージョンのみ）
• Zoom - ズームモジュール
• Controller - コントローラーモジュール
• A11y - アクセシビリティモジュール
• History - 履歴ナビゲーションモジュール
• HashNavigation - ハッシュナビゲーションモジュール
• Autoplay - 自動再生モジュール
• EffectFade - フェードエフェクトモジュール
• EffectCube - キューブエフェクトモジュール
• EffectFlip - フリップエフェクトモジュール
• EffectCoverflow - カバフローエフェクトモジュール
• EffectCards - カードエフェクトモジュール
• EffectCreative - クリエイティブエフェクトモジュール
• Thumbs - サムズモジュール

// import Swiper core and required modules
import { Navigation, Pagination, Scrollbar, A11y } from 'swiper/modules';

import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/scrollbar';

export default () => {
  return (
    <Swiper
      // install Swiper modules
      modules={[Navigation, Pagination, Scrollbar, A11y]}
      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>
  );
};

スタイル

Swiperパッケージには、CSS、Less、SCSSスタイルの異なるセットが含まれています。

• swiper/css - コアSwiperスタイルのみ
• swiper/css/bundle - ナビゲーション、ページネーションなど、すべてのモジュールスタイルを含むすべてのSwiperスタイル

モジュールスタイル（バンドルスタイルをすでにインポートしている場合は不要）

• swiper/css/a11y - A11yモジュールに必要なスタイル
• swiper/css/autoplay - 自動再生モジュールに必要なスタイル
• swiper/css/controller - コントローラーモジュールに必要なスタイル
• swiper/css/effect-cards - カードエフェクトモジュールに必要なスタイル
• swiper/css/effect-coverflow - カバフローエフェクトモジュールに必要なスタイル
• swiper/css/effect-creative - クリエイティブエフェクトモジュールに必要なスタイル
• swiper/css/effect-cube - キューブエフェクトモジュールに必要なスタイル
• swiper/css/effect-fade - フェードエフェクトモジュールに必要なスタイル
• swiper/css/effect-flip - フリップエフェクトモジュールに必要なスタイル
• swiper/css/free-mode - フリーモードモジュールに必要なスタイル
• swiper/css/grid - グリッドモジュールに必要なスタイル
• swiper/css/hash-navigation - ハッシュナビゲーションモジュールに必要なスタイル
• swiper/css/history - 履歴モジュールに必要なスタイル
• swiper/css/keyboard - キーボードモジュールに必要なスタイル
• swiper/css/manipulation - 操作モジュールに必要なスタイル
• swiper/css/mousewheel - マウスホイールモジュールに必要なスタイル
• swiper/css/navigation - ナビゲーションモジュールに必要なスタイル
• swiper/css/pagination - ページネーションモジュールに必要なスタイル
• swiper/css/parallax - パララックスモジュールに必要なスタイル
• swiper/css/scrollbar - スクロールバーモジュールに必要なスタイル
• swiper/css/thumbs - サムズモジュールに必要なスタイル
• swiper/css/virtual - 仮想モジュールに必要なスタイル
• swiper/css/zoom - ズームモジュールに必要なスタイル

Lessスタイルについては、インポートパスでcssをlessに置き換えてください（例：）

import 'swiper/less';
import 'swiper/less/navigation';
import 'swiper/less/pagination';

SCSSスタイルについては、インポートパスでcssをscssに置き換えてください（例：）

import 'swiper/scss';
import 'swiper/scss/navigation';
import 'swiper/scss/pagination';

Swiperプロパティ

Swiper Reactコンポーネントは、すべてのSwiperパラメーターをコンポーネントのプロパティとして受け取ります。さらに、いくつかの追加プロパティも受け取ります。

また、on{イベント名}形式ですべてのSwiperイベントをサポートしています。たとえば、slideChangeイベントはonSlideChangeプロパティになります。

  <Swiper
    onSlideChange={() => {/*...*/}}
    onReachEnd={() => {/*...*/}}
    ...
  >

SwiperSlideプロパティ

SwiperSlideレンダリング関数

SwiperSlideコンポーネントは、次のプロパティを持つオブジェクトを受け取るレンダリング関数を受け入れることができます。

• isActive - 現在のスライドがアクティブな場合はtrue
• isPrev - 現在のスライドがアクティブなスライドの前にある場合はtrue
• isNext - 現在のスライドがアクティブなスライドの次にある場合はtrue
• isVisible - 現在のスライドが表示されている場合はtrue（watchSlidesProgress Swiperパラメーターを有効にする必要があります）
• isDuplicate - 現在のスライドが重複スライドの場合（loopモードが有効になっている場合）例：

<Swiper>
  <SwiperSlide>
    {({ isActive }) => (
      <div>Current slide is {isActive ? 'active' : 'not active'}</div>
    )}
  </SwiperSlide>
</Swiper>

useSwiper

Swiper Reactは、Swiper内のコンポーネントでSwiperインスタンスを簡単に取得するためのuseSwiperフックを提供します。

// some-inner-component.jsx
import { React } from 'react';
import { useSwiper } from 'swiper/react';

export default function SlideNextButton() {
  const swiper = useSwiper();

  return (
    <button onClick={() => swiper.slideNext()}>Slide to the next slide</button>
  );
}

useSwiperSlide

useSwiperSlideは、Swiperスライド内のコンポーネントがスライドデータ（SwiperSlideレンダリング関数と同じデータ）を取得するためのもう1つのフックです。

// some-inner-component.jsx
import { React } from 'react';
import { useSwiperSlide } from 'swiper/react';

export default function SlideTitle() {
  const swiperSlide = useSwiperSlide();

  return (
    <p>Current slide is {swiperSlide.isActive ? 'active' : 'not active'}</p>
  );
}

スロット

Swiper Reactは、コンテンツの配信に「スロット」を使用します。4つのスロットを利用できます。

• container-start - 要素はswiper-containerの先頭に追加されます
• container-end (デフォルト) - 要素はswiper-containerの末尾に追加されます
• wrapper-start - 要素はswiper-wrapperの先頭に追加されます
• wrapper-end - 要素はswiper-wrapperの末尾に追加されます

例:

<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>

次のようにレンダリングされます

<div class="swiper">
  <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>

仮想スライド

ここでの仮想スライドのレンダリングはReactによって完全に処理され、virtual:trueプロパティを設定し、スライドにvirtualIndexを設定すること以外は何も必要ありません。

import { Virtual } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/virtual';

export default () => {
  // Create array with 1000 slides
  const slides = Array.from({ length: 1000 }).map(
    (el, index) => `Slide ${index + 1}`
  );

  return (
    <Swiper modules={[Virtual]} spaceBetween={50} slidesPerView={3} virtual>
      {slides.map((slideContent, index) => (
        <SwiperSlide key={slideContent} virtualIndex={index}>
          {slideContent}
        </SwiperSlide>
      ))}
    </Swiper>
  );
};

コントローラー

コントローラーでは、あるSwiperインスタンスを別のSwiperインスタンスに渡す必要があります。

  import React, { useState } from 'react';
  import { Controller } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/react';

  const App = () => {
    // store controlled swiper instance
    const [controlledSwiper, setControlledSwiper] = useState(null);

    return (
      <main>
        {/* Main Swiper -> pass controlled swiper instance */}
        <Swiper modules={[Controller]} controller={{ control: controlledSwiper }} ...>
          {/* ... */}
        </Swiper>

        {/* Controlled Swiper -> store swiper instance */}
        <Swiper modules={[Controller]} onSwiper={setControlledSwiper} ...>
          {/* ... */}
        </Swiper>
      </main>
    )
  }

双方向制御（両方のSwiperが互いに制御する場合）では、次のようになります。

import React, { useState } from 'react';
import { Controller } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

const App = () => {
  // store swiper instances
  const [firstSwiper, setFirstSwiper] = useState(null);
  const [secondSwiper, setSecondSwiper] = useState(null);

  return (
    <main>
      <Swiper
        modules={[Controller]}
        onSwiper={setFirstSwiper}
        controller={{ control: secondSwiper }}
      >
        {/* ... */}
      </Swiper>

      <Swiper
        modules={[Controller]}
        onSwiper={setSecondSwiper}
        controller={{ control: firstSwiper }}
      >
        {/* ... */}
      </Swiper>
    </main>
  );
};

サムズ

コントローラーと同じように、サムズインスタンスを保存し、メインギャラリーに渡す必要があります。

  import React, { useState } from 'react';
  import { Swiper, SwiperSlide } from 'swiper/react';
  import { Thumbs } from 'swiper/modules';

  const App = () => {
    // store thumbs swiper instance
    const [thumbsSwiper, setThumbsSwiper] = useState(null);

    return (
      <main>
        {/* Main Swiper -> pass thumbs swiper instance */}
        <Swiper modules={[Thumbs]} thumbs={{ swiper: thumbsSwiper }} ...>
          {/* ... */}
        </Swiper>

        {/* Thumbs Swiper -> store swiper instance */}
        {/* It is also required to set watchSlidesProgress prop */ }
        <Swiper
          modules={[Thumbs]}
          watchSlidesProgress
          onSwiper={setThumbsSwiper}
          ...
        >
          {/* ... */}
        </Swiper>
      </main>
    )
  }

エフェクト

次のエフェクトが利用可能です。

• フェード
• キューブ
• カバフロー
• フリップ
• カード
• クリエイティブ

エフェクトを使用するには、最初に（他のすべてのモジュールと同様に）インポートしてインストールする必要があります。

ここで実行中のエフェクトデモを見つけることができます。

完全なフェードエフェクトの例

import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { EffectFade } from 'swiper/modules';

import 'swiper/css';
import 'swiper/css/effect-fade';

export default () => {
  return (
    <Swiper modules={[EffectFade]} effect="fade">
      {[1, 2, 3].map((i, el) => {
        return <SwiperSlide>Slide {el}</SwiperSlide>;
      })}
    </Swiper>
  );
};

Create React Appでの使用

Create React Appはまだ純粋なESMパッケージをサポートしていません。それでも、Swiper (7.2.0+) を使用することは可能です。

この場合、直接ファイルインポートを使用する必要があります。

// Core modules imports are same as usual
import { Navigation, Pagination } from 'swiper/modules';
// Direct React component imports
import { Swiper, SwiperSlide } from 'swiper/swiper-react.mjs';

// Styles must use direct files imports
import 'swiper/swiper.scss'; // core Swiper
import 'swiper/modules/navigation.scss'; // Navigation module
import 'swiper/modules/pagination.scss'; // Pagination module

次は何をすればいいですか？

ご覧のとおり、SwiperをWebサイトやアプリに統合するのは非常に簡単です。次に、次の手順を実行します。

• APIドキュメントに移動して、すべてのSwiper APIとそれを制御する方法について詳細を確認してください。
• 利用可能なデモを見てください。
• Swiperについて質問がある場合は、StackOverflowまたはSwiper Discussionsで質問してください。
• バグを見つけた場合は、GitHubで問題を作成してください。
• サポートをお探しの場合は、Swiperパトロン向けのプライベートDiscordサポートチャットルームがあります。