Orginally Posted March 2, 2009 | Last Updated November 4, 2009



jCaption is a jQuery plugin designed to make adding captions to a page dead simple. It takes an image element and uses one of its attributes to build the markup for a caption. It allows for both arbitrary styling and markup.

Dealing with image captions on the web can be a big pain. The code structure for nearly any caption looks something like the following:

<div> <img src="image.gif" alt="" /> <p>Caption Text</p> </div>

While writing such markup for every image is merely an inconvenience for web developers, it is an impossibility for most of thier clients. Many clients use a web-based WYSIWYG editor to create and edit their pages through a CMS. It would be nearly impossible to expect them to add this markup around their images.

This was a problem I faced when building a site for a client. I found well-concepted solution in Captify, but I found it too restrive for my needs. I proceeded by writing a version that met the following requirements:

Follow jQuery Conventions - Animations shouldn't be handled by passing in a string, instead arbitrary animations should be allowed. Markup Should be Arbitrary - Other than the tag that is required, other markup should be arbitrary. Optionally Allow Placement From Text-Editors - Web-Editors like tinyMCE or FCKditor allow users to align images to the left or right of text. Depending on the version, this is accomplished using the "align" attribute or "style" attribute. This plugin accomodates both and makes sure that the caption is correctly placed as well.

Using the plugin

Using the plugin is dead simple. Just use apply the .jcaption() method to the images you want:

$('img').jcaption();

By default this will take the following image:

<img src="image.jpg" alt="Some caption text" />

and produce the following markup:

<div class="caption"> <img src="image.jpg" alt="Some caption text" /> <p>Some caption text</p> </div>

The options will allow you to control the elements and classes that the plugin produces. Additionally, to accomodate text editors, the plugin can copy the styling that was applied to the image to the caption instead, and take the images "align" attribute and append it to the caption class. So for text editors that place images using align="left" you can instead have the plugin add "left" as a class to the caption so that you can place the entire caption using your stylesheet.

Options

$('img').jcaption({ //Element to wrap the image and caption in wrapperElement: 'div', //Class for wrapper element wrapperClass: 'caption', //Caption Element captionElement: 'p', //Attribute of image to use as caption source imageAttr: 'alt', //If true, it checks to make sure there is caption copy before running on each image requireText: true, //Should inline style be copied from img element to wrapper copyStyle: false, //Strip inline style from image removeStyle: true, //Strip align attribute from image removeAlign: true, //Assign the value of the image's align attribute as a class to the wrapper copyAlignmentToClass: false, //Assign the value of the image's float value as a class to the wrapper copyFloatToClass: true, //Assign a width to the wrapper that matches the image autoWidth: true, //Animate on hover over the image animate: false, //Show Animation show: {opacity: 'show'}, showDuration: 200, //Hide Animation hide: {opacity: 'hide'}, hideDuration: 200 });

You'll see that any arbitrary animations are possible by setting up the options in this manner.

Demo

View a Demo of this plugin with and without animations here. The captions on the left are animated and the caption on the right is not.

Download the plugin

This plugin has been tested in IE 6 and 7, Firefox 2 and 3, Safari and Chrome.

Updated Sept. 2, 2009 - Added CopyFloattoClass, improved some documentation and changed defaults to reflect the current state of text editors.

Updated Nov. 4, 2009 - Added requireText, allowing the plugin to be run even if there is no caption text.

Download a zip of the plugin and the sample.