Skip to content
Imadaem — JS Daemon for Responsive Images
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Build Status

Imadaem is a javascript daemon for responsive images built with jQuery and Timthumb.

Imadaem replaces the placeholder image by the dedicated size image on every significant browser window event: load, resize, rotate. The website feels pretty fast. The visitor sees the low quality file nearly immediately and can start to interact with the site: scroll, zoom, etc. After the right resolution file is loaded, all the visitor maybe notices is the blurry image gets sharp.

The small overhead by loading two images instead of one is negligible. In return you get low latency user experience.

Visitors with no javascript still see everything as long as you provide sufficient placeholders.


Read what wise men think about the technique Imadaem provides:


Visit one of following sites, resize your browser’s window and see what happens to images.

  • My personal website. My portrait’s height follows the header’s height. The portrait’s aspect ratio is limited to 2.
  • Geisterstunden — graffiti illustrated stories in German. All images are ratio-driven. The website is hosted on a cheap 1&1 hosting.


You can make things run in 15 minutes.


  • PHP library Timthumb (GPL license)
  • Javascript library jQuery (MIT license)

1. Timthumb

Download the timthumb.php file and put it on your server. Follow the official instruction. You can put your default options inside the timthumb-config.php file. For questions read the documentation inside of timthumb.php.

Make sure you can resize an image with your Timthumb installation before next steps.

2. jQuery

Download the jquery.js file and put it on your server.

3. Imadaem

Download the jquery.imadaem.js file and put it on your server.

4. Data in Images

Change the src attribute to a placeholder image, e. g. a low quality version.

The data-imadaem attribute holds the information about the original image. If you know the image’s URL only, you can put it as a string:


If you want Imadaem takes full effect, pass more information about the image as a JSON object. Example:

        "url": "/path/to/image-original.jpg",
        "gravity": "tl",
        "heightGuide": "#guide"

Learn about available data options in the API description.

Use double quotes inside of JSON object and single quotes outside of it for HTML.

5. Javascript in HTML

You must put the 3 files from the previous steps into the include definition of your HTML file. Pass a CSS selector, e. g. $("img[data-imadaem]") to Imadaem.

<script src='/path/to/jquery.js'></script>
<script src='/path/to/jquery.imadaem.js'></script>
    $(function() {
            timthumbPath: "/path/to/timthumb.php"

Learn about available javascript options in the API description.


Javascript Options

Options you can pass to the initialization call.

Parameter Meaning Values Default
dataAttribute Data attribute that holds image’s options. string imadaem
timthumbPath Path to Timthumb script string /timthumb/timthumb.php
verticalRhythm Keep image height according to a vertical scale null, line-height null
windowEvents One or more space-separated event types string resize orientationchange

Data Options

Options you can pass to an image by setting the data-imadaem attribute. Without it Imadaem will not affect the image. It must be a valid JSON object with the following properties:

  <td>Position of the most important piece</td>
  <td><code>l</code>, <code>r</code>,
    <code>t</code>, <code>tl</code>, <code>tr</code>,
    <code>b</code>, <code>bl</code>, <code>br</code>
  <td><code>"gravity": "tr"</code></td>

  <td>Aspect ratio</td>
  <td><code>"ratio": "1.5"</code></td>

  <td>Maximum aspect ratio. If <var>ratio</var> is set, <var>maxRatio</var> is ignored.</td>
  <td><code>"maxRatio": "2.4"</code></td>

  <td>Selector of elements to copy the height from</td>
  <td><code>"heightGuide": "#header"</code></td>
Property Meaning Values Example
url Path to the original string "url": "/path/to/image.jpg"


Released under the MIT license.

© 2014 Anatol Broder

You can’t perform that action at this time.