vue-easy-lightbox
A Vue.js 3.0 image lightbox component with Zoom / Drag / Rotate / Switch .
vue-easy-lightbox@1.x
only supports Vue.js 3, if you need Vue.js 2 version please check here.
Installation
Using npm or yarn
$ npm install --save vue-easy-lightbox@next
$ yarn add vue-easy-lightbox@next
Import in Browser
Add script
in your browser and use the global variable VueEasyLightbox
.
<script src="https://unpkg.com/vue@next"></script>
<script src="https://unpkg.com/vue-easy-lightbox@next/dist/vue-easy-lightbox.umd.min.js"></script>
<script>
const app = Vue.createApp({
// ... root component options
})
app.use(VueEasyLightbox) // global variable
app.mount('#app')
</script>
Different Builds
Since Vue 3.x
uses ES2015
(docs faq), there is no need to build ES5
bundle, and ES5
build is removed from version 1.6.0
.
Module | Filename |
---|---|
UMD(for browsers) | vue-easy-lightbox.umd.min.js |
CommonJS | vue-easy-lightbox.common.min.js (pkg.main) |
ES Module(for bundlers) | vue-easy-lightbox.esm.min.js (pkg.module) |
External CSS Build
Added in:
v1.2.3
By default, CSS is included in dist/*.min.js
. In some special cases you may want to import CSS individually to avoid some problems (CSP Violation). You can import builds without CSS and individual .css
file from dist/external-css/
.
import VueEasyLightbox from 'vue-easy-lightbox/external-css'
// or
import VueEasyLightbox from 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js'
// you need to import css file
import 'vue-easy-lightbox/external-css/vue-easy-lightbox.css'
// or
import 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.css'
TypeScript Checking error:
If your project is TypeScript project and you get this error message:
Could not find the declaration file for module 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js'
Here are two ways to solve it.
Way 1: add d.ts
in your project:
declare module 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js' {
import VueEasyLightbox from 'vue-easy-lightbox'
export * from 'vue-easy-lightbox'
export default VueEasyLightbox
}
Way 2:
If you're using webpack: webpack alias docs
// wepback.config.js
module.exports = {
//...
resolve: {
alias: {
'vue-easy-lightbox$': 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js',
},
},
};
// in your component
import VueEasyLightbox from 'vue-easy-lightbox' // work
vitejs: vitejs alias
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
alias: {
'vue-easy-lightbox$': 'vue-easy-lightbox/dist/external-css/vue-easy-lightbox.esm.min.js'
}
}
})
Usage
UMD
in browser
Using <!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<script src="https://unpkg.com/vue@next"></script>
<script src="https://unpkg.com/vue-easy-lightbox@next/dist/vue-easy-lightbox.umd.min.js"></script>
</head>
<body>
<div id="app">
<div class="">
<div v-for="(src, index) in imgs" :key="index" class="pic" @click="() => showImg(index)">
<img :src="src" />
</div>
</div>
<vue-easy-lightbox :visible="visibleRef" :imgs="imgs" :index="indexRef" @hide="onHide"></vue-easy-lightbox>
</div>
<script>
const { ref } = Vue
const app = Vue.createApp({
setup() {
const visibleRef = ref(false)
const indexRef = ref(0)
const imgs = [
'https://via.placeholder.com/450.png/',
'https://via.placeholder.com/300.png/',
'https://via.placeholder.com/150.png/',
{ src: 'https://via.placeholder.com/450.png/', title: 'this is title' }
]
const showImg = (index) => {
indexRef.value = index
visibleRef.value = true
}
const onHide = () => visibleRef.value = false
return {
visibleRef,
indexRef,
imgs,
showImg,
onHide
}
}
})
// Registering VueEasyLightbox for your VueApp.
app.use(VueEasyLightbox)
app.mount('#app')
</script>
</body>
</html>
Basic Usage in SFC
1. Register VueApp component
In Vue.js
3.0. You need to register the vue-easy-lightbox
for each VueApp
you use. Docs here
import Vue from 'vue'
import VueEasyLightbox from 'vue-easy-lightbox'
const app = Vue.createApp({
// ... root component options
})
app.use(VueEasyLightbox)
app.mount('#app')
2. Basic Usage
<template>
<div>
<button @click="showSingle">Show single picture.</button>
<button @click="showMultiple">Show a group of pictures.</button>
<vue-easy-lightbox
:visible="visibleRef"
:imgs="imgsRef"
:index="indexRef"
@hide="onHide"
></vue-easy-lightbox>
</div>
</template>
<script>
// If VueApp is already registered with VueEasyLightbox, there is no need to register it here.
import VueEasyLightbox from 'vue-easy-lightbox'
import { ref, defineComponent } from 'vue'
export default defineComponent({
components: {
VueEasyLightbox
},
setup() {
const visibleRef = ref(false)
const indexRef = ref(0) // default 0
const imgsRef = ref([])
// Img Url , string or Array of string
// ImgObj { src: '', title: '', alt: '' }
// 'src' is required
// allow mixing
const onShow = () => {
visibleRef.value = true
}
const showSingle = () => {
imgsRef.value = 'http://via.placeholder.com/350x150'
// or
// imgsRef.value = {
// title: 'this is a placeholder',
// src: 'http://via.placeholder.com/350x150'
// }
onShow()
}
const showMultiple = () => {
imgsRef.value = [
'http://via.placeholder.com/350x150',
'http://via.placeholder.com/350x150'
]
// or
// imgsRef.value = [
// { title: 'test img', src: 'http://via.placeholder.com/350x150' },
// 'http://via.placeholder.com/350x150'
// ]
indexRef.value = 0 // index of imgList
onShow()
}
const onHide = () => (visibleRef.value = false)
return {
visibleRef,
indexRef,
imgsRef,
showSingle,
showMultiple,
onHide
}
}
})
</script>
Custom buttons or toolbar
<vue-easy-lightbox ...>
<template v-slot:prev-btn="{ prev }">
<button @click="prev">show the prev</button>
</template>
<template v-slot:next-btn="{ next }">
<button @click="next">show the next</button>
</template>
<template v-slot:close-btn="{ close }">
<button @click="close">close lightbox</button>
</template>
<template v-slot:toolbar="{ toolbarMethods }">
<button @click="toolbarMethods.zoomIn">zoom in</button>
<button @click="toolbarMethods.zoomOut">zoom out</button>
<button @click="toolbarMethods.rotateLeft">Anticlockwise rotation</button>
<button @click="toolbarMethods.rotateRight">clockwise rotation</button>
</template>
</vue-easy-lightbox>
Reference: Slots-Vue.js
Composables
Added in
v1.7.0
useEasyLightbox()
provides some simple methods and states to help you use setup()
. It is optional. You can customize your state.
Usage:
<template>
<div>
<button @click="show">show</button>
<vue-easy-lightbox
:visible="visibleRef"
:imgs="imgsRef"
:index="indexRef"
@hide="onHide"
/>
</div>
</template>
<script>
import { defineComponent } from 'vue'
import VueEasyLightbox, { useEasyLightbox } from 'vue-easy-lightbox'
export default defineComponent({
components: {
VueEasyLightbox
},
setup() {
const {
// methods
show, onHide, changeIndex,
// refs
visibleRef, indexRef, imgsRef
} = useEasyLightbox({
// src / src[]
imgs: [
'http://via.placeholder.com/250x150',
'http://via.placeholder.com/300x150',
'http://via.placeholder.com/350x150'
],
// initial index
initIndex: 0
})
return {
visibleRef,
indexRef,
imgsRef,
show,
onHide
}
}
})
</script>
Type declaration
export interface Img {
src?: string
title?: string
alt?: string
}
export interface UseEasyLightboxOptions {
/**
* image src/Img or list of images src/Img
* @default ''
*/
imgs: Img | string | (Img | string)[];
/**
* initial index of imgList
* @default 0
*/
initIndex?: number;
}
export declare const useEasyLightbox: (options: UseEasyLightboxOptions) => {
imgsRef: Ref<Img | string | (Img | string)[]>;
indexRef: Ref<number | undefined>;
visibleRef: Ref<boolean>;
show: (index?: Ref<number> | number | Event) => void;
onHide: () => void;
changeIndex: (index?: number) => void;
};
Options
Props
Name | Type | Default | Description |
---|---|---|---|
visible | Boolean | required | Control lightbox display |
imgs | String/String[]/ImgObject:{ src: string, title?: string, alt?: string }/ImgObject[] | required | Image's src / array of src / ImgObject:{ src, title?, alt? } / array of ImgObject / array of ImgObject. |
index | Number | 0 | Index of imgList |
loop | Boolean | false | Pass true to enable continuous loop mode. |
scrollDisabled (scroll-disabled) | Boolean | true | Pass true to disable scrolling when modal is visible. |
escDisabled (esc-disabled) | Boolean | false | By default, press the esc key to close Modal during presentation. |
moveDisabled (move-disabled) | Boolean | false | Pass true to disable image movement and enable swipe. |
rotateDisabled (rotate-disabled) | Boolean | false | Pass true to disable image rotation. |
zoomDisabled (zoom-disabled) | Boolean | false | Pass true to disable image zooming. |
pinchDisabled (pinch-disabled) | Boolean | false | Pass true to disable pinching. |
maskClosable (mask-closable) | Boolean | true | Enable or disable click mask to close vue-easy-lightbox. |
dblclickDisabled (dblclick-closable) | Boolean | false | Enable or disable double-click on img to zoom in/out. |
teleport | string | Element | - | Specify the mount node for vue-easy-lightbox. |
swipeTolerance (swipe-tolerance) | Number | 50 | Specify the number of pixel you have to swipe. |
zoomScale | Number | 0.12 | Specify the step between zoom levels. |
maxZoom | Number | 3 | Specify the maximum level of zoom scale. |
minZoom | Number | 0.1 | Specify the minimum level of zoom scale. |
rtl | Boolean | false | support RTL (right to left) languages |
Reference: Teleport
Event
Name | Description | Return Value |
---|---|---|
hide | When you click modal mask or close Btn, component will emit this event | - |
on-error | Image loading error | event (event.target is not the image to be displayed) |
on-prev / on-prev-click | Emit when prev btn is clicked or when the user swiped right | (oldIndex, newIndex) |
on-next / on-next-click | Emit when next btn is clicked or when the user swiped left | (oldIndex, newIndex) |
on-index-change | Emit when imgs's index is changed | (oldIndex, newIndex) |
on-rotate | Emit when image rotate | deg: number (clockwise angle deg) |
Slot
Slot Name | Slot Props | Slot Props Type | Description |
---|---|---|---|
prev-btn | prev | Function | Show the prev img |
next-btn | next | Function | Show the next img |
close-btn | close | Function | Close modal |
toolbar | toolbarMethods: { zoomIn, zoomOut, rotate(rotateLeft), rotateLeft, rotateRight } | { Function } | Zoom in, zoom out, rotate(rotateLeft), rotateLeft, rotateRight |
loading | - | - | Loading icon |
onerror | - | - | Error Placeholder |