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/[email protected]/dist/alpine-tailwind-lightbox.min.js"></script>

<!-- Focus Plugin -->
<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/[email protected]/dist/cdn.min.js"></script>

<!-- AlpineJS Core -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/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.