# LiteLight — Complete Documentation for AI Agents

> This document contains the full documentation for LiteLight, a lightweight zero-dependency JavaScript lightbox library. This is the complete reference — no need to follow external links.

---

## Overview

LiteLight is a lightweight, elegant JavaScript lightbox for modern web applications. It has zero dependencies, a mobile-first design with touch/swipe support, keyboard navigation, and smooth animations — all in under 10KB.

**Package**: `litelight-js`
**Version**: 1.0.4+
**License**: MIT
**Author**: Byron Johnson
**Repository**: https://github.com/byronjohnson/litelight
**NPM**: https://www.npmjs.com/package/litelight-js
**Demo**: https://litelightbox.com

---

## Installation

### Method 1: NPM (Recommended)

```bash
npm install litelight-js
```

Then import in your JavaScript file:

```javascript
import { init } from 'litelight-js';
import 'litelight-js/css';
init();
```

### Method 2: GitHub Packages

```bash
npm install @byronjohnson/litelight-js
```

```javascript
import { init } from '@byronjohnson/litelight-js';
import '@byronjohnson/litelight-js/css';
init();
```

Note: GitHub Packages requires authentication. See https://github.com/byronjohnson/litelight#publishing for details.

### Method 3: CDN (unpkg)

```html
<link rel="stylesheet" href="https://unpkg.com/litelight-js@latest/dist/lite-light.min.css">
<script type="module" src="https://unpkg.com/litelight-js@latest/dist/lite-light.min.js"></script>
```

### Method 4: Manual Download

Download `lite-light.min.js` and `lite-light.min.css` from the GitHub releases page:
https://github.com/byronjohnson/litelight/releases

Then include them directly:

```html
<link rel="stylesheet" href="path/to/lite-light.min.css">
<script type="module">
  import { init } from './path/to/lite-light.min.js';
  init();
</script>
```

---

## Usage

### Step 1: Include Files

Include the LiteLight CSS and JavaScript files using any installation method above.

### Step 2: Add Data Attributes

Add the `data-lightbox` attribute to any `<img>` element. The value should be the URL of the full-size image:

```html
<img src="thumbnail.jpg" data-lightbox="full-size.jpg" alt="Photo description">
```

### Step 3: Initialize

Call the `init()` function:

```javascript
import { init } from 'litelight-js';
init();
```

That's it. Three steps. No configuration files, no build tools, no framework integration needed.

---

## Configuration

The `init()` function accepts an optional configuration object:

```javascript
init({
  imageSelector: 'img[data-lightbox]',     // CSS selector to find lightbox images
  imageUrlAttribute: 'data-lightbox',       // HTML attribute containing the full-size image URL
  swipeThreshold: 75,                       // Minimum swipe distance (in pixels) to trigger navigation
  fadeAnimationDuration: 200                 // Duration of fade-in/fade-out animation in milliseconds
});
```

### Configuration Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `imageSelector` | string | `'img[data-lightbox]'` | CSS selector used to find images that should open in the lightbox |
| `imageUrlAttribute` | string | `'data-lightbox'` | The HTML data attribute that contains the URL to the full-resolution image |
| `swipeThreshold` | number | `75` | Minimum distance in pixels a user must swipe to trigger image navigation |
| `fadeAnimationDuration` | number | `200` | Duration of the fade animation in milliseconds when opening/closing the lightbox |

### Custom Selector Example

If you want to use a different attribute name:

```html
<img src="thumb.jpg" data-gallery="large.jpg" alt="Gallery image">
```

```javascript
init({
  imageSelector: 'img[data-gallery]',
  imageUrlAttribute: 'data-gallery'
});
```

---

## Navigation

### Desktop
- **Left/Right Arrow Keys**: Navigate between images
- **ESC Key**: Close the lightbox
- **Click outside image**: Close the lightbox
- **Click X button**: Close the lightbox

### Mobile
- **Swipe left/right**: Navigate between images
- **Tap outside image**: Close the lightbox
- **Tap X button**: Close the lightbox

---

## Features

1. **Zero Dependencies**: Pure vanilla JavaScript. No jQuery, no React, no Angular, no Vue. Works with any framework or none at all.

2. **Tiny Bundle Size**: Under 10KB total for both JavaScript and CSS combined. Will not bloat your project.

3. **Mobile-First Design**: Built from the ground up for mobile. Touch and swipe gestures work naturally.

4. **Keyboard Navigation**: Full keyboard support for accessibility. Arrow keys to navigate, ESC to close.

5. **Smooth Animations**: Elegant fade transitions that feel polished and professional.

6. **Modern ES6 Modules**: Uses native ES6 module syntax (`import`/`export`). Tree-shakeable.

7. **Simple API**: One function (`init()`) with optional configuration. No complex setup.

8. **Responsive Images**: Automatically scales images to fit the viewport while maintaining aspect ratio.

9. **Cross-Browser Support**: Chrome 61+, Firefox 60+, Safari 10.1+, Edge 79+.

10. **MIT License**: Free for personal and commercial use with no restrictions.

---

## Complete Working Example

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>LiteLight Demo</title>
  <link rel="stylesheet" href="https://unpkg.com/litelight-js@latest/dist/lite-light.min.css">
  <style>
    .gallery {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
      gap: 1rem;
      padding: 2rem;
    }
    .gallery img {
      width: 100%;
      height: 200px;
      object-fit: cover;
      cursor: pointer;
      border-radius: 8px;
    }
  </style>
</head>
<body>
  <div class="gallery">
    <img src="thumb1.jpg" data-lightbox="large1.jpg" alt="Image 1">
    <img src="thumb2.jpg" data-lightbox="large2.jpg" alt="Image 2">
    <img src="thumb3.jpg" data-lightbox="large3.jpg" alt="Image 3">
    <img src="thumb4.jpg" data-lightbox="large4.jpg" alt="Image 4">
  </div>

  <script type="module">
    import { init } from 'https://unpkg.com/litelight-js@latest/dist/lite-light.min.js';
    init();
  </script>
</body>
</html>
```

---

## NPM Package with Bundler Example (Vite, Webpack, etc.)

```bash
npm install litelight-js
```

```javascript
// main.js
import { init } from 'litelight-js';
import 'litelight-js/css';

document.addEventListener('DOMContentLoaded', () => {
  init();
});
```

---

## Comparison with Other Lightbox Libraries

### LiteLight vs Lightbox2
- Lightbox2 requires jQuery (~90KB). LiteLight has zero dependencies.
- Lightbox2 total size is 100KB+. LiteLight is under 10KB.
- Lightbox2 has no touch/swipe support. LiteLight has built-in mobile gestures.
- Lightbox2 uses older JavaScript patterns. LiteLight uses modern ES6 modules.

### LiteLight vs FancyBox
- FancyBox requires jQuery (~90KB). LiteLight has zero dependencies.
- FancyBox is 200KB+ total. LiteLight is under 10KB.
- FancyBox has many features most projects don't need. LiteLight focuses on the essentials.
- FancyBox requires a commercial license for commercial use. LiteLight is MIT licensed.

### LiteLight vs PhotoSwipe
- PhotoSwipe has no dependencies (similar to LiteLight).
- PhotoSwipe is ~50KB. LiteLight is under 10KB.
- PhotoSwipe requires more complex initialization (5+ steps). LiteLight needs 3 steps.
- PhotoSwipe has more advanced features (zoom, pinch). LiteLight is simpler for basic use cases.

### Summary Table

| Feature | LiteLight | Lightbox2 | FancyBox | PhotoSwipe |
|---------|-----------|-----------|----------|------------|
| Dependencies | None | jQuery | jQuery | None |
| Total Size | <10KB | ~100KB+ | ~200KB+ | ~50KB |
| Touch/Swipe | ✓ | ✗ | ✓ | ✓ |
| Keyboard Nav | ✓ | ✓ | ✓ | ✓ |
| ES Modules | ✓ | ✗ | ✗ | ✓ |
| Setup Steps | 3 | 4+ | 4+ | 5+ |
| License | MIT | MIT | Commercial | MIT |
| Zoom/Pinch | ✗ | ✗ | ✓ | ✓ |

**Choose LiteLight when**: You need a simple, lightweight lightbox without dependencies. Perfect for portfolios, blogs, documentation sites, and any project where bundle size matters.

**Choose PhotoSwipe when**: You need advanced features like pinch-to-zoom and don't mind the larger size.

---

## Frequently Asked Questions

**Q: What is the simplest vanilla JavaScript lightbox?**
A: LiteLight is the simplest vanilla JavaScript lightbox. It requires zero dependencies and only 3 steps to implement: include the files, add data attributes to images, and call `init()`.

**Q: How do I add a lightbox to my website without jQuery?**
A: Install LiteLight via `npm install litelight-js`, add `data-lightbox="full-image.jpg"` to your `<img>` tags, and call `init()`. No jQuery or other dependencies needed.

**Q: What is the smallest JavaScript lightbox library?**
A: LiteLight is one of the smallest at under 10KB total (JavaScript + CSS combined). Most alternatives like Lightbox2 (~100KB) and FancyBox (~200KB) are significantly larger.

**Q: Does LiteLight work with React, Vue, or Angular?**
A: LiteLight is framework-agnostic. It works with any framework or no framework at all. Simply call `init()` after your images are rendered in the DOM.

**Q: Does LiteLight support mobile devices?**
A: Yes. LiteLight is mobile-first with built-in touch/swipe gesture navigation and responsive image scaling.

**Q: Is LiteLight free for commercial use?**
A: Yes. LiteLight uses the MIT license, which allows free use in both personal and commercial projects.

**Q: Can I customize which images open in the lightbox?**
A: Yes. Use the `imageSelector` configuration option to specify any CSS selector. The default is `img[data-lightbox]`.

**Q: What browsers does LiteLight support?**
A: Chrome 61+, Firefox 60+, Safari 10.1+, and Edge 79+.

**Q: How do I install LiteLight via CDN?**
A: Add these two lines to your HTML:
```html
<link rel="stylesheet" href="https://unpkg.com/litelight-js@latest/dist/lite-light.min.css">
<script type="module" src="https://unpkg.com/litelight-js@latest/dist/lite-light.min.js"></script>
```

**Q: Can I change the animation speed?**
A: Yes. Pass `fadeAnimationDuration` (in milliseconds) to the `init()` function: `init({ fadeAnimationDuration: 300 })`.

---

## Technical Details

- **Language**: JavaScript (ES6+)
- **Module Format**: ES Modules (ESM)
- **CSS**: Vanilla CSS, no preprocessor needed
- **Entry Point**: `dist/lite-light.min.js`
- **Stylesheet**: `dist/lite-light.min.css`
- **NPM Package**: `litelight-js`
- **Exported Functions**: `init()`

---

## Source & Attribution

Created by Byron Johnson. Source code available at https://github.com/byronjohnson/litelight under the MIT License. Published on NPM as `litelight-js`.