https://github.com/deoostfrees/Parvus
An open source, dependency free image lightbox with the goal of being accessible.
https://github.com/deoostfrees/Parvus
a11y accessibility dependency-free javascript lightbox vanilla
Last synced: 6 months ago
JSON representation
An open source, dependency free image lightbox with the goal of being accessible.
- Host: GitHub
- URL: https://github.com/deoostfrees/Parvus
- Owner: deoostfrees
- License: mit
- Created: 2020-10-05T19:18:06.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-05-01T17:36:57.000Z (over 1 year ago)
- Last Synced: 2024-05-01T18:35:08.413Z (over 1 year ago)
- Topics: a11y, accessibility, dependency-free, javascript, lightbox, vanilla
- Language: JavaScript
- Homepage: https://codepen.io/collection/DwLBpz
- Size: 4.48 MB
- Stars: 407
- Watchers: 4
- Forks: 14
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Parvus
Overlays suck, but if you need one, consider using Parvus. Parvus is an open source, dependency free image lightbox with the goal of being accessible.
[Open in CodePen](https://codepen.io/collection/DwLBpz)
## Table of Contents
- [Installation](#installation)
- [Download](#download)
- [Package Managers](#package-managers)
- [Usage](#usage)
- [Captions](#captions)
- [Gallery](#gallery)
- [Responsive Images](#responsive-images)
- [Localization](#localization)
- [Options](#options)
- [API](#api)
- [Events](#events)
- [Browser Support](#browser-support)
## Installation
### Download
- CSS:
- `dist/css/parvus.min.css` (minified) or
- `dist/css/parvus.css` (un-minified)
- JavaScript:
- `dist/js/parvus.min.js` (minified) or
- `dist/js/parvus.js` (un-minified)
Link the `.css` and `.js` files in your HTML:
```html
Page title
```
### Package Managers
You can also install Parvus using npm or yarn:
```sh
npm install parvus
```
or
```sh
yarn add parvus
```
After installation, import Parvus into your JavaScript codebase:
```js
import Parvus from 'parvus'
```
Be sure to include the corresponding SCSS or CSS file.
## Usage
Link a thumbnail image with the class `lightbox` to a larger image:
```html
```
Initialize the script:
```js
const prvs = new Parvus()
```
### Captions
To show a caption under the image, add a `data-caption` attribute:
```html
```
Alternatively, set the option `captionsSelector` to select captions from an element's innerHTML:
```html
I'm a caption
```
```js
const prvs = new Parvus({
captionsSelector: '.figure__caption',
})
```
### Gallery
To group related images into a set, add a `data-group` attribute:
```html
//...
```
Alternatively, set the option `gallerySelector` to group all images with a specific class within a selector:
```html
// ...
```
```js
const prvs = new Parvus({
gallerySelector: '.gallery',
})
```
### Responsive Images
Specify different image sources and sizes using the `data-srcset` and `data-sizes` attributes:
```html
```
### Localization
Import the language module and set it as an option for localization:
```js
import de from 'parvus/src/l10n/de'
const prvs = new Parvus({
l10n: de
})
```
## Options
Customize Parvus by passing an options object when initializing:
```js
const prvs = new Parvus({
// Clicking outside does not close Parvus
docClose: false
})
```
Available options include:
```js
{
// Selector for elements that trigger Parvus
selector: '.lightbox',
// Selector for a group of elements combined as a gallery, overrides the `data-group` attribute.
gallerySelector: null,
// Display zoom indicator
zoomIndicator: true,
// Display captions if available
captions: true,
// Selector for the element where the caption is displayed; use "self" for the `a` tag itself.
captionsSelector: 'self',
// Attribute to get the caption from
captionsAttribute: 'data-caption',
// Clicking outside closes Parvus
docClose: true,
// Close Parvus by swiping up/down
swipeClose: true,
// Accept mouse events like touch events (click and drag to change slides)
simulateTouch: true,
// Touch dragging threshold in pixels
threshold: 100,
// Hide browser scrollbar
hideScrollbar: true,
// Icons
lightboxIndicatorIcon: '',
previousButtonIcon: '',
nextButtonIcon: '',
closeButtonIcon: '',
// Localization of strings
l10n: en
}
```
## API
Parvus provides the following API functions:
| Function | Description |
| --- | --- |
| `open(element)` | Open the specified `element` (DOM element) |
| `close()` | Close Parvus |
| `previous()` | Show the previous image |
| `next()` | Show the next image |
| `select(index)` | Select a slide with the specified `index` (integer) |
| `add(element)` | Add the specified `element` (DOM element) |
| `remove(element)` | Remove the specified `element` (DOM element) |
| `destroy()` | Destroy Parvus |
| `isOpen()` | Check if Parvus is currently open |
| `currentIndex()` | Get the index of the currently displayed slide |
## Events
Bind and unbind events using the `.on()` and `.off()` methods:
```js
const prvs = new Parvus()
const listener = () => {
console.log('eventName happened')
}
// Bind event listener
prvs.on(eventName, listener)
// Unbind event listener
prvs.off(eventName, listener)
```
Available events:
| eventName | Description |
| --- | --- |
| `open` | Triggered after Parvus has opened |
| `select` | Triggered when a slide is selected |
| `close` | Triggered after Parvus has closed |
| `destroy` | Triggered after Parvus has destroyed |
## Browser Support
Parvus is supported on the latest versions of the following browsers:
- Chrome
- Edge
- Firefox
- Safari
