A VitePress Plugin to Easily add a SwiperJS Photo Gallery or Image Slideshow with Custom Options.
npm install @cssnr/vitepress-swiper
















- 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/
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.
NPM Package: https://www.npmjs.com/package/@cssnr/vitepress-swiper
Install directly into your VitePress with:
``shell`
npm i @cssnr/vitepress-swiper
Then import it in your .vitepress/theme/index.js:
`javascript
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.
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.vueswiper
3. Install the dependencies, .
`shell`
npm i swiper
Then import it in your .vitepress/theme/index.js:
`javascript
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
},
}
`
To use, add a tag to your markdown where you want the gallery to appear.
You can provide a list of :slides or generate:number-of-slides
a dynamic using a base-url.
> View the Usage Guide.
To generate from a list of :slides add them in this format.
`vue`
'https://example.com/path/1.jpg',
'https://example.com/path/2.jpg',
'https://example.com/path/3.jpg',
]"
/>
Example using additional options.
`vue`
'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/
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 tag options/parameters.
`vue`
Will produce these URL's:
`text`
https://example.com/path/1.jpg
https://example.com/path/2.jpg
https://example.com/path/3.jpg
Example using additional options.
`vue`
: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:
`text`
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
There are Plugin Options and Swiper Options.
_Note: String parameters do not begin with a : but all other types do._
> View the Options Guide.
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 |1
| :start-at ¹ | | Number | Number to start generation |.jpg
| file-ext ¹ | | String | Extension for file names |1
| :pad-start ¹ | | Number | Pad file names with 0's |
| file-name-prefix ¹ | | String | Prefix for file names |Loading
| alt-text-prefix | | String | Prefix for alt attributes |View in Fullscreen
| button-text | | String | Text for fullscreen button |false
| no-fullscreen | | Boolean | Disable fullscreen button |null
| height | | String | CSS height (default: auto) |null
| margin | | String | CSS margin |var(--vp-code-block-bg)
| background-color | | String | CSS background-color |8px
| border-radius | | String | CSS border-radius |
> ¹ Only used with Dynamic URL's
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 |0
| :space-between | | Number | Space between slides in pixels |1
| :lazy-preload-prev-next | | Number | Number of lazy loaded slides |null
| :breakpoints | | Object | Breakpoints parameters |true
| :pagination | | Object | Pagination parameters |true
| :keyboard | | Boolean | Enable keyboard navigation |true
| :mousewheel | | Boolean | Enable mouse wheel navigation |true
| :navigation | | Boolean | Enable side navigation arrows |true
| :grab-cursor | | Boolean | Enable grab cursor on hover |true
| :loop | | Boolean | Enable continuous loop |false
| :autoplay | | Object | Can be true or parameters |false
| :centered-slides | | Boolean | Center slides vs left aligned |horizontal
| :direction | | String | If vertical must set height |0
| :initial-slide | | Number | Initial slide index |false
| :one-way-movement | | Boolean | Only allow swiping forward |300
| :speed | | Number | Slide transition speed in ms |slide
| effect | | String | coverflow, cube, fade, flip |{ }
| :coverflow-effect | | Object | EffectCoverflow parameters |{ }
| :cube-effect | | Object | EffectCube parameters |{ }
| :fade-effect | | Object | EffectFade parameters |{ }` | Object | EffectFlip parameters |
| :flip-effect |
> [!TIP]
> If you need more options, please start a feature request discussion.
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/
- SwiperJS - Photo Gallery
- Contributors - GitHub Contributors
- Copy Button - Copy Text Button
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/