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

Current Version: 3.3.0

Documentation Demo


Include the following resources on your page before initializing:

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


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

bower install Boxer


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
labels.close string 'Close' Close button text
labels.count string 'of' Gallery count separator text 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


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 are publicly available to all active instances, unless otherwise stated.


Closes active instance of plugin



Sets default plugin options

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


Removes plugin bindings



Triggers resize of instance

Parameter Type Default Description
height int | false Target height or false to auto size
width int | false Target width or false to auto size


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

<a href="image.jpg" class="boxer" title="Caption">
	<img src="thumbnail.jpg" alt="Thumbnail" />


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 href="image_2.jpg" class="boxer" title="Caption Two" data-gallery="gallery">
    <img src="thumbnail_2.jpg" alt="Thumbnail Two" />

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="" data-gallery="videos" title="">YouTube Video</a>
// OR
<a href="" data-gallery="videos" title="">Vimeo Video</a>


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

    mobile: true

Fixed Positioning

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

    fixed: true

Top Positioning

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

    top: 50

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">

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 = $("


"); // OR $obj = $("<div />").load(""); $.boxer($obj);


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

<a href="" class="boxer">Example</a>

Local iFrame

You can also link to local iFrames:

<a href="iframe.html" class="boxer">Example</a>


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="" class="boxer" data-boxer-height="500" data-boxer-width="500">Example</a>

Caption Formating

To customize the caption markup:

    formatter: formatCaptions

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

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.

    retina: true
<a href="image-2x.jpg" class="boxer" title="Caption - Retina">
    <img src="thumbnail-2x.jpg" alt="Thumbnail - Retina" />