---
{
	"title": "Lightbox",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "Display images and other content in a dialog box, either individually or as part of a gallery.",
	"altLangPrefix": "lightbox",
	"dateModified": "2015-07-09"
}
---
<span class="wb-prettify all-pre hide"></span>

<section>
	<h2>Purpose</h2>
	<p>Display images and other content in a dialog box, either individually or as part of a gallery. Implements the <a href="https://www.w3.org/TR/wai-aria-practices/#dialog_modal">WAI-ARIA Dialog (Modal) design pattern</a>.</p>
</section>

<section>
	<h2>Working example</h2>
	<ul>
		<li><a href="../../../demos/lightbox/lightbox-en.html">English example</a></li>
		<li><a href="../../../demos/lightbox/lightbox-fr.html">French example</a></li>
	</ul>
	<div lang="en">
		<h2>Evaluation and report</h2>
		<ul>
			<li>Accessibility pre-assessment #1
				<ul>
					<li><a href="../../../demos/lightbox/reports/pre-a11y-1-en.html" hreflang="en">English report</a></li>
					<li><a href="../../../demos/lightbox/reports/pre-a11y-1-fr.html" hreflang="fr">French report</a></li>
				</ul>
			</li>
		</ul>
	</div>
</section>

<section>
	<h2>How to implement</h2>
	<section>
		<h3>Single items</h3>
		<ol>
			<li>Add a link element to the page with the class <code>wb-lbx</code>.</li>
			<li>Add an <code>href</code> attribute on the link element that points to the image (e.g., <code>href="demo/1_b.jpg"</code>), the file containing the content (e.g., <code>ajax/ajax.html</code>), an element within the file containing the content (e.g., <code>ajax/ajax.html#element</code>) or the id of the inline content (e.g., <code>href="#inline-content</code>).</li>
			<li>Add a <code>title</code> attribute to the link element with the caption text.</li>
			<li><strong>Optional:</strong> Filter the content using the URL hash (<code>ajax/ajax4-en.html#filter-id</code>, v4.0.7+) or a selector (<code>href="ajax/ajax4-en.html" data-wb-lbx='{"filter": ".filter-selector"}'</code>, v4.0.12+).</li>
		</ol>
	</section>
	<section>
		<h3>Galleries</h3>
		<ol>
			<li>Add a <code>section</code> or other element to the page with the classes <code>wb-lbx</code> and <code>lbx-gal</code>.</li>
			<li>Add within the <code>section</code> or other element a link element for each item in the gallery.</li>
			<li>Add an <code>href</code> attribute on each link element that points to the image (e.g., <code>href="demo/1_b.jpg"</code>), the file containing the content (e.g., <code>ajax/ajax.html</code>), an element within the file containing the content (e.g., <code>ajax/ajax.html#element</code>) or the id of the inline content (e.g., <code>href="#inline-content</code>).</li>
			<li>Add a <code>title</code> attribute to each link element with the caption text.</li>
		</ol>
	</section>
</section>

<section>
	<h2>Configuration options</h2>
	<table class="table">
		<thead>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>How to configure</th>
				<th>Values</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>mfp-hide</code></td>
				<td>Hides inline popup content.</td>
				<td>Add <code>mfp-hide</code> to the <code>class</code> attribute of the popup's <code>section</code> element.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>modal-dialog</code></td>
				<td>Restrict width of the popup.</td>
				<td>Add <code>modal-dialog</code> to the <code>class</code> attribute of the popup's <code>section</code> element.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>lbx-hide-gal</code></td>
				<td>Hides all but the first item in the gallery.</td>
				<td>Add <code>lbx-hide-gal</code> to the <code>class</code> attribute of the <code>section</code> or other element of the gallery.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>lbx-modal</code></td>
				<td>Make the lightbox behave like a modal dialog.</td>
				<td>Add <code>lbx-modal</code> to the <code>class</code> attribute of the link element.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>lbx-ajax</code></td>
				<td>Overrides the default content type with the ajax content type.</td>
				<td>Add <code>lbx-ajax</code> to the <code>class</code> attribute of the link element.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>lbx-image</code></td>
				<td>Overrides default content type with the image content type.</td>
				<td>Add <code>lbx-image</code> to the <code>class</code> attribute of the link element.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>lbx-inline</code></td>
				<td>Overrides default content type with the inline content type.</td>
				<td>Add <code>lbx-inline</code> to the <code>class</code> attribute of the link element.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>lbx-iframe</code></td>
				<td>Overrides default content type with the iframe content type.</td>
				<td>Add <code>lbx-iframe</code> to the <code>class</code> attribute of the link element.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>popup-modal-dismiss</code></td>
				<td>Identifies the button that is to be used to close a lightbox behaving like a modal dialog.</td>
				<td>Add <code>popup-modal-dismiss</code> 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.</td>
				<td>n/a</td>
			</tr>
			<tr>
				<td><code>data-wb-lbx</code></td>
				<td>Magnific Popup settings can be set through the <code>data-wb-lbx</code> attribute or <code>window[ "wb-lbx" ]</code>. See <a href="https://dimsemenov.com/plugins/magnific-popup/documentation.html#options">Magnific Popup documentation</a> for possible options.<br /><strong>Note:</strong> WET uses the open, change and parseAjax callbacks (See <a href="https://dimsemenov.com/plugins/magnific-popup/documentation.html#events">Events</a>).</td>
				<td>Add <code>data-wb-lbx</code> attribute to the link element with the options. </td>
				<td>e.g., <code>data-wb-lbx='{"type": "ajax"}'</code> will set the content type. Will have the same result as adding the <code>lbx-ajax</code> class.</td>
			</tr>
			<tr>
				<td><code>filter</code> (v4.0.12+)</td>
				<td>Content can be filtered by a selector through the <code>filter</code> property in the <code>data-wb-lbx</code> attribute or <code>window[ "wb-lbx" ]</code>.</td>
				<td>Add <code>data-wb-lbx='{"filter": ".filter-selector"}'</code> to the link element, replacing <code>.filter-selector</code> by a selector.</td>
				<td>e.g., <code>data-wb-lbx='{"filter": ".filter-selector"}'</code> will filter the content by <code>.filter-selector</code>.</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Events</h2>
	<p>Document the public events that can be used by implementers or developers.</p>
	<table class="table">
		<thead>
			<tr>
				<th>Event</th>
				<th>Trigger</th>
				<th>What it does</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>wb-init.wb-lbx</code></td>
				<td>Triggered manually (e.g., <code>$( ".wb-lbx" ).trigger( "wb-init.wb-lbx" );</code>).</td>
				<td>Used to manually initialize the Lightbox plugin. <strong>Note:</strong> The Lightbox plugin will be initialized automatically unless the Lightbox markup is added after the page has already loaded.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb-lbx</code> (v4.0.5+)</td>
				<td>Triggered automatically after a lightbox is initialized.</td>
				<td>Used to identify when a lightbox has initialized (target of the event)
					<pre><code>$( document ).on( "wb-ready.wb-lbx", ".wb-lbx", function( event ) {
});</code></pre>
					<pre><code>$( ".wb-lbx" ).on( "wb-ready.wb-lbx", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-open.wb-lbx</code> (v4.0.4+)</td>
				<td>Triggered manually:
					<pre><code>$( document ).trigger( "open.wb-lbx", items, modal, image, ajax (v4.0.16+) );</code></pre>
					<p>The <code>items</code> parameter is required while the <code>modal</code>, <code>image</code> and <code>ajax</code> parameters are optional. Note that the <code>ajax</code> parameter was added in v4.0.16. The following is an example usage:
					<pre><code>$( document ).trigger( "open.wb-lbx", [
	[
		{
			src: "demo/1_b.jpg",
			type: "image"
		}
	],
	false,
	[
		"Image 1"
	],
	{
		settings: {
			type: 'POST',
			data: {
				foo: 'bar'
			}
		}
	}
]);</code></pre>
				</td>
				<td>Used to manually open a Lightbox popup. Can be used to load single popups, galleries and modal popups. See <a href="../../../demos/lightbox/lightbox-en.html#examples5">Opening popups through JavaScript</a> for working examples.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb</code> (v4.0.5+)</td>
				<td>Triggered automatically when WET has finished loading and executing.</td>
				<td>Used to identify when all WET plugins and polyfills have finished loading and executing.
					<pre><code>$( document ).on( "wb-ready.wb", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>mfp*</code> events (e.g., <code>mfpClose</code></td>
				<td>Events triggered automatically by Magnific Popup (<a rel="external" href="https://dimsemenov.com/plugins/magnific-popup/documentation.html#events">documentation on Magnific Popup events</a>.</td>
				<td>Used by Magnific Popup to identify what events are occurring. <code>$.magnificPopup.instance</code> contains the properties of the popup in question.
					<ul>
						<li><strong>Opened with <code>.wb-lbx</code></strong>:
							<pre><code>$( ".wb-lbx" ).on( "mfpClose", function( event ) {
	var src = $.magnificPopup.instance.items[ 0 ].src;

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

	if ( src === "#inline_content" ) {
	} else if ( src === "demo/1_b.jpg" ) {
	}
});</code></pre>
						</li>
					</ul>
				</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Test case</h2>
	<dl>
		<dt><a href="test/click-on-same-page-link.html">Click on the same page link</a></dt>
		<dd>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.</dd>
	</dl>
</section>

<section>
	<h2>Source code</h2>
	<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/plugins/lightbox">Lightbox source code on GitHub</a></p>
</section>
