https://github.com/cssnr/vitepress-swiper
A VitePress Swiper Plugin to Easily add an Image or Photo Gallery with Custom Options.
https://github.com/cssnr/vitepress-swiper
vitepress
Last synced: 4 months ago
JSON representation
A VitePress Swiper Plugin to Easily add an Image or Photo Gallery with Custom Options.
- Host: GitHub
- URL: https://github.com/cssnr/vitepress-swiper
- Owner: cssnr
- License: gpl-3.0
- Created: 2025-08-25T00:35:19.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-08-25T06:22:11.000Z (9 months ago)
- Last Synced: 2025-08-25T06:42:35.966Z (9 months ago)
- Topics: vitepress
- Language: Vue
- Homepage: https://cssnr.github.io
- Size: 40 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/@cssnr/vitepress-swiper)
[](https://github.com/cssnr/vitepress-swiper/releases)
[](https://npm-stat.com/charts.html?package=%40cssnr%2Fvitepress-swiper)
[](https://bundlephobia.com/package/@cssnr/vitepress-swiper)
[](https://github.com/cssnr/vitepress-swiper/deployments/npm)
[](https://github.com/cssnr/vitepress-swiper/deployments/docs)
[](https://github.com/cssnr/vitepress-swiper/actions/workflows/release.yaml)
[](https://github.com/cssnr/vitepress-swiper/actions/workflows/lint.yaml)
[](https://github.com/cssnr/vitepress-swiper?tab=readme-ov-file#readme)
[](https://github.com/cssnr/vitepress-swiper/blob/master/src/VPSwiper.vue)
[](https://github.com/cssnr/vitepress-swiper/pulse)
[](https://github.com/cssnr/vitepress-swiper/issues)
[](https://github.com/cssnr/vitepress-swiper/graphs/contributors)
[](https://github.com/cssnr/vitepress-swiper/discussions)
[](https://github.com/cssnr/vitepress-swiper/stargazers)
[](https://cssnr.github.io/)
[](https://discord.gg/wXy6m2X8wY)
[](https://ko-fi.com/cssnr)
# VitePress Swiper Plugin
- [Install](#Install)
- [Usage](#Usage)
- [Options](#Options)
- [Support](#Support)
A [VitePress](https://vitepress.dev/) Plugin to Easily add a [SwiperJS](https://swiperjs.com/) Photo Gallery or Image Slideshow with Custom [Options](#Options).
Easy to [install](#Install) and [use](#Usage) with lots of custom [options](#Options).
Provide a [list](#Usage) of slide URL's or [dynamically generate](#dynamic-url-generation) 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](https://vitepress-swiper.cssnr.com/examples).
> [!IMPORTANT]
> For **Up-to-Date** Documentation, please visit the website:
> https://vitepress-swiper.cssnr.com/
## Install
- [NPM Package](#NPM-Package) - Easiest, minimal footprint, no source access
- [From Source](#From-Source) - Adds 1 file to your project, full source access
View the [Installation Guide](https://vitepress-swiper.cssnr.com/guides/get-started#install) for more details.
### NPM Package
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](https://vitepress.dev/reference/default-theme-badge#badge)
see the [Setup Guide](https://vitepress-swiper.cssnr.com/guides/get-started#setup) for more information._
Proceed to [Usage](#Usage).
### From Source
Add to your project:
1. Download or clone the [src/VPSwiper.vue](src/VPSwiper.vue) file to your project.
2. Place it to the following location: `.vitepress/theme/components/VPSwiper.vue`
3. Install the dependencies, `swiper`.
```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
},
}
```
## Usage
To use, add a `` tag to your markdown where you want the gallery to appear.
You can provide a [list](#slides-list) of `:slides` or generate
a [dynamic](#dynamic-url-generation) `:number-of-slides` using a `base-url`.
> View the [Usage Guide](https://vitepress-swiper.cssnr.com/guides/get-started#usage).
### Slides List
To generate from a list of `:slides` add them in this format.
```vue
```
Example using [additional options](#options).
```vue
```
> [!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 `` 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](#options).
```vue
```
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
```
## Options
There are [Plugin Options](#plugin-options) and [Swiper Options](#swiper-options).
_Note: String parameters do **not** begin with a `:` but all other types do._
> View the [Options Guide](https://vitepress-swiper.cssnr.com/docs/options).
### 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](https://developer.mozilla.org/en-US/docs/Web/CSS/height) (default: auto) |
| margin | `null` | String | [CSS margin](https://developer.mozilla.org/en-US/docs/Web/CSS/margin) |
| background-color | `var(--vp-code-block-bg)` | String | [CSS background-color](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) |
| border-radius | `8px` | String | [CSS border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) |
> **¹** Only used with [Dynamic URL's](#dynamic-url-generation)
### Swiper Options
Swiper Parameters: https://swiperjs.com/swiper-api#parameters
| Property Name | Default | Type | Description of Value |
| :------------------------------------------------------------------------------- | :----------: | :-----: | :---------------------------------- |
| [:slides-per-view](https://swiperjs.com/swiper-api#param-slidesPerView) | `1` | Number | Number of slides shown per view |
| [:space-between](https://swiperjs.com/swiper-api#param-spaceBetween) | `0` | Number | Space between slides in pixels |
| [:lazy-preload-prev-next](https://swiperjs.com/swiper-api#param-spaceBetween) | `1` | Number | Number of lazy loaded slides |
| [:breakpoints](https://swiperjs.com/swiper-api#param-breakpoints) | `null` | Object | Breakpoints parameters |
| [:pagination](https://swiperjs.com/swiper-api#pagination-parameters) | `true` | Object | Pagination parameters |
| [:keyboard](https://swiperjs.com/swiper-api#param-keyboard) | `true` | Boolean | Enable keyboard navigation |
| [:mousewheel](https://swiperjs.com/swiper-api#param-mousewheel) | `true` | Boolean | Enable mouse wheel navigation |
| [:navigation](https://swiperjs.com/swiper-api#param-navigation) | `true` | Boolean | Enable side navigation arrows |
| [:grab-cursor](https://swiperjs.com/swiper-api#param-grabCursor) | `true` | Boolean | Enable grab cursor on hover |
| [:loop](https://swiperjs.com/swiper-api#param-loop) | `true` | Boolean | Enable continuous loop |
| [:autoplay](https://swiperjs.com/swiper-api#param-autoplay) | `false` | Object | Can be `true` or parameters |
| [:centered-slides](https://swiperjs.com/swiper-api#param-centeredSlides) | `false` | Boolean | Center slides vs left aligned |
| [:direction](https://swiperjs.com/swiper-api#param-direction) | `horizontal` | String | If `vertical` must set `height` |
| [:initial-slide](https://swiperjs.com/swiper-api#param-initialSlide) | `0` | Number | Initial slide index |
| [:one-way-movement](https://swiperjs.com/swiper-api#param-oneWayMovement) | `false` | Boolean | Only allow swiping forward |
| [:speed](https://swiperjs.com/swiper-api#param-speed) | `300` | Number | Slide transition speed in ms |
| [effect](https://swiperjs.com/swiper-api#param-effect) | `slide` | String | `coverflow`, `cube`, `fade`, `flip` |
| [:coverflow-effect](https://swiperjs.com/swiper-api#coverflow-effect-parameters) | `{ }` | Object | EffectCoverflow parameters |
| [:cube-effect](https://swiperjs.com/swiper-api#cube-effect-parameters) | `{ }` | Object | EffectCube parameters |
| [:fade-effect](https://swiperjs.com/swiper-api#fade-effect-parameters) | `{ }` | Object | EffectFade parameters |
| [:flip-effect](https://swiperjs.com/swiper-api#flip-effect-parameters) | `{ }` | Object | EffectFlip parameters |
> [!TIP]
> If you need more options, please start a [feature request discussion](https://github.com/cssnr/vitepress-swiper/discussions/categories/feature-requests).
## Support
Please let us know if you run into any [issues](https://github.com/cssnr/vitepress-swiper/issues)
or want to see [new features](https://github.com/cssnr/vitepress-swiper/discussions/categories/feature-requests)...
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/](https://cssnr.github.io/feedback/?app=VitePress%20Swiper)
### More VitePress Plugins
- [SwiperJS](https://github.com/cssnr/vitepress-swiper) - Photo Gallery
- [Contributors](https://github.com/cssnr/vitepress-plugin-contributors) - GitHub Contributors
- [Copy Button](https://github.com/cssnr/vitepress-plugin-copybutton) - Copy Text Button
# Contributing
All contributions are welcome including [bug reports](https://github.com/cssnr/vitepress-swiper/issues), [feature requests](https://github.com/cssnr/vitepress-swiper/discussions/categories/feature-requests), or pull requests.
For instructions on creating a PR for the [Package](https://www.npmjs.com/package/@cssnr/vitepress-swiper) or [Documentation](https://vitepress-swiper.cssnr.com/),
see the [CONTRIBUTING.md](#contributing-ov-file).
Please consider making a donation to support the development of this project and additional open source projects.
[](https://ko-fi.com/cssnr)
For a full list of current projects visit: [https://cssnr.github.io/](https://cssnr.github.io/)