Image Captions in Drupal 7 – A method

Image captions are supposed are a fairly standard item in a web developer’s toolkit. In a modern CMS they seem to be a given. However, Drupal leaves this to the contrib space, as it should, since each site has different needs. However, the lack of an adopted contrib method for achieving image captions was a bit surprising.

With Drupal 7 the media module is used to handle media. No problem, however it doesn’t do anything to allow for automatic captions to appear. However, it does allow us to show users when they upload an image that an alt tag is a good idea and a title tag can be used. Most auto-caption techniques rely on that title tag to be used as the caption and you show it with a bit of javascript and CSS.

My goal for the end user was to have them get captions for free but have the ability to turn them off. I do not want them to assign a special class for a caption to appear because in my use case, the majority of folks want the captions. However, to disable a caption I want a fairly straight forward method that can be accomplished in the WYSIWYG editor.

To make this work I leveraged several contrib modules and now have it working except it still will not automatically show in the WYSIWYG editor. That last issue seems to be somewhere that improvements can still be made.

Ingredients (List of Modules):

  • Media Module 7-x.1.2
  • Insert
  • Image Caption
  • WYSIWYG with the CKeditor Library
  • HTML Purifier (Not needed if you allow full HTML)
  • Any dependencies of the above modules, i.e. ctools, views, etc…


Go ahead and download the modules and install them on your site whatever your preferred method. You can enable them as well.

Now, most of these modules auto-configure themselves. For this example we will use the basic page content type but add an image field.

Basic Page content type
Basic page content type configuration screen.

Notice that we use the image widget which is augmented via the media module. The next screen we need to edit is the images field. Make sure to check the Enable Alt field and Enable Title field.

The alt and title field checkboxes are checked.
Don’t forget to enable the alt and title fields.

Right below those check boxes, if you have the Insert module enabled you will see a collapsed field labeled insert. Expand it. Check the Enable Insert button check box. Choose the styles you want to make available to your users. Add the word “caption” without the quotes to the Additional CSS Classes text field. This will add the caption class to every image inserted into your nodes. This makes the caption magic happen automatically, as long as you fill out the title field with each image, because the image caption module looks for the class caption on all images.

The insert configuration screen.
Enable the insert button, choose some styles, and add caption to the classes field.

Make sure you have the image caption module enabled and let’s make a new test node.

Go to Content -> Add Content -> Basic Page and title your new node to test the image caption.

Then go down to your image field and upload a new image or graphic. Fill in the alt field and the in the title field add the text you want for your caption. Click the insert button near the style dropdown menu and the image appears in your post.

An image field being configured in Drupal 7.

Now, click the preview button and you will see the caption appear beneath your image. Styling the caption class is up to you.


A picture of the author with a caption below.
Look ma’ a caption!

Fairly awesome.

Why this approach:

OK, so why did I decide to do it this way? There are a few other modules, notably jCaption. You could also make each image a node and then attach a caption field to the image. That approach seemed unrealistic as then I would have to easily allow authors to import nodes, into their post in an easy manner. However, the author would have to create at a minimum two nodes/entities just to create a page with one image. That doesn’t entice many people.

jCaption looks interesting except that you cannot turn off captions. Anything with a title attribute gets a caption. Sometimes, captions are not appropriate but people still want the contents of the title attribute to appear on mouseover. With the image caption module because the caption is controlled by a class, the user can edit the image in their WYSIWYG editor and remove the class. In the next image you can see the caption class has been removed, meaning no caption will appear. This gives control to the page creators which is a fundamental goal of CMS.

The advanced property screen of the CKeditor image window.
No caption class means no caption accompanying the image.


I am happy with this approach except for the fact that users cannot see the captions directly in the WYSIWYG. It would be fantastic if that were possible and it will require more research. Since the caption appears because of jQuery we would have to utilize a drupal behavior to fire whenever an image is inserted and then with ajax save the state of the page and add in the caption. It sounds messy.

I wish there was an easier way for users to disable the caption as well. It is not hard to go into the properties of an image but it would be great if they could just click the image and remove the caption class via a dropdown menu or contextual editor.


This seems to be a robust approach that helps the user by minimizing the knowledge and time needed to add captions. I need to find a good way to alert them of how to remove a caption, but I am hopeful for the use of this technique.

4 thoughts on “Image Captions in Drupal 7 – A method

  1. Hi!
    Finally a worthwhile approach to image captions combined with media library functionality..
    I wonder how you get to augment the image widget with media browser?
    I cannot find how to do it.. neither in the admin interface nor by googling.
    Maybe it has to do with my version of some modules, I am using
    Media 7.x-2.0-unstable6
    Image 7.17
    Insert 7.x-1.3

    Hoping for some advice 🙂

  2. Hi Grahmtk,

    What do you mean by augmenting the image widget with the media browser? Since I wrote this post I have been using Media 7.x.2.0-unstable7 and Media-7.x-2.0-dev and they function properly with the caption process outlined above.

    If you mean the dropdown style choices next to the images, double check that you have expanded the Insert fieldset when setting up your content type. Once expanded you can enable the Insert field and associated styles.

    I hope that helps.

Leave a Reply

Your email address will not be published. Required fields are marked *