🌌 A slick, yet tiny lightbox gallery for Vue.js https://os.karamoff.dev/vue-tinybox/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
Nikita Karamov d373d2128e
Bump dev dependencies
1 year ago
.github Replace Patreon with GitHub Sponsor 2 years ago
dev Update dev environment 2 years ago
docs Update link to library in docs 2 years ago
src Rename variable 2 years ago
.browserslistrc Fix build for browsers 2 years ago
.eslintignore Update .eslintignore 2 years ago
.eslintrc.js Update dependencies 2 years ago
.gitignore Update dev environment 2 years ago
CONTRIBUTING.md Add CONTRIBUTING.md 2 years ago
LICENSE Initial commit 3 years ago
README.md Bump size-limit to 3333 bytes 2 years ago
package.json v1.3.0 2 years ago
rollup.config.js Simplify build config 2 years ago
yarn.lock Bump dev dependencies 1 year ago

README.md

vue-tinybox

Milky Way emoji

A slick, yet tiny lightbox gallery for Vue.js

  • Slick. No excessive design. Pictures, thumbnails, controls.
  • Tiny. Dependency-free. 3 KB minified and gzipped.
  • Adaptive. Works on computers. Works on tablets. Works on phones.

Demo

Observe the live demo here: os.karamoff.dev/vue-tinybox

Basic usage

<Tinybox
    v-model="index"
    :images="images"
    loop
    no-thumbs
/>

Install

Browsers

  1. Include the link to Tinybox in <head> alongside Vue.js:

    <script src="https://cdn.jsdelivr.net/npm/vue"></script>
    <script src="https://cdn.jsdelivr.net/npm/vue-tinybox"></script>
    
  2. Tinybox will auto-install upon detecting the global Vue instance. You can use it right away.

Node environment

  1. Install the Tinybox package:

    npm install vue-tinybox
    # or
    yarn add vue-tinybox
    
  2. Register it as you usually would:

    import Tinybox from "vue-tinybox";
    // or
    const Tinybox = require('vue-tinybox');
    
    
    Vue.component('Tinybox', Tinybox);
    //or
    Vue.use(Tinybox);
    //or
    new Vue({
        components: { Tinybox },
        // ... 
    });
    

API

Image object

An Image object is an object with following fields:

Field name Type Description
src String Image URL
thumbnail String (optional) Thumbnail URL. If omitted, the image URL will be used
caption String (optional) Caption text to be overlayed on the image
alt String (optional) Alt text. If omitted, the caption will be used

Props

Prop name Type Default Description
images Array [] List of either image URLs or Image objects
loop Boolean false Indicates whether the images should loop
no-thumbs Boolean false When enabled, the thumbnails are hidden

v-model

You can use v-model on a Number variable, which will hold the index of the image currently open. If no image is open (i.e. Tinybox is closed), the value becomes null.

Instead of v-model you can use the index prop and change event:

<Tinybox
    v-model="index"
    :images="images"
/>

<!-- is equivalent to -->

<Tinybox
    :images="images"
    :index="index"
    @change="(i) => {index = i}"
/>

Events

Event name Payload Description
change index of the image changed to Is emitted on any image change (thumbnail navigation, prev/next, close)
prev/next index of the image changed to Is emitted specifically when the user clicks "Prev"/"Next" or presses Left/Right arrow key
close index of the image Tinybox was closed at Is emitted specifically when the user clicks "Close" or presses the Esc key

Events can come in handy for business logic cases:

<Tinybox
    :images="images"
    v-model="index"
    @change="onChange"
    @prev="onPrevious"
    @next="onNext"
    @close="onClose"
/>
export default {
    // ...
    methods: {
        onChange(index) {
            console.log("User navigated to the photo: ", index);
        },
        onPrevious(index) {
            console.log("User clicked 'previous' to switch to: ", index);
        },
        onNext(index) {
            console.log("User clicked 'previous' to switch to: ", index);
        },
        onClose(index) {
            console.log("User closed TinyBox on this photo: ", index);
        }
    },
}

Browser support

Chrome Firefox Safari MS Edge Internet Explorer
21+ 28+ 7+ 16+ 11