alpine-tailwind-lightbox

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #golang #android #docker #nodejs #macos #java #windows #awesome #kubernetes #vue #ios

alpine-tailwind-lightbox

(★ 31)

A simple lightbox for AlpineJS and Tailwind CSS projects.

alpine-tailwind-lightbox Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A simple lightbox for AlpineJS and Tailwind CSS projects.

### Prerequisites

* [AlpineJS](https://alpinejs.dev/essentials/installation) (3.x)
* [AlpineJS Focus Plugin](https://alpinejs.dev/plugins/focus)
* [Tailwind CSS](https://tailwindcss.com/docs/installation) (3.x, 4.x)

### Table of Contents

* [Installation](#installation)
* [Demo](#demo)
* [Usage](#usage)
* [Config Object](#config-object)
* [Magics](#magics)
* [License](#license)

## Installation

#### CDN

```html

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

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

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

#### Module

Install the package:

```shell
npm install alpine-tailwind-lightbox
```

Then import and initialize the plugin:

```js
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 CSS config:

```css
/* Relative path to node_modules */
@source '../node_modules/alpine-tailwind-lightbox/src/template.html';
```

Or `tailwind.config.js` if you are using Tailwind 3.x:

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

[View Demo](https://oli-laban.github.io/alpine-tailwind-lightbox/)
## 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.

```html
<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](#config-object) reference):

```html
<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:

```html
<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):

```html
<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](#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` | `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

```html
<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

```html
<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>
```

## Global Options

| Option        | Type           | Default | Description                                                                                                              |
|---------------|----------------|----|--------------------------------------------------------------------------------------------------------------------------|
| **container** | `string\|null` | `null`  | A CSS selector for the element the lightbox should be appended to. If null, the lightbox will be appended to the `body`. |

Using global options differs depending on whether you are using the module or CDN build.

#### Module

Use the `.configure` method when registering the plugin:

```js
Alpine.plugin(lightbox.configure({ container: '#lightbox-container' }))
```

#### CDN

Declare a global variable in your HTML **before** the CDN script:

```html
<script>
    window.AlpineLightboxConfig = { container: '#lightbox-container' }
</script>
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

alpine-tailwind-lightbox

alpine-tailwind-lightbox Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

alpine-tailwind-lightbox

alpine-tailwind-lightbox Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README