Zenn
😎

【Vue3】Vue3-carouselの使い方を解説

2025/03/05に公開
Vue.js
Vue 3
tech

はじめに

今回の記事では、Vue3-carousel という Vue3 のコンポーネントの使い方を解説します。
Vue3/Nuxt3 の環境でカルーセルを実装する場合には非常に便利です。

インストール

npm install vue3-carousel

サンプルコード

<script setup>
import "vue3-carousel/carousel.css";
import { Carousel, Slide, Pagination, Navigation } from "vue3-carousel";

const carouselConfig = {
  itemsToShow: 1,
  wrapAround: true,
};
</script>

<template>
  <Carousel v-bind="carouselConfig">
    <Slide v-for="slide in 10" :key="slide">
      <div>
        <!-- コンテンツが入ります -->
      </div>
    </Slide>
    <template #addons>
      <Navigation />
      <Pagination />
    </template>
  </Carousel>
</template>

template 内で<Carousel>を呼び出しましょう。その際、v-bind でカルーセルの config をまとめて渡すことができます。<Slide>に v-for でスライドの枚数 と key 属性を設定したら OK です。
また、必要に応じてナビゲーション・ページネーションを用意することもできます。実装方法は簡単で、<Slide>と同じ階層に <template #addons>を記述し、その中に<Navigation />``<Pagination />をそれぞれ書いてあげるだけです。

Config

他のカルーセルライブラリ同様にオプションが用意されています。よく使うものをまとめておきます。

Prop 型 初期値 説明
autoplay number 0 自動再生の間隔 (ミリ秒単位)。自動再生を無効にするには 0 に設定します
breakpoints object null ブレークポイントの指定ができます
itemsToScroll number 1 1 度にスライドする枚数が指定できます
itemsToShow number,'auto' 1 同時に表示されるスライドの数。可変幅の場合は'auto'が適用されます
mouseDrag boolean true マウスによるドラッグを有効にするか設定できます
wrapAround boolean false true の場合、カルーセルが無限ループになります

スタイリング

Slide - スライド

コンポーネント側がスタイル設定用に提供している CSS のクラス一覧です。

CSS クラス 説明
.carousel__slide 全てのスライド
.carousel__slide--active アクティヴなスライド
.carousel__slide--clone 複製されたスライド
.carousel__slide--next 次のスライド
.carousel__slide--prev 前のスライド
.carousel__slide--sliding トランジション中のスライド
.carousel__slide--visible 表示されるスライド

Navigation - ナビゲーション

ナビゲーションのスタイルを制御するには二つ方法があります。CSS カスタムプロパティを利用するか、セレクタを指定してスタイルを上書きするかです。

カスタムプロパティ

変数 初期値 説明
--vc-nav-background transparent ナビゲーションボタンの背景
--vc-nav-border-radius 0 ナビゲーションボタンの角丸
--vc-nav-color var(--vc-clr-primary) ナビゲーションボタンの色
--vc-nav-color-hover var(--vc-clr-secondary) ナビゲーションボタンのホバー時の色
--vc-nav-height 30px ナビゲーションボタンの高さ
--vc-nav-width 30px ナビゲーションボタンの幅

セレクタ

CSS クラス 説明
.carousel__next 次のスライドへ進むボタン
.carousel__prev 前のスライドへ戻るボタン
.carousel__next--disabled 利用不可の次のスライドへ進むボタン
.carousel__prev--disabled 利用不可の前のスライドへ戻るボタン
.carousel__icon ボタン内の矢印アイコン

Pagination - ページネーション

ナビゲーション同様に、カスタムプロパティかセレクタ指定のいずれかでスタイルを設定できます。

カスタムプロパティ

変数 初期値 説明
--vc-pgn-active-color var(--vc-clr-primary) アクティブなページネーションボタンの色
--vc-pgn-background-color var(--vc-clr-secondary) ページネーションボタンの背景色
--vc-pgn-border-radius 0 ページネーションボタンの角丸
--vc-pgn-gap 6px ページネーションボタン間の隙間
--vc-pgn-height 4px ページネーションボタンの高さ
--vc-png-bottom 10px ページネーションの下部余白
--vc-png-left auto 左の間隔（垂直モード）
--vc-png-right 10px 右の間隔（垂直モード）
--vc-png-width 16px ページネーションボタンの幅

セレクタ

CSS クラス 説明
.carousel__pagination ページネーション全体(ol)
.carousel__pagination-item ページネーションのアイテム(li)
.carousel__pagination-button ページネーションボタン
.carousel__pagination-button--active アクティヴなページネーションボタン

応用その 1: ページネーションを数字カウントに置き換える

<Pagination>で呼び出されるものはデフォルトだとドットスタイルのものですが、それを数字形式に置き換えることができます。コンポーネントが用意されている訳ではないのですが、実装はそこまで手間ではありません。

<script lang="ts" setup>
const currentSlide = ref<number>(0);
</script>

<template>
  <Carousel v-model="currentSlide" v-bind="config">
    <Slide v-for="slide in data" :key="slide.id">
      <div>
        <!-- コンテンツが入ります -->
      </div>
    </Slide>
    <template #addons>
      <Navigation />
      <!-- <Pagination /> -->
    </template>
  </Carousel>
  <p>
    {{ currentSlide + 1 }} /
    {{ data.length }}
  </p>
</template>

script 内で定数currentSlideを用意し、<Carousel>を呼び出す際に v-model="currentSlide"を記述しておきます。<Carousel>外でマスタッシュ構文currentSlide + 1を展開してあげることで、現在のスライドの数字が表示されます。必要に応じてdata.lengthでスライドの総数も加えてあげると、よりユーザーフレンドリーなカルーセルになりますね。

応用その 2: スライドの枚数が一定以下だった場合、ナビゲーションを非表示にする

スライドの枚数を算出し、設定した数に満たない場合はナビゲーションを非表示にします。

<script setup>
import { Carousel, Slide, Pagination, Navigation } from "vue3-carousel";
import "vue3-carousel/dist/carousel.css";

const slideLimit = 4;
</script>
<template>
  <Carousel v-bind="config">
    <Slide v-for="(slide, index) in data" :key="page.name">
      <!-- コンテンツが入ります -->
    </Slide>
    <template #addons="{ slidesCount }">
      <Navigation v-if="slidesCount > slideLimit" />
    </template>
  </Carousel>
</template>

Vue3-carousel のデータ値として用意されているslidesCountを利用します。<Navigation>を呼び出す際に、v-if で出力条件に組み込んであげましょう。今回の例では、スライド総数(slidesCount)が 4 枚以下ならナビゲーションは出力されない、といった具合になっています。

まとめ

今回の記事では、Vue3-carousel の使い方を解説しました。
実装も簡単ですし、オプションやデータ値なども活用すると色々カスタマイズもできるので、かなり有用なコンポーネントだと思います。

参考

https://vue3-carousel.ismail9k.com/

Discussion