Lightbox2 Documentation

To set up a local development environment for Lightbox2, follow these steps:

1. Install dependencies using npm install.
2. Run linting/tests using npm test.
3. Build the project using npm run build.
4. Start a local server (for example, using npx serve .) and navigate to /examples/index.html to view the project in action.

Lightbox2 can now be used as a standalone vanilla JavaScript library without requiring jQuery. This is achieved by using the standard UMD bundle. If you require backwards compatibility with existing jQuery-based workflows, you can use the lightbox-plus-jquery.js bundle, which concatenates jQuery before the vanilla lightbox code.

Key Benefits:

• Reduced bundle size (removes 30KB+ of jQuery).
• No dependency on jQuery for DOM manipulation or events.
• The public API remains identical to previous versions.

Lightbox2 includes a sanitizeTitle option to prevent XSS attacks when using user-generated content in captions.

Note: In recent updates, sanitizeTitle defaults to true. If you rely on injecting raw HTML into your captions via the data-title attribute, you may need to explicitly configure this (though be aware of the security implications).

To customize the appearance of Lightbox2 without overriding numerous specific selectors, you can use CSS custom properties (variables). The following variables are recommended for theming:

• --lb-overlay-opacity: Controls the opacity of the lightbox overlay.
• --lb-border-radius: Sets the border radius for the lightbox container.
• --lb-image-border: Defines the border style for the displayed image.
• --lb-transition-speed: Sets the duration for CSS transitions.

:root {
  --lb-overlay-opacity: 0.8;
  --lb-border-radius: 3px;
  --lb-image-border: 4px solid white;
  --lb-transition-speed: 0.6s;
}

Lightbox2 uses CSS custom properties to control animation durations. You can override these in your global CSS to customize the feel of transitions.

Available CSS variables:

• --lb-fade-duration: Controls the fade duration for the overlay and lightbox.
• --lb-image-fade-duration: Controls the fade duration for the image itself.
• --lb-resize-duration: Controls the duration of the container resizing animations.

:root {
  --lb-fade-duration: 600ms;
  --lb-image-fade-duration: 600ms;
  --lb-resize-duration: 700ms;
}

Future updates to the v2.x branch aim to expose a public API for controlling the lightbox via JavaScript and emitting events for integration with other components (like analytics or routing).

Planned Public Methods:

• open(imageUrl, options): Opens the lightbox at a specific URL.
• close(): Closes the lightbox.
• next(): Navigates to the next image.
• prev(): Navigates to the previous image.
• destroy(): Removes the lightbox DOM and event listeners (essential for SPAs).

Planned Events (via jQuery custom events):

• lightbox:open
• lightbox:close
• lightbox:change

Lightbox2 uses native CustomEvent for its lifecycle events. You can listen for these events on the document object to trigger custom logic when the lightbox state changes.

Supported events:

• lightbox:open
• lightbox:close
• lightbox:change

The public API for Lightbox2 is identical whether you are using the vanilla or jQuery-dependent version. You can control the lightbox programmatically using the following methods:

• lightbox.open(url): Opens the lightbox with the specified image URL.
• lightbox.close(): Closes the active lightbox.
• lightbox.next(): Navigates to the next image in the set.
• lightbox.prev(): Navigates to the previous image in the set.
• lightbox.destroy(): Destroys the lightbox instance and cleans up event listeners.
• lightbox.option(options): Updates lightbox configuration options.