Fork me on GitHub

caption.js

easily and semantically add captions to images

Quick Start

To begin, make sure you have jQuery included on your page. Next, download the script from above, upload it to your server, and link to it in the <head> section of your page (make sure you adjust the path according to where you uploaded the script on your server).

<script src="jquery.caption.js" type="text/javascript"></script>

You may also put the above code right inside the closing </body> tag to help increase loading times on your site. For more info, see Yahoo!'s article on page speed optimization.

Then, add the CSS to your site.

<link href="captionjs.css" rel="stylesheet"/>

Finally, initialize the plugin within a $(window).load() function as follows:

$(window).load(function() {
	$('img.caption').captionjs();
});

Whatever text you have in an image's data-caption attribute will be the text for the caption.js caption. If no data-caption is set, caption.js will look for text in the image's alt text as a fallback.

<img src="photo.jpg" data-caption="A wonderful caption for the photo."/>

To customize caption.js, see the documentation section below.

Why caption.js?

There are a lot of jQuery-based solutions for putting captions on your page. What sets caption.js apart from the rest is that, instead of wrapping your images layers deep in divs, it adds captions using semantic markup (i.e., figure and figcaption tags).

Using semantic markup not only helps organize your code, it aids in accessibility for people using assistive devices to view websites and helps in SEO by feeding search engines meaningful, structured code.

Documentation

$(window).load(function() {
	$('img.caption').captionjs({
		'class_name'      : 'captionjs', // Class name assigned to each <figure>
		'schema'          : true,        // Use schema.org markup (i.e., itemtype, itemprop)
		'mode'            : 'default',   // default | static | animated | hide
		'debug_mode'      : false,       // Output debug info to the JS console
		'force_dimensions': false        // Force the dimensions in case they can't be detected (e.g., image is not yet painted to viewport)
	});
});

Since you’ll probably like to customize the <figure> elements that caption.js generates, you can set a custom class for them (or just use the default captionjs class). caption.js also features four different modes, which are shown in the examples below. For diagnosing problems, a debug mode is available. Finally, if you have images which are initially hidden when the page is loaded, set the 'force_dimensions' option to true so that caption.js can correctly detect the size of your images.

Examples

The first example is the default mode, in which the caption sits below the image.

The second example shows how captions can be stacked on top of the image using the stacked mode.

The third mode, hide, has a caption that slides down when a user hovers over the photo, allowing the image to be seen unobscured.

Two climbers in the Bernese Alps of Switzerland stand on a precipice across from a large mountain peak shrouded in clouds called the Mönch.

The last mode, animated, features an animated caption that appears when the user hovers over the image. Also, in this example, the caption text comes from the image's alt text rather than its data-caption attribute, as is the case for the other examples.

Contribute

Want to help build out caption.js? Come on by on our Github project page. If you have an update you'd like to see implemented, just send a pull request.