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

Evaluation and report

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
mfp-hide Hides inline popup content. Add mfp-hide to the class attribute of the popup's section element. n/a
modal-dialog Restrict width of the popup. Add modal-dialog to the class attribute of the popup's section element. n/a
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. If target attribute is set, the dialog box will be closed automatically when the user leaves the web page. 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" ) {
	}
});

Test case

Click on the same page link
Ensuring the dialog close when clicking on a link inside the opened dialog that are pointing to a location outside the dialog context, like futher down in the page.

Source code

Lightbox source code on GitHub

Date modified: