LighterBox

A very lightweight lightbox with a bare minimum of features, packaged for the Rails asset pipeline:

• Displays a single image (with caption) or arbitrary content loaded via Ajax.
• Fully accessible (note that all UI alt texts and titles are in german).
• Gallery mode (navigation between related images / contents).
• Fullscreen mode for small screen devices (see below).
• Supports nested lightboxes.

On small screen devices the lightbox will be shown fullscreen, with a fixed header bar containing the close button (and gallery buttons, if applicable). Per default this mode is activated for screens narrower than 480px (can be customized by setting --lighter-box-fullscreen-breakpoint in your CSS).

Requirements and Compatibility

LighterBox requires jQuery. It is designed to work with all modern browsers.

Installation

npm install @die-antwort/lighter_box --save

Usage

Create a new instance of LighterBox.Ajax or LighterBox.Image, with the link element referencing the target image or content as parameter.

A common pattern is to do this in a event handler like this:

$("body").on "click", "a[data-lightbox]", (ev) ->
  ev.preventDefault()
  if $(this).data("lightbox-mode") == "ajax"
    new LighterBox.Ajax(this)
  else
    new LighterBox.Image(this)

Configuration via attributes

The following attributes on the source element (link) can be used to customize LighterBox:

• data-lightbox-class: Additional css class names for the lightbox modal.
• data-lightbox-group: Used for gallery mode: Next / previous links will be displayed to allow navigation between lightboxes for source elements that share the save value for this attribute. Hidden source elements are ignored, so the gallery mode works well with all sorts of client side filtering. Note that this feature relies on jQuery’s :visible selector, which might yield unexpected results (eg. for links wrapping block elements, see jquery/jquery#2227).
• data-lightbox-href: The URL that to be loaded into the lightbox. If not set, the link’s href attribute is used. If used with an image lightbox, this URL must also point to an image (common usecase: the link points to the original image file, but the lightbox should display a smaller version of the image instead).

Image lightbox only:

• data-lightbox-caption: Image caption. If not set, the image’s alt text is used as caption.
• data-lightbox-caption-allow-html: If present, the image caption is interpreted as HTML.

Ajax lightbox only:

• data-lightbox-fragment: A jQuery selector to specify the portion of the remote document to be loaded into the lightbox (similar to the fragment feature of jQuery.load()).

Events

The following events will be triggered on the lightbox modal element:

• lighter-box-content-loaded: When the content has been completely loaded (lightbox already visible).
• lighter-box-will-hide: Before the lightbox elements (modal, container and backdrop) are removed from the DOM.

Event handlers will get passed the lightbox instance as second parameter (after the event object).

Styling

Depending on your site’s CSS you may need specify a custom z-index value for lightbox and backdrop. Set --lighter-box-z-index to an appropriate value in your application’s CSS.

There are some more custom properties that can be set, see dist/lighter_box.css for a full list.