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.

$3

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.

$3

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.

`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 of :slides or generate
a dynamic :number-of-slides using a base-url.

> View the Usage Guide.

$3

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

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

Example using additional options.

`vue
: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/

$3

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
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:

`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 and Swiper Options.

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

> View the Options Guide.

$3

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

$3

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/

$3

- 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/