VitePress Swiper Plugin

• Install
• Usage
• Options
• Support

A VitePress Plugin to Easily add a SwiperJS Photo Gallery or Image Slideshow with Custom Options.

Easy to install and use with lots of custom options. Provide a list of slide URL's or dynamically generate them.

Minimal footprint with only 3 lines of setup code and 1 Markdown tag per gallery.

Live Demo's and Examples are available on the website.

[!IMPORTANT]
For Up-to-Date Documentation, please visit the website:
https://vitepress-swiper.cssnr.com/

Install

There are 2 ways to install this plugin based on preference.

1. As a Dependency - Easiest, minimal footprint, no source access
2. From the Source - Adds 1 file to your project, full source access

View the Installation Guide.

As a Dependency

NPM Package: https://www.npmjs.com/package/@cssnr/vitepress-swiper

Install directly into your VitePress with:

npm i @cssnr/vitepress-swiper

Then import it in your .vitepress/theme/index.js:

import DefaultTheme from 'vitepress/theme'

import VPSwiper from '@cssnr/vitepress-swiper' // add this line
import '@cssnr/vitepress-swiper/style.css' // add this line

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('VPSwiper', VPSwiper) // add this line
  },
}

Note: If you use the VitePress Badge see the Setup Guide for more information.

Proceed to Usage.

From the Source

Add to your project:

1. Download or clone the src/VPSwiper.vue file to your project.
2. Place it to the following location: .vitepress/theme/components/VPSwiper.vue
3. Install the dependencies, swiper.

npm i swiper

Then import it in your .vitepress/theme/index.js:

import DefaultTheme from 'vitepress/theme'

import VPSwiper from './components/VPSwiper.vue' // add this line

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('VPSwiper', VPSwiper) // add this line
  },
}

Usage

To use, add a <VPSwiper> tag to your markdown where you want the gallery to appear.

You can provide a list of :slides or generate a dynamic :number-of-slides using a base-url.

View the Usage Guide.

Slides List

To generate from a list of :slides add them in this format.

<VPSwiper
  :slides="[
    'https://example.com/path/1.jpg',
    'https://example.com/path/2.jpg',
    'https://example.com/path/3.jpg',
  ]"
/>

Example using additional options.

<VPSwiper
  :slides="[
    'https://example.com/path/1.jpg',
    'https://example.com/path/2.jpg',
    'https://example.com/path/3.jpg',
  ]"
  :pagination="{ type: 'fraction' }"
  :mousewheel="false"
  button-text="Fullscreen"
  margin-top="30px"
  effect="coverflow"
  :coverflow-effect="{ slideShadows: false }"
/>

[!TIP]
See Live Demo's, Examples, and Up-to-Date Docs on the website:
https://vitepress-swiper.cssnr.com/

Dynamic URL Generation

This only works if your files are named numerically and ordered sequentially.

This generates numbers for filenames and appends them to the base url as follows:

• base-url + / + file-name-prefix + file# + file-ext

Therefore, the following <VPSwiper> tag options/parameters.

<VPSwiper base-url="https://example.com/path" :number-of-slides="3" />

Will produce these URL's:

https://example.com/path/1.jpg
https://example.com/path/2.jpg
https://example.com/path/3.jpg

Example using additional options.

<VPSwiper
  base-url="https://example.com/path"
  :number-of-slides="4"
  :start-at="8"
  :pad-start="2"
  file-name-prefix="slide-"
  file-ext=".png"
  :pagination="{ clickable: true }"
  :grab-cursor="false"
  margin-top="40px"
  effect="fade"
/>

Resulting URL's:

https://example.com/path/slide-08.png
https://example.com/path/slide-09.png
https://example.com/path/slide-10.png
https://example.com/path/slide-11.png

Options

There are Plugin Options and Swiper Options.

Note: String parameters do not begin with a : but all other types do.

View the Options Guide.

Plugin Options

You must provide :slides or a base-url but not both.

| Property Name | Default Value | Type | Description of Value | | :---------------------- | :-----------------------: | :-----: | :---------------------------------------------------------------------------------------- | | :slides | or base-url | Array | Base URL for image sources | | base-url ¹ | or :slides | String | Base URL for image sources | | :number-of-slides ¹ | 1 | Number | Number of slides to generate | | :start-at ¹ | 1 | Number | Number to start generation | | file-ext ¹ | .jpg | String | Extension for file names | | :pad-start ¹ | 1 | Number | Pad file names with 0's | | file-name-prefix ¹ | | String | Prefix for file names | | alt-text-prefix | Loading | String | Prefix for alt attributes | | button-text | View in Fullscreen | String | Text for fullscreen button | | no-fullscreen | false | Boolean | Disable fullscreen button | | height | null | String | CSS height (default: auto) | | margin | null | String | CSS margin | | background-color | var(--vp-code-block-bg) | String | CSS background-color | | border-radius | 8px | String | CSS border-radius |

¹ Only used with Dynamic URL's

Swiper Options

Swiper Parameters: https://swiperjs.com/swiper-api#parameters

| Property Name | Default | Type | Description of Value | | :------------------------------------------------------------------------------- | :----------: | :-----: | :---------------------------------- | | :slides-per-view | 1 | Number | Number of slides shown per view | | :space-between | 0 | Number | Space between slides in pixels | | :lazy-preload-prev-next | 1 | Number | Number of lazy loaded slides | | :breakpoints | null | Object | Breakpoints parameters | | :pagination | true | Object | Pagination parameters | | :keyboard | true | Boolean | Enable keyboard navigation | | :mousewheel | true | Boolean | Enable mouse wheel navigation | | :navigation | true | Boolean | Enable side navigation arrows | | :grab-cursor | true | Boolean | Enable grab cursor on hover | | :loop | true | Boolean | Enable continuous loop | | :autoplay | false | Object | Can be true or parameters | | :centered-slides | false | Boolean | Center slides vs left aligned | | :direction | horizontal | String | If vertical must set height | | :initial-slide | 0 | Number | Initial slide index | | :one-way-movement | false | Boolean | Only allow swiping forward | | :speed | 300 | Number | Slide transition speed in ms | | effect | slide | String | coverflow, cube, fade, flip | | :coverflow-effect | { } | Object | EffectCoverflow parameters | | :cube-effect | { } | Object | EffectCube parameters | | :fade-effect | { } | Object | EffectFade parameters | | :flip-effect | { } | Object | EffectFlip parameters |

[!TIP]
If you need more options, please start a feature request discussion.

Support

Please let us know if you run into any issues or want to see new features...

For general help or to request a feature:

• Q&A Discussion: https://github.com/cssnr/vitepress-swiper/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/vitepress-swiper/discussions/categories/feature-requests

If you are experiencing an issue/bug or getting unexpected results:

• Report an Issue: https://github.com/cssnr/vitepress-swiper/issues
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY
• Provide General Feedback: https://cssnr.github.io/feedback/

More VitePress Plugins

• SwiperJS - Photo Gallery
• Contributors - GitHub Contributors
• Copy Button - Copy Text Button

Contributing

All contributions are welcome including bug reports, feature requests, or pull requests.

For instructions on creating a PR for the Package or Documentation, see the CONTRIBUTING.md.

Please consider making a donation to support the development of this project and additional open source projects.

For a full list of current projects visit: https://cssnr.github.io/