A Vue.js 3.0 image lightbox component with Zoom / Drag / Rotate / Switch
npm install 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.
``shell`
$ npm install --save vue-easy-lightbox@nextOR
$ yarn add vue-easy-lightbox@next
Include the CDN link in HTML.
`html`
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) |
> 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/.
`js
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
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:
`ts`
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: alias
If you're using webpack: webpack alias docs
`js
// 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
`
Or vitejs: vitejs alias
`js
// 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'
}
}
})
`
`html`
showImg(index)">
`javascript
import Vue from 'vue'
import VueEasyLightbox from 'vue-easy-lightbox'
const app = Vue.createApp({
// ... app options
})
app.use(VueEasyLightbox)
app.mount('#app')
`
` html
:imgs="imgsRef"
:index="indexRef"
@hide="onHide"
>
`
`html
`
Reference: Slots
> 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:
`html
:imgs="imgsRef"
:index="indexRef"
@hide="onHide"
/>
`
#### Type declaration
`ts``
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;
indexRef: Ref
visibleRef: Ref
show: (index?: Ref
onHide: () => void;
changeIndex: (index?: number) => void;
};
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 |
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 & Scoped 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 |