alpine-tailwind-lightbox

A simple lightbox for AlpineJS and Tailwind CSS projects.

Prerequisites

• AlpineJS 3.x
• AlpineJS Focus Plugin
• Tailwind CSS

Table of Contents

• Installation
• Demo
• Usage
• Config Object
• Magics
• License

Installation

CDN

<!-- Lightbox Plugin -->
<script defer src="https://cdn.jsdelivr.net/npm/alpine-tailwind-lightbox@1.x.x/dist/alpine-tailwind-lightbox.min.js"></script>

<!-- Focus Plugin -->
<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/focus@3.x.x/dist/cdn.min.js"></script>

<!-- AlpineJS Core -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Module

Install the package:

npm install alpine-tailwind-lightbox

Then import and initialize the plugin:

import Alpine from 'alpinejs'
import focus from '@alpinejs/focus'
import lightbox from 'alpine-tailwind-lightbox'

Alpine.plugin(focus)
Alpine.plugin(lightbox)

Alpine.start()

Styles

Make sure Tailwind can pick up the CSS classes by adding the lightbox HTML to your tailwind.config.js:

module.exports = {
    content: [
        // ...
        './node_modules/alpine-tailwind-lightbox/src/template.html',
    ],
    // ...
}

Demo

View Demo

Usage

You can create a lightbox by simply passing a URL to the x-lightbox directive. A click handler will automatically be added to the element with the directive.

<a href="#" x-lightbox="'./image.jpg'">
    Open Image
</a>

Note the single quotes around the URL. It is parsed as a JavaScript expression so you can pass Alpine data or an object as below.

For more options, you can pass an object to the lightbox (see the Config Object reference):

<a href="#" x-lightbox="{ url: './image.jpg', alt: 'An image of something' }">
    Open Image
</a>

<a href="#" x-lightbox="{ url: './video.mp4', type: 'video' }">
    Open Video
</a>

Lightbox Groups

By default, all items will be added to the same "default" lightbox. If you want to create separate lightbox instances on the same page, you can specify a group:

<a href="#" x-lightbox="'./cat.jpg'" x-lightbox:group="cats">
    View the Cats
</a>

<a href="#" x-lightbox="'./dog.jpg'" x-lightbox:group="dogs">
    View the Dogs
</a>

Lazy Loading Images

By default, all images will be fetched in the background on page load. To only fetch an image when it is opened, use the lazy modifier (or the lazy config property):

<a href="#" x-lightbox.lazy="'./cat.jpg'" x-lightbox:group="cats">
    Open Image
</a>

For smoother navigation between images, when an image is opened this will also load the previous and next image in the lightbox.

Programmatic Creation

It is possible to create a lightbox without needing a DOM element per item. See Magics.

Config Object

Option	Type	Default	Description
url	string		The media URL.
type	string	image	The media type. image, video or embed.
group	string?	null	The lightbox group the item should be added to. If omitted, the item is added to the default lightbox.
lazy	boolean	false	Indicates whether to delay fetching the image until it is opened. Only applies to the image type.
muted	boolean	false	Determines whether the video should be muted by default. Only applies to the video type.
autoplay	boolean	false	Determines whether the video should play automatically upon opening the lightbox. Only applies to the video type.

Magics

There are magic functions available for controlling lightboxes programmatically.

$lightbox(items, group)

Parameters

Parameter	Type	Default	Description
items	(string|object)[]		An array of URLs or config objects.
group	string|null	null	The name of the lightbox group. If null, the items will be added to the default lightbox.

Example Usage

<div
    x-data="{ images: ['./image1.jpg', './image2.jpg', './image3.jpg'] }"
    x-init="$lightbox(images)"
></div>

If there are also lightbox items created via x-lightbox targeting the same group (default or named), the items will be merged.

$lightbox.open(urlOrRef, group)

Parameters

Parameter	Type	Default	Description
urlOrRef	string|HTMLElement|null	null	The URL or element ref of the item to open. If null, the first item in the lightbox will be opened.
group	string|null	null	The name of the lightbox group. If null, the default lightbox will be opened.

Example Usage

<img src="#" x-lightbox="'./image.jpg'" x-ref="image" alt="Example image">

<a href="#" @click="$lightbox.open('./image.jpg')">Open Image</a>
or
<a href="#" @click="$lightbox.open($refs.image)">Open Image</a>

License

This project is licensed under the MIT License. See the LICENSE file for details.