The Plugin

What is it?

The image overlay plugin is a simple jQuery plugin that attempts to present an image with an overlaid title/caption. The overlay drops in on hover, as you can see above.

This plugin is based upon the great demos of this technique available from build internet. Thanks for the inspiration, guys!


This plugin is hosted on Google Code. Download the latest version here.


There are no known issues with plugin compatability. Tested in IE 6-8, Firefox 3.5, Google Chrome, Apple Safari 4.0, Opera 10.


Questions and comments will be handled through the Google Code site.


1.3 - Added overlay_speed_out option, removed need to specify image width/height.

1.2 - Added animate option.

1.1 - Added always_show_overlay option.

1.0 - Initial Release.

How to Implement

First, include the Image Overlay CSS file to your page header.

<link rel="stylesheet" type="text/css" href="ImageOverlay.css" />

Next, include the Image Overlay JavaScript file AFTER you include your jQuery installation. The ImageOverlay control was tested under jQuery 1.2.x, 1.3.x, and 1.4.1, so it should work under a number of distributions.

<script type="text/javascript" src="path-to-jQuery/jquery.min.js"></script>
<script type="text/javascript" src="jquery.ImageOverlay.js"></script>

Create the gallery html. Here are the guidelines you should follow for galleries:

  • Ideally, all images should be the same height and width. This is because we need to know the location and size of the overlay to show it properly. Refer to advanced usage to for additional information.
  • The image overlay can support a variety of content. A default CSS style has been added for header and paragraph tags, but you can style the overlay content as you see fit.
  • The gallery element must include the 'image-overlay' class in order to use any of the styling in the ImageOverlay.css file.

Here is an example of gallery html.

<ul id="myGallery" class="image-overlay">
    <a href="">
      <img alt="Image 1" src="testImages/Image1.jpg"/>
      <div class="caption">
        <h3>Image #1</h3>
        <p>click for more info</p>
    <a href="">
      <img alt="Image 2" src="testImages/Image2.jpg"/>
      <div class="caption">
        <h3>Image #2</h3>
        <p>click for more info</p>

Finally, attach the Image Overlay control via JavaScript.

$(document).ready(function() {

Here is an example of a gallery load function with options (see directly below for an explanation of available options).

  overlay_speed: 'fast',
  overlay_speed_out: 'slow',
  overlay_origin: 'top'



Allows pinning of overlay if set to true. Overrides overlay_speed, animate. Default: false.


Whether to animate the overlay as it is being shown. Overrides overlay_speed. Default: true.


Any color value. Default: '#666'.


The color of the semi-opaque overlay layer. Default: '#000'


The side which the overlay comes in from. Valid values are 'top' and 'bottom'. Default: 'bottom'


The speed of the overlay animation. Valid values are 'slow', 'normal', 'fast', and numbers for millis. Default: 'normal'


The speed of the overlay animation when hover is removed. Valid values are 'slow', 'normal', 'fast', and numbers for millis. Default is value of overlay_speed.


The color of the text on the overlay. Default: '#666'

Advanced Usage

This plugin supports the metadata plugin. You must have the metadata plugin installed to use these features. Refer to metadata plugin documentation for instructions.

In order to override or add additional options on the gallery, you can just add the options after your gallery class name using the metadata syntax. Any Image Overlay option can be overridden using this technique.

  <ul id="myGallery" class="image-overlay { overlay_color : '#ff9' }">

You can also override settings on a per-element basis by adding metadata parameters to the <a> element (not the <img> element). This is great for doing things like specifying an alternate overlay speed on a per-image basis.

<a href=""
  class="{ overlay_speed: 'fast', overlay_speed_out: 'slow' }">


The overlay is partially transparent, which was done in order to create the most visually striking style. Opacity is something that Internet Explorer doesn't do well, though. Because of this, no style other than the general 'opacity' style is officially supported. I haven't run into too many issues using the styling that is in the default stylesheet, but be aware of this - test your implementation thoroughly and use at your own risk.


Please take a second to visit my business:


blaq design