Overview

Use the <Swiper> component to display image carousels on pages.

Usage

To use this component, first manually install the swiper library:

pnpm

pnpm add swiper

yarn

yarn add swiper

npm

npm install swiper

Then, manually import the Swiper component:

<!-- Import in markdown -->
<script setup>
import Swiper from 'vuepress-theme-plume/features/Swiper.vue'
</script>

<!-- After importing, you can use it in markdown -->
<Swiper :items="['img_link1', 'img_link2']" />

Register as a global component:

.vuepress/client.ts

import Swiper from 'vuepress-theme-plume/features/Swiper.vue'
import { defineClientConfig } from 'vuepress/client'

export default defineClientConfig({
  enhance({ app }) {
    app.component('Swiper', Swiper)
  },
})

Global components can be used in any other markdown file:

<Swiper :items="['img_link1', 'img_link2']" />

Example:

Props

Name	Type	Default	Description
items	string | { link: string; href?: string; alt?: string}[]	[]	Image link array. When passing objects, link represents image URL, href represents navigation link, alt represents image description
width	number | string	100%	Carousel area width
height	number | string	100%	Carousel area height
mode	'banner' | 'carousel' | 'broadcast'	'banner'	Carousel mode: banner: banner; carousel: carousel; broadcast: information display
navigation	boolean	true	Whether to show navigation buttons
effect	'slide' | 'fade' | 'cube' | 'coverflow' | 'flip' | 'cards' | 'creative'	'slide'	Carousel effect
delay	number	3000	Carousel interval time. Only effective when mode: 'banner'. Unit: ms
speed	number	300	Animation duration. Unit: ms
loop	boolean	true	Whether to loop
pauseOnMouseEnter	boolean	false	Whether to pause carousel on mouse hover
swipe	boolean	true	Whether to enable gesture swiping

For more props, refer to Swiper Documentation

Reference Examples

Preset Animation Effects

cube:

View Code

<Swiper :items="images" effect="cube" />

fade:

View Code

<Swiper :items="images" effect="fade" />

coverflow:

View Code

<Swiper :items="images" effect="coverflow" />

flip:

View Code

<Swiper :items="images" effect="flip" />

cards:

View Code

<Swiper :items="images" effect="cards" />

Custom Animation Effects

Example 1:

View Code

<Swiper :items="images" effect="creative" :creativeEffect="{
  prev: { shadow: true, translate: [0, 0, -400] },
  next: { translate: ['100%', 0, 0] },
}"
/>

Example 2:

View Code

<Swiper :items="images" effect="creative" :creativeEffect="{
  prev: { shadow: true,  translate: [0, 0, -800], rotate: [180, 0, 0] },
  next: { shadow: true, translate: [0, 0, -800], rotate: [-180, 0, 0] },
}"
/>

Example 3:

View Code

<Swiper :items="images" effect="creative" :creativeEffect="{
  prev: { shadow: true, translate: ['-125%', 0, -800], rotate: [0, 0, -90] },
  next: { shadow: true, translate: ['125%', 0, -800], rotate: [0, 0, 90] },
}"
/>

Example 4:

View Code

<Swiper :items="images" effect="creative" :creativeEffect="{
  prev: { shadow: true, origin: 'left center', translate: ['-5%', 0, -200], rotate: [0, 100, 0] },
  next: { origin: 'right center', translate: ['5%', 0, -200], rotate: [0, -100, 0] },
}"
/>

Carousel

View Code

<Swiper
  :items="images"
  mode="carousel"
  :height="200"
  :slides-per-view="3"
  :space-between="20"
  :speed="5500"
/>

Information Display

View Code

<Swiper
  :items="images"
  mode="broadcast"
  :height="200"
  :slides-per-view="3"
  :space-between="20"
  mousewheel
/>

Contributors

pengzhanbo

Changelog

10/9/25, 7:46 AM

View All Changelog

• 38505-docs: update en docs (#708)on 10/9/25
• 4d236-feat(theme)!: add collections support (#704)on 10/7/25
• 47335-docs: update docson 5/6/25
• 73ed8-feat(theme): add badge support for navbar and sidebar (#559)on 4/19/25
• 0fd6c-refactor(theme): improve types and flat config (#524)on 3/15/25
• 597a1-style: lint fixon 11/29/24
• b99d9-feat(theme): add page title badge (#183)on 9/15/24
• 8ccc6-docs: update docson 9/12/24
• 85b9d-docs: update docson 9/12/24