- Skip to main content
- Skip to "About this site"

# Lightbox

Questions or comments?

## Purpose

Display images and other content in a dialog box, either individually or as part of a gallery. Implements the WAI-ARIA Dialog (Modal) design pattern.

## Working example

- English example
- French example

## How to implement

### Single items

1. Add a link element to the page with the class `wb-lbx`.
2. Add an `href` attribute on the link element that points to the image (e.g., `href="demo/1_b.jpg"`), the file containing the content (e.g., `ajax/ajax.html`), an element within the file containing the content (e.g., `ajax/ajax.html#element`) or the id of the inline content (e.g., `href="#inline-content`).
3. Add a `title` attribute to the link element with the caption text.
4. Optional: Filter the content using the URL hash (`ajax/ajax4-en.html#filter-id`, v4.0.7+) or a selector (`href="ajax/ajax4-en.html" data-wb-lbx='{"filter": ".filter-selector"}'`, v4.0.12+).

### Galleries

1. Add a `section` or other element to the page with the classes `wb-lbx` and `lbx-gal`.
2. Add within the `section` or other element a link element for each item in the gallery.
3. Add an `href` attribute on each link element that points to the image (e.g., `href="demo/1_b.jpg"`), the file containing the content (e.g., `ajax/ajax.html`), an element within the file containing the content (e.g., `ajax/ajax.html#element`) or the id of the inline content (e.g., `href="#inline-content`).
4. Add a `title` attribute to each link element with the caption text.

## Configuration options

Option | Description | How to configure | Values
--- | --- | --- | ---
`lbx-hide-gal` | Hides all but the first item in the gallery. | Add `lbx-hide-gal` to the `class` attribute of the `section` or other element of the gallery. | n/a
`lbx-modal` | Make the lightbox behave like a modal dialog. | Add `lbx-modal` to the `class` attribute of the link element. | n/a
`lbx-ajax` | Overrides the default content type with the ajax content type. | Add `lbx-ajax` to the `class` attribute of the link element. | n/a
`lbx-image` | Overrides default content type with the image content type. | Add `lbx-image` to the `class` attribute of the link element. | n/a
`lbx-inline` | Overrides default content type with the inline content type. | Add `lbx-inline` to the `class` attribute of the link element. | n/a
`lbx-iframe` | Overrides default content type with the iframe content type. | Add `lbx-iframe` to the `class` attribute of the link element. | n/a
`popup-modal-dismiss` | Identifies the button that is to be used to close a lightbox behaving like a modal dialog. | Add `popup-modal-dismiss` to the link or button that will be used to close the lightbox behaving like a modal dialog. | n/a
`data-wb-lbx` | Magnific Popup settings can be set through the `data-wb-lbx` attribute or `window[ "wb-lbx" ]`. See Magnific Popup documentation for possible options. Note: WET uses the open, change and parseAjax callbacks (See Events). | Add `data-wb-lbx` attribute to the link element with the options. | e.g., `data-wb-lbx='{"type": "ajax"}'` will set the content type. Will have the same result as adding the `lbx-ajax` class.
`filter` (v4.0.12+) | Content can be filtered by a selector through the `filter` property in the `data-wb-lbx` attribute or `window[ "wb-lbx" ]`. | Add `data-wb-lbx='{"filter": ".filter-selector"}'` to the link element, replacing `.filter-selector` by a selector. | e.g., `data-wb-lbx='{"filter": ".filter-selector"}'` will filter the content by `.filter-selector`.

## Events

Document the public events that can be used by implementers or developers.

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-lbx` | Triggered manually (e.g., `$( ".wb-lbx" ).trigger( "wb-init.wb-lbx" );`). | Used to manually initialize the Lightbox plugin. Note: The Lightbox plugin will be initialized automatically unless the Lightbox markup is added after the page has already loaded.
`wb-ready.wb-lbx` (v4.0.5+) | Triggered automatically after a lightbox is initialized. | Used to identify when a lightbox has initialized (target of the event)
    $( document ).on( "wb-ready.wb-lbx", ".wb-lbx", function( event ) {
    });
    $( ".wb-lbx" ).on( "wb-ready.wb-lbx", function( event ) {
    });
`wb-open.wb-lbx` (v4.0.4+) | Triggered manually:
    $( document ).trigger( "open.wb-lbx", items, modal, image, ajax (v4.0.16+) );
The `items` parameter is required while the `modal`, `image` and `ajax` parameters are optional. Note that the `ajax` parameter was added in v4.0.16. The following is an example usage:
    $( document ).trigger( "open.wb-lbx", [
    	[
    		{
    			src: "demo/1_b.jpg",
    			type: "image"
    		}
    	],
    	false,
    	[
    		"Image 1"
    	],
    	{
    		settings: {
    			type: 'POST',
    			data: {
    				foo: 'bar'
    			}
    		}
        }
    ]);
| Used to manually open a Lightbox popup. Can be used to load single popups, galleries and modal popups. See Opening popups through JavaScript for working examples.
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });
- `mfp*` events (e.g., `mfpClose` | Events triggered automatically by Magnific Popup (documentation on Magnific Popup events. | Used by Magnific Popup to identify what events are occurring. `$.magnificPopup.instance` contains the properties of the popup in question. Opened with `.wb-lbx`:
      $( ".wb-lbx" ).on( "mfpClose", function( event ) {
      	var src = $.magnificPopup.instance.items[ 0 ].src;

      	if ( src === "#inline_content" ) {
      	} else if ( src === "demo/1_b.jpg" ) {
      	}
      });
- Opened with JavaScript:
      $( document ).on( "mfpClose", function( event ) {
      	var src = $.magnificPopup.instance.items[ 0 ].src;

      	if ( src === "#inline_content" ) {
      	} else if ( src === "demo/1_b.jpg" ) {
      	}
      });

## Source code

Lightbox source code on GitHub

Date modified:
  2015-07-09