Swiper 12でできなくなったこと・変更された仕様まとめ

はじめに

Swiper 12では、大きな破壊的変更(Breaking Changes)がいくつか入っています。主に「プリプロセッサ(SCSS/Less)の廃止」「ナビゲーションアイコンのSVG化」「Virtual Slidesの仕様拡張」の3点が中心です。移行時にハマりやすいポイントを中心に整理しました。

1. SCSS / Lessファイルの提供が廃止

Swiperパッケージから .scss / .less のソースファイルが同梱されなくなりました。以降はビルド済みの標準CSSのみが提供され、CSSカスタムプロパティ(CSS変数)でテーマをカスタマイズする方式に一本化されています。

影響を受けるコード

// v12ではこれらのimportが使えなくなる
@import 'swiper/scss';
@import 'swiper/scss/navigation';
@import 'swiper/scss/pagination';

移行方法

// 標準CSSのimportに置き換える
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';

テーマのカスタマイズは、SCSSの変数やmixinではなく、CSSカスタムプロパティで行う。

:root {
  --swiper-theme-color: #111;
  --swiper-navigation-size: 20px;
  --swiper-pagination-color: #111;
}

• 自前のビルドでSCSS/Lessを使うこと自体は引き続き可能。ただし、Swiper配布のCSSは「最終成果物」として外部ライブラリのCSSと同様に扱う必要がある(SCSSのソースとしては使えない)。
• SCSSのmixinやmapに依存したテーマ設定をしていた場合は、自分のビルドステップ側に移す必要がある。

2. ナビゲーションのアイコンがフォントアイコンからSVGアイコンに変更

これまでnavigationボタン(swiper-button-prev / swiper-button-next)はフォントアイコンで描画されていましたが、v12からはデフォルトでSVGアイコンが挿入されるようになりました。

影響

• 独自のフォントアイコンの読み込み処理に依存していた場合、そのコードは不要(むしろ削除対象)になる。
• 見た目や色・サイズの指定方法が変わる。

新しいカスタマイズ方法

/* サイズ・色をCSS変数で指定 */
:root {
  --swiper-navigation-color: #0f172a;
  --swiper-navigation-size: 26px;
}

/* もしくはセレクタで直接指定 */
.swiper-button-next svg,
.swiper-button-prev svg {
  width: 26px;
  height: 26px;
  fill: #0f172a;
}

完全に独自のアイコンを使いたい場合は、要素の中に直接SVGを差し込むことでデフォルトのアイコン挿入を回避できる。

<div class="swiper-button-prev">
  <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M15 6l-6 6 6 6" /></svg>
</div>
<div class="swiper-button-next">
  <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M9 6l6 6-6 6" /></svg>
</div>

• 副次的なメリットとして、厳格なCSPを敷いている場合に問題になりやすかった「フォントのインラインstyle/CSP false positive」の問題が解消されている。

3. Virtual Slides + slidesPerView: 'auto' の扱いが変更

これまでVirtual Slidesモードと slidesPerView: 'auto' の組み合わせは、実際のDOMサイズを計測できない都合上、うまく共存できませんでした。v12では部分的な互換レイヤーとして virtual.slidesPerViewAutoSlideSize オプションが追加されています。

const swiper = new Swiper('.swiper', {
  slidesPerView: 'auto',
  spaceBetween: 12,
  virtual: {
    enabled: true,
    slides: Array.from({ length: 10000 }, (_, i) => `Slide #${i + 1}`),
    slidesPerViewAutoSlideSize: 320, // px単位でスライド幅を仮定
  },
});

• あくまで「実用上の折衷案」であり、各スライドの幅がほぼ揃っている場合にうまく機能する。
• スライドごとの幅の差が大きい場合は、幅を固定するか、Virtualモードを使わない方法を検討したほうがよい、と公式でも案内されている。

その他の補足

• 上記以外のオプション・デフォルト値・イベント・メソッドのシグネチャ・モジュールのimport方法(swiper/modules, swiper/react, swiper/vue, swiper/element など)には変更がなく、コードの書き換えは基本的に不要。
• 影響が出るのは主に CSSの読み込み方法 と ナビゲーションアイコンの見た目・カスタマイズ方法、Virtual Slides + auto幅の組み合わせ の3点。

参考

• Swiper公式ブログ: Swiper v12 (https://swiperjs.com/blog/swiper-v12)
• Swiper公式Changelog (https://swiperjs.com/changelog)

JISOUのメンバー募集中！

プログラミングコーチングJISOUでは、新たなメンバーを募集しています。
日本一のアウトプットコミュニティでキャリアアップしませんか？
興味のある方は、ぜひホームページをのぞいてみてください！