Boxer

A jQuery plugin for displaying images, videos or content in a modal overlay.

Current Version: 3.2.0


Documentation Demo

Installation

Include the following resources on your page before initializing:

<script src="jquery.fs.boxer.js"></script>
<link href="jquery.fs.boxer.css" rel="stylesheet">

Bower

You can deploy and update via the command line with Bower:

bower install Boxer

Options

Options are set by passing a valid options object at initialization or to the public "defaults" method. You can also set custom options for a specific instance by attaching a data-boxer-options attribute containing a properly formatted JSON object to the target element.

Name Type Default Description
callback function $.noop Funciton called after opening instance
customClass string '' Class applied to instance
extensions array "jpg", "sjpg", "jpeg", "png", "gif" Image type extensions
fixed boolean false Flag for fixed positioning
formatter function $.noop Caption format function
height int 100 Initial height (while loading)
labels.close string 'Close' Close button text
labels.count string 'of' Gallery count separator text
labels.next string 'Next' Gallery control text
labels.previous string 'Previous' Gallery control text
margin int 50 Margin used when sizing (single side)
minHeight int 100 Minimum height of modal
minWidth int 100 Minimum width of modal
mobile boolean false Flag to force 'mobile' rendering
opacity number 0.75 Overlay target opacity
retina boolean false Use 'retina' sizing (half's natural sizes)
requestKey string 'boxer' GET variable for ajax / iframe requests
top int 0 Target top position; over-rides centering
videoRadio number 0.5625 Video height / width ratio (9 / 16 = 0.5625)
videoWidth int 600 Video target width
width int 100 Initial height (while loading)

Events

Events are triggered on the target instance's element, unless otherwise stated.

Option Description
open.boxer Modal opened; triggered on window
close.boxer Modal closed; triggered on window

Methods

Methods are publicly available to all active instances, unless otherwise stated.

close

Closes active instance of plugin

$.boxer("close");

defaults

Sets default plugin options

$.boxer("defaults", opts);
Parameter Type Default Description
opts object {} Options object

destroy

Removes plugin bindings

$(".target").boxer("destroy");

resize

Triggers resize of instance

$.boxer("resize");
Parameter Type Default Description
height int | false Target height or false to auto size
width int | false Target width or false to auto size

Basic

To display a single image simply link to the source. Also, 'title' attributes will automatically populate the caption field:

$(".boxer").boxer();
<a href="image.jpg" class="boxer" title="Caption">
	<img src="thumbnail.jpg" alt="Thumbnail" />
</a>
Demo

Gallery

To display a gallery of images attach a common 'data-gallery' attribute to each item:

<a href="image_1.jpg" class="boxer" title="Caption One" data-gallery="gallery">
    <img src="thumbnail_1.jpg" alt="Thumbnail One" />
</a>
<a href="image_2.jpg" class="boxer" title="Caption Two" data-gallery="gallery">
    <img src="thumbnail_2.jpg" alt="Thumbnail Two" />
</a>
Demo

YouTube & Vimeo Videos

Boxer will auto-detect a YouTube or Vimeo embed URL and render accordingly. Videos can also be included in galleries alongside image.

<a href="http://www.youtube.com/embed/VIDEO_ID" data-gallery="videos" title="">YouTube Video</a>
// OR
<a href="http://player.vimeo.com/video/VIDEO_ID" data-gallery="videos" title="">Vimeo Video</a>
Demo

Mobile

Boxer will automatically render a touch-friendly modal on mobile devices, but you can also force it to always render as mobile:

$(".boxer").boxer({
    mobile: true
});
Demo

Fixed Positioning

To display a more traditional lightbox that locks the window while open:

$(".boxer").boxer({
    fixed: true
});
Demo

Top Positioning

To force the modal to always animate from a standard top position:

$(".boxer").boxer({
    top: 50
});
Demo

In-Line Content

To display a section of inline markup link to the parent element's 'id'. It's important to note that a copy of the matching element's inner markup will be used, so try to avoid using decent elements with id selectors:

<a href="#hidden" class="boxer">Show Content</a>
<div id="hidden" style="display: none;">
    <div class="content">
        ...
    </div>
</div>
Demo

jQuery Objects

You can also display compiled jQuery objects, this is especially usefull when loading partial content or using a templating system. To display a pre-compiled jQuery object, simply pass the new object when calling the plugin.

$obj = $("

Content!

"); // OR $obj = $("<div />").load("http://www.url.com/partial-markup/"); $.boxer($obj);
Demo

iFrame

To display a valid URL in an iFrame simply link to the page:

<a href="http://www.example.com/" class="boxer">Example</a>
Demo

Sizing

When loading inline content or an iFramed URL you can specify the desired dimensions using html data attributes. If no dimensions are specified, or mobile styles are being rendered, the plugin will calculate them based on the current window and content size:

<a href="http://www.example.com/" class="boxer" data-boxer-height="500" data-boxer-width="500">Example</a>
Demo

Caption Formating

To customize the caption markup:

$(".boxer").boxer({
    formatter: formatCaptions
});

function formatCaptions($target) {
	return '<h3>' + $target.attr("title") + '</h3>';
}
Demo

Retina Support

To display images at "retina" quality the original image dimentions of halved, sizing the images to at least 2x pixel-density and ensuring crisp images on your fancy new display.

$(".boxer").boxer({
    retina: true
});
<a href="image-2x.jpg" class="boxer" title="Caption - Retina">
    <img src="thumbnail-2x.jpg" alt="Thumbnail - Retina" />
</a>
Demo