vue-tinybox

vue-tinybox

A slick, yet tiny lightbox gallery for Vue 3.

• 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="index" :images="images" loop no-thumbs />

Install

• In modern browsers, you can import Tinybox from a CDN URL along with the Vue import:

  <script type="module">
  	import { createApp } from "https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.js";
  	import Tinybox from "https://cdn.jsdelivr.net/npm/vue-tinybox@2/dist/vue-tinybox.js";
  
  	// ...
  </script>
  

  You'll also need the CSS file:

  <link
  	href="https://cdn.jsdelivr.net/npm/vue-tinybox@2/dist/vue-tinybox.css"
  	rel="stylesheet"
  />
  

• In Node, install the vue-tinybox package:

   pnpm add vue-tinybox
  

  npm install vue-tinybox
  

  yarn add vue-tinybox
  

  ...and then import Tinybox like you usually would:

  import Tinybox from "vue-tinybox";
  import "vue-tinybox/css";
  // or const Tinybox = require("vue-tinybox");
  

After you have imported Tinybox, you can bind it to your application instance like you usually do:

const app = createApp({
	components: {
		Tinybox,
	},
});

// or app.component("Tinybox", Tinybox);

// or app.use(Tinybox);

For older browsers

If you need to use the component in a browser without ESM support, include the IIFE version:

<link
	href="https://cdn.jsdelivr.net/npm/vue-tinybox@2/dist/vue-tinybox.css"
	rel="stylesheet"
/>
<script src="https://cdn.jsdelivr.net/npm/vue-tinybox@2/dist/vue-tinybox.iife.js"></script>

This exposes the Tinybox component in the global scope. Include it in your app:

<script>
	app = createApp({
		// ...
	});

	app.component("Tinybox", Tinybox);
</script>

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="index" :images="images" />

<!-- is equivalent to -->

<Tinybox :images="images" :index="index" @update:index="(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="index"
	@update:index="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

51+	28+	10+	16+