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/