Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/am283721/vue-my-photos

Simple lightbox component for Vue applications
https://github.com/am283721/vue-my-photos

gallery image-gallery lightbox lightbox-component lightbox-gallery lightbox-gallery-plugin vue vue-component vue2 vue3 vuejs vuejs2

Last synced: about 1 month ago
JSON representation

Simple lightbox component for Vue applications

Awesome Lists containing this project

README 

        
# Simple Image Lightbox for Vue.js

Upgraded to support Vue 3 and still no dependencies required!



Inspired by vue-pure-lightbox, however I 

needed a framework that allowed for a gallery of thumbnails as well as filtering functionality.



## Vue Compatibility

Versions >= 3.0.0 are built for Vue 3.



If your project uses Vue 2, use vue-my-photos-1.1.1

## Demo

Live demo available on Codepen



## Installation



### Via NPM:

```bash

npm i vue-my-photos --save

```



### Via CDN:

```html



```



## Setup



In your App:

```html



    import Lightbox from "@/lightbox.vue";

    // ...

    export default defineComponent({

        name: "VueMyPhotosDemo",

        components: {

            Lightbox,

        },

        // ...

    })



```

## Usage



Simply initiate a lightbox component with the `lightbox` tag:



```html



```



Expose the appropriate data for the template:



```js

data() {

    return {

        thumbnailDir: "/.../.../",

        images: imageList,

        galleryFilter: "all",

        currentImageName: ""

    };

},

```



Each thumbnail in the gallery registers a click event, passing the name of the photo:



```html

...

```



And add the showLightbox and onLightboxClose methods to your vue page (these can be named however you like):



```js

showLightbox(imageName: string) {

    this.currentImageName = imageName;

},

onLightboxClose(imageName: string) {

    this.currentImageName = imageName;

},

```



To update which images show within the lightbox, update the filter string like so:

```js

updateFilter(filterName) {

    this.galleryFilter = filterName;

}

```



### A Note On v3 Updates



Previously, the lightbox was shown by accessing the component via the $refs object and calling the show method directly:



```js

showLightbox: function(imageName) {

    this.$refs.mylightbox.show(imageName);

}

```



This approach can still be done (and in Vue 3 using Ref() within the setup method), however, in an effort to decouple the Lightbox Component from its parent Component, the new recommended approach is detailed above using the `currentImageName` prop. This is a reactive property that will trigger the lightbox to display whenever its value is changed. A method that listens to the `on-lightbox-close` event must also be implemented in order to reset the value of  `currentImageName` (Otherwise, if the user tries to open the lightbox with the same image twice in a row, `currentImageName` won't change and the lightbox won't open).



### Properties



| Property                                         | Type     | Value                                                                       |

| ------------------------------------------------ | -------- | --------------------------------------------------------------------------- |

| images (Required)                                | array    | Array of objects with image data (example below)                            |

| currentImageName (Required)                      | string   | Should initially be an empty string, then updated later to trigger lightbox |

| filter (Optional - Default: "all")               | string   | String to filter on specific images (Ex: "nature")                          |

| directory (Optional - Default: "")               | string   | Path to location of images (Ex: "/src/assets/")                             |

| timeoutDuration (Optional - Default: 3000)       | integer  | duration in ms of key/mouse inactivity before caption disappears            |

| closeOnBackdropClick (Optional - Default: false) | boolean  | toggle whether or not to close lightbox when clicking outside of image      |



### Events



| Event                                                                                     | Description                                                                                                                     |

| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |

| onLightboxClose(imageName: string)                                                        | Fired every time the lightbox is closed. Must implement a method to update currentImageName with the value passed by this event |

| onLightboxChange(newImage: { name: string, alt: string, filter: string, id: string }      | Fired every time the user advances the lightbox to the next or previous image.                                                  |



**Example of images array:**



```js

var images = [{'name':'mountains.jpg', 'alt':'The Dolomites', 'filter':'nature', 'id':'image1' },

              {'name':'bird.jpg', 'alt':'It is a bird', 'filter':'animals', 'id':'image2' }];

```



**Note**:

- 'name' value should include the file extension

- 'alt' is optional

- 'filter' is optional if you never pass or try to update the filter value on the lightbox component

- 'id' is optional, but useful as a key if you're displaying the images in a gallery using the v-for iterator



## Recommended additional modules



disable-scroll or similar module to prevent the user from scrolling while the lightbox is visible.



vue-fontawesome if you want to replace/re-style the svg icons for left/right arrows and close icon.