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"></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. You can also turn the caption into a link by adding a data-link attribute to your image and inserting a fully qualified URL into it.
<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 for each <figure>
'schema' : true, // Use schema.org markup (i.e., itemtype, itemprop)
'mode' : 'default', // default | stacked | animated | hidden (deprecated: hide)
'debug_mode' : false, // Output debug info to the JS console
'force_dimensions': true, // Force the dimensions in case they cannot be detected (e.g., image is not yet painted to viewport)
'is_responsive' : false, // Ensure the figure and image change size when in responsive layout. Requires a container to control responsiveness!
'inherit_styles' : false // Have the caption.js container inherit box-model properties from the original image
});
});
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. If you have images which are initially hidden when the page is loaded (or if you're experiencing weird behaviors/sizing with the captions), set the 'force_dimensions' option to true so that caption.js can correctly detect the size of your images. If you have a responsive site, enable 'is_responsive' to ensure the figure will enlarge and shrink with your layout — just be sure to wrap the original image in a responsive container. Finally, the inherit_styles property will attempt to copy any box model properties from your original image to the caption.js container (that way you don't have to add any addition styles yourself).
Examples
The first example is the default mode, in which the caption sits below the image. There is also a link added to the caption using the image&rsuo; data-link attribute.
The second example shows how captions can be stacked on top of the image using the stacked mode.
The third mode, hidden, has a caption that slides down when a user hovers over the photo, allowing the image to be seen unobscured.
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.
If you’re using caption.js in a responsive setting, be sure to enable the is_responsive setting, and make sure your original image is wrapped in a responsive container (in other words, the direct parent container should be responsive, or have a variable width). See below for an example.
