AnimateImage

Index

• Introduction
  • Features
  • Usage
• Download
• API Specification
• Code Samples
• Demos
• FAQ
• Alternative Scripts
• Animation Specification
• Support Me?

Introduction

AnimateImage is a JavaScript library which displays multiple images continuously like animated GIF.

* I found some animation scripts but they do not match for me. So I had decided to create AnimateImage on my own.

Features

• Displays multiple images continuously like animated GIF. It supports sequential/arbitrary file names.
• Supports all image formats supported by Web browsers
  • PNG, JPEG, GIF, BMP, TIFF, WebP, etc.
  • Transparent PNG: Transparent background of animated images
  • High-quality images: more than 256 colors photos and illustrations
• You can specify animation delay (0.5 seconds in default)
• You can specify repeat count of animation (infinite iteration in default)
• No need for JavaScript codes. img elements are animated automatically just by writing them.
• You can control (play/stop/replay) animations and more by writing JavaScript codes
• Displays as Simple Slide-Show by using photos, etc
• Stand-alone script with about 5.6 KB file size (No need for JS libraries such as jQuery)

Usage

Write the following code in “head” or “body” element to load AnimateImage script.

<script type="text/javascript" src="animate-image.min.js"></script>

Write the following code if you animate 1.png, 2.png, … 10.png in ‘images’ directory.

<img src="images/1.png" data-files="[1-10].png" />

Or write the following code if you use AnimateImage from inside JavaScript.

<script type="text/javascript">
    AnimateImage.animate('Image[1-10].png');
</script>

Image files that can be animated are the following 4 types.

• Sequential number (0, 1, 2, 3, …)
• Sequential zero-padded number (01, 02, …, 001, 002, …)
• Sequential alphabet (a, b, c, …, A, B, C, …)
• Arbitrary files (foo.png, bar.jpg, baz.gif, …)

Options to customize animation are more than 15.

• Image title, alternative text of image
• ID string and class name of image element
• Animation interval, delay between animation cycles
• Repeat count of animation
• Whether to rewind to the first image at the end of animation
• Whether to pause at the first/last image in animation
• Whether to display blank image between animation cycles

Furthermore you can do below by writing JavaScript codes.

• Contolling animation (play/stop/replay)
• Getting animation img element, then modify/insert it
• Changing common options for all animations

* See API Specification and Code Samples for more information.

* you can play/stop/replay animatione. you can change common options of all animations.

Download

animate-image.min.js

• v1.1.1, 2012-09-17, 5.6 KB
• Free license (for personal & non-commercial, donate to support)
• Optimized and compressed code

animate-image.js

• v1.1.1, 2012-09-17, 22.4 KB
• Commercial license ($5.00)
• Uncompressed code with comments
• Paid support (technical questions, customization, etc.)

* animate-image.min.js is minified by removing comments, line breaks, unnecessary spaces, etc. And local variables and function parameters are renamed to shorter name. While animate-image.js is formatted for readability. And documentation comments are written in JSDoc style.

Supported Browsers

• Internet Explorer
• Mozilla Firefox
• Google Chrome
• Opera
• Safari

* AnimateImage is coded with JavaScript 1.4 / JScript 5.0 (IE5). So AnimateImage may support most browsers.

Past Releases

• AnimateImage version 1.1 (1.1.1)
• AnimateImage version 1.0.4
• AnimateImage version 1.0
• AnimateImage version 0.9
• AnimateImage version 0.8.3
• AnimateImage version 0.8 (0.8.0.3)
• AnimateImage version 0.7
• AnimateImage version 0.6.5 (0.6.5.1)
• AnimateImage version 0.6.4 (0.6.4.1)
• AnimateImage version 0.6.3
• AnimateImage version 0.6.2
• AnimateImage version 0.6.1
• AnimateImage version 0.6
• AnimateImage version 0.5 (initial release)

* This is obsolete information about older version (code samples and API specification, etc.)

• AnimateImage Old Version (v0.9 – v1.0.4)
• AnimateImage Old Version (v0.7 – v0.8.3)
• AnimateImage Old Version (v0.5 – v0.6.5.1)

API Specification

• Auto-Apply img Elements
• AnimateImage.Animator Class
• AnimateImage.animate() Function
• AnimateImage.options Object

Auto-Apply img Elements

AnimateImage is applied automatically to ‘img’ elements that have ‘data-files’ attribute.

<img src="" data-files=""
  title="" alt="" id="" class="" style=""
  data-delay="" data-repeat="" data-rewind=""
  data-pauseAtFirst="" data-pauseAtLast="" data-showBlank="" data-cycleDelay="" data-blankClassName="" />

You need to specify undefined attributes with custom data-* attributes in ‘img’ element. ‘src’ and ‘data-files’ attributes are required in AnimateImage. ‘data-files’ attribute is specified with file name including format string, or specified with relative path to directory when specifying directory name with format string. See Code Sample 3 for details.

AnimateImage.Animator Class

An object to control animation of images.

Properties

imgElem

‘img’ element that is created by AnimateImage, or specified with options.imgElem

Constructor Function

AnimateImage.Animator(files, options)

* See AnimateImage.animate() function about arguments specification. The following old syntax also works.

AnimateImage.Animator(files, title, id, delay, repeat, rewind)

animate(replay) Method

Plays (Replays) animation.

When argument “replay” is true or you call it after animation, the animation is replayed from the beggining.

stopAnimate() Method

Stops (Pauses) running animation.

AnimateImage.animate() Function

Animates multiple images.

* It is almost equivalent to new AnimateImage.Animator(files, options).animate().

Syntax

animator = AnimateImage.animate(files, options)

* The following old syntax also works.

animator = AnimateImage.animate(files, title, id, delay, repeat, rewind)

Arguments

files (required)

Image files specified with file name including the format string or array of file name

Sequential Number

In “[d-d]” format. Specify as “[0d-dd]” or “[00d-ddd]” if zero-padding.

Sequential Alphabet

In “[a-z]” format. Specify as “[A-Z]” if uppercase.

Comma Separated Values

In “[foo, bar, baz]” format. Specify as “[foo.png, bar.jpg, baz.gif]” if different extensions.

options

Animation settings specified with object literal ({ properyName: value })

title

Image title that is set to img@title attribute

alt

Alternative text that is set to img@alt attribute (options.title in default)

id

ID string of img element. It is unique value for each animation.

delay

Animation delay in milliseconds (AnimateImage.options.delay in default)

repeat

Repeat count of animation (AnimateImage.options.repeat in default)

rewind

Whether to rewind to the first image at the end of animation (AnimateImage.options.rewind in default)

pauseAtFirst

Whether to pause at the first image in animation (AnimateImage.options.pauseAtFirst in default)

pauseAtLast

Whether to pause at the last image in animation (AnimateImage.options.pauseAtLast in default)

showBlank

Whether to display blank image between animation cycles (AnimateImage.options.showBlank in default)

cycleDelay

Delay between animation cycles in milliseconds (AnimateImage.options.cycleDelay in default)

className

Class name of img element, separated by spaces (AnimateImage.options.className in default)

blankClassName

Class name of img element, added to blank image (AnimateImage.options.blankClassName in default)

attr

Arbitrary attributes specified with object literal ({ attributeName: value })

css

Arbitrary CSS properties that are set to img@style, specified with object literal ({ propertyName: value }).

You can use property names in DOM formatting (e.g. borderLeft) or CSS formatting (e.g. border-left). You need to enclose hyphenated names in quotation marks as { 'property-name': value }.

imgElem

img element specified with Image object. Use it to specify created img element. (img element will be created if omitted)

output

Whether to output img element

Return Value

animator

AnimateImage.Animator object. you can stop/replay animation using this object.

AnimateImage.options Object

Common options in AnimateImage.

* You need to set value before the start of animation if you change it, because the value is referred to before the start of animation.

Properties

delay

Animation delay in milliseconds. Default is 500 ms.

repeat

Repeat count of animation. -1 means infinite iteration, and 0 means no animation (i.e. only displays first image). Default is -1.

rewind

Whether to rewind to the first image at the end of animation. Default is false.

pauseAtFirst

Whether to pause at the first image in animation. Default is false.

pauseAtLast

Whether to pause at the last image in animation. Default is false.

showBlank

Whether to display blank image between animation cycles. Default is false.

Blank image is transparent GIF using data:url, and is displayed in the size of first image.

cycleDelay

Delay between animation cycles in milliseconds. Default is 0.

className

Class name of img element, separated by spaces. class attribute is not added if empty. Default is “animation”.

blankClassName

Class name of img element, added to blank image. class attribute is not added if empty. Default is “blank”.

output

Whether to output img element. Default is true.

Code Samples

• Code Sample 1: Sequential File Names
• Code Sample 2: Arbitrary File Names
• Code Sample 3：Specifying Directory Name with Format String
• Code Sample 4: title/alt Attributes
• Code Sample 5: id/class Attributes
• Code Sample 6: delay/cycleDelay Options
• Code Sample 7: repeat/rewind Options
• Code Sample 8: pauseAtFirst/Last Options
• Code Sample 9: Arbitrary Attributes
• Code Sample 10: Arbitrary CSS Properties
• Code Sample 11: Common Options (AnimateImage.options)
• Code Sample 12: Animation Control (Start/Stop/Replay)
• Code Sample 13: Using Created img Elements
• Code Sample 14: Getting/Modifying/Inserting img Elements

Code Sample 1: Sequential File Names

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png" />
<img src="images/01.png" data-files="[01-99].png" />
<img src="images/001.png" data-files="[001-999].png" />
<img src="images/a.png" data-files="[a-z].png" />
<img src="images/A.png" data-files="[A-Z].png" />
<img src="dir/pre-1_post.jpg" data-files="pre-[1-10]_post.jpg" />

JavaScript

AnimateImage.animate('images/[0-9].png');
AnimateImage.animate('images/[01-99].png');
AnimateImage.animate('images/[001-999].png');
AnimateImage.animate('images/[a-z].png');
AnimateImage.animate('images/[A-Z].png');
AnimateImage.animate('dir/pre-[1-10]_post.jpg'); // prefix/suffix

Code Sample 2: Arbitrary File Names

img Elements (HTML)

<img src="images/foo.png" data-files="[foo, bar, baz].png" />
<img src="images/foo.png" data-files="[foo.png, bar.jpg, baz.gif]" />
<img src="dir/pre-foo_post.jpg" data-files="pre-[foo, bar, baz]_post.jpg" />

JavaScript

AnimateImage.animate('images/[foo, bar, baz].png');
AnimateImage.animate('images/[foo.png, bar.jpg, baz.gif]');
AnimateImage.animate('dir/pre-[foo, bar, baz]_post.jpg'); // prefix/suffix

* You can also specify array of file name instead of file name including format string.

var files = ['images/foo.png', 'images/bar.png', 'images/baz.png'];
AnimateImage.animate(files);

AnimateImage.animate(['images/foo.png', 'images/bar.jpg', 'images/baz.gif']);

Code Sample 3：Specifying Directory Name with Format String

img Elements (HTML)

<img src="parent/child/image0.png" data-files="image[0-9].png" />
<img src="parent/child0/image.png" data-files="child[0-9]/image.png" />
<img src="parent0/child/image.png" data-files="parent[0-9]/child/image.png" />

* ‘data-files’ attribute is specified with file name including format string, or specified with relative path to directory when specifying directory name with format string.

JavaScript

AnimateImage.animate('parent/child/image[0-9].png');
AnimateImage.animate('parent/child[0-9]/image.png');
AnimateImage.animate('parent[0-9]/child/image.png');

* Specify path to directory to data-files attribute if directory name is sequential.

Code Sample 4: title/alt Attributes

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png" title="foo" />
<img src="images/0.png" data-files="[0-9].png" title="foo" alt="bar" />
<img src="images/0.png" data-files="[0-9].png" alt="bar" />
<img src="images/0.png" data-files="[0-9].png" alt="" />

JavaScript

AnimateImage.animate('images/[0-9].png', { title: 'foo' });             // title="foo" alt="foo"
AnimateImage.animate('images/[0-9].png', { title: 'foo', alt: 'bar' }); // title="foo" alt="bar"
AnimateImage.animate('images/[0-9].png', { alt: 'bar' });               // alt="bar"
AnimateImage.animate('images/[0-9].png', { alt: '' });                  // alt=""

* Add alt attribute with empty string to img element (img@alt=””) if alternative text for images is unnecessary.

Code Sample 5: id/class Attributes

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png" />
<img src="images/0.png" data-files="[0-9].png" id="foo" />
<img src="images/0.png" data-files="[0-9].png" class="bar" />
<img src="images/0.png" data-files="[0-9].png" class="bar baz" />
<img src="images/0.png" data-files="[0-9].png" class="" />

JavaScript

AnimateImage.animate('images/[0-9].png');                           // class="animation"
AnimateImage.animate('images/[0-9].png', { id: 'foo' });            // id="foo" class="animation"
AnimateImage.animate('images/[0-9].png', { className: 'bar' });     // class="bar"
AnimateImage.animate('images/[0-9].png', { className: 'bar baz' }); // class="bar baz"
AnimateImage.animate('images/[0-9].png', { className: '' });        // no class

* Define style rules with class/id selectors in CSS files or style elements.

img.animation { background: white; }
img#foo { background: silver; }
img.bar { background: gray; }
img.baz { background: black; }

Code Sample 6: delay/cycleDelay Options

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png" />
<img src="images/0.png" data-files="[0-9].png" data-delay="1000" />
<img src="images/0.png" data-files="[0-9].png" data-cycleDelay="2000" />

JavaScript

AnimateImage.animate('images/[0-9].png'); // delay=500, cycleDelay=0
AnimateImage.animate('images/[0-9].png', { delay: 1000 });
AnimateImage.animate('images/[0-9].png', { cycleDelay: 2000 });

Code Sample 7: repeat/rewind Options

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png" />
<img src="images/0.png" data-files="[0-9].png" data-repeat="1" />
<img src="images/0.png" data-files="[0-9].png" data-repeat="2" data-rewind="true" />

JavaScript

AnimateImage.animate('images/[0-9].png'); // repeat=-1, rewind=false
AnimateImage.animate('images/[0-9].png', { repeat: 1 });
AnimateImage.animate('images/[0-9].png', { repeat: 2, rewind: true });

Code Sample 8: pauseAtFirst/Last Options

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png" />
<img src="images/0.png" data-files="[0-9].png" data-pauseAtFirst="true" data-pauseAtLast="true" />

JavaScript

AnimateImage.animate('images/[0-9].png'); // pauseAtFirst=false, pauseAtLast=false
AnimateImage.animate('images/[0-9].png', { pauseAtFirst: true, pauseAtLast: true });

Code Sample 9: Arbitrary Attributes

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png"
    width="100" height="100" longdesc="long description" />

JavaScript

AnimateImage.animate('images/[0-9].png', {
  attr: {
    width: 100,
    height: 100,
    longdesc: 'long description'
  }
});

Code Sample 10: Arbitrary CSS Properties

img Elements (HTML)

<img src="images/0.png" data-files="[0-9].png"
    style="border: solid; border-top: dotted; border-bottom: dashed" />

JavaScript

AnimateImage.animate('images/[0-9].png', {
  css: {
    border: 'solid',
    borderTop: 'dotted',
    'border-bottom': 'dashed'
  }
});

Code Sample 11: Common Options (AnimateImage.options)

JavaScript

AnimateImage.animate('images/[0-9].png'); // delay=500, repeat=-1

AnimateImage.options.delay = 1000;
AnimateImage.options.repeat = 1;
AnimateImage.animate('images/[0-9].png'); // delay=1000, repeat=1
AnimateImage.animate('images/[0-9].png'); // delay=1000, repeat=1

AnimateImage.animate('images/[0-9].png', { delay: 2000, repeat: -1 });

Code Sample 12: Animation Control (Start/Stop/Replay)

JavaScript

var animator = new AnimateImage.Animator('images/[0-9].png');
animator.animate();

var animator2 = AnimateImage.animate('images/[0-9].png');

* Write the following input elements when you control animation behavior.

<input type="button" value="Start" onclick="animator.animate()" />
<input type="button" value="Stop" onclick="animator.stopAnimate()" />
<input type="button" value="Replay" onclick="animator.animate(true)" />

Code Sample 13: Using Created img Elements

JavaScript

var imgElem = new Image();
imgElem.src = 'images/0.png';
imgElem.width = 100;
imgElem.height = 100;
imgElem.setAttribute('longdesc', 'long description');
AnimateImage.animate('images/[0-9].png', { imgElem: imgElem });

Code Sample 14: Getting/Modifying/Inserting img Elements

JavaScript

var animator = AnimateImage.animate('images/[0-9].png', { output: false });
animator.imgElem.width = 100;
animator.imgElem.height = 100;
animator.imgElem.setAttribute('longdesc', 'long description');
document.getElementById('foo').appendChild(animator.imgElem);

Demos

Transparent PNG

Transparent background of animated images with transparent PNGs. In this demo, background color changes on mouse hover.

Simple Slide-Show

High-quality photos and illustrations which is more than 256 colors. In this demo, 24-bit colors JPEGs are animated.

Non-sequential filenames

Any files whose filename is non-sequential number. In this demo, “blank.png”, “website.png”, “blog.png”, and “download.png” are animated.

Animation Control (Play/Stop/Replay)

Animation control (play/stop/replay) at any time. In this demo, [Start] button starts (restarts) animation, [Stop] button stops (pauses) animation, and [Replay] button replays animation from the beggining.

FAQ

• Which to Use Auto-Apply ‘img’ Elements or JavaScript Codes
• Differences between AnimateImage.Animator Class and AnimateImage.animate() Function
• How to Describe Valid HTML as Complying with Web Standards

Which to Use Auto-Apply ‘img’ Elements or JavaScript Codes

Auto-Apply ‘img’ Elements

• Improved readability by not writing ‘script’ elements and JavaScript codes
• No need for JavaScript codes. It is also available in where JavaScript is limited.
• ‘img’ elements are always displayed even if JavaScript is disabled or JavaScript errors occur (equivalent of ‘noscript’ elements)

JavaScript Codes

• Animation behavior (start/stop/replay) is controllable
• Handling ‘img’ elements in JavaScript (to get, create, modify, insert, etc.)
• Common options can be changed

* FYI: The two sample codes below are almost equivalent.

<p><img src="images/0.png" data-files="[0-9].png" /></p>

<p><script type="text/javascript">AnimateImage.animate('images/[0-9].png');</script></p>
<noscript><p><img src="images/0.png" /></p></noscript>

Differences between AnimateImage.Animator Class and AnimateImage.animate() Function

AnimateImage.Animator Class

Use when you want to control the start timing of animation.

• In creating object, first image is displayed.
• Animation does not start until calling animate() method.

AnimateImage.animate() Function

Use when you do not care about starting animation automatically.

• In calling the function, first image is displayed and animation starts.

How to Describe Valid HTML as Complying with Web Standards

There are three points below.

• ‘alt’ attribute is mandatory in ‘img’ element
• ‘script’ element is inline in body, and ‘noscript’ element is block
• ‘noscript’ element contains only block elements

Then valid HTML as complying with Web standards is as follows.

<div>
    <script type="text/javascript">
        AnimateImage.animate('image[0-9].png', 'text');
    </script>
</div>
<noscript>
    <div><img src="image0.png" alt="text" /></div>
</noscript>

Alternative Scripts

• Square Goldfish ≫ AnimatedPNG
• jQuery Cycle Plugin

Animation Specification

• Animated GIF
• MNG (Multiple-image Network Graphics)
• APNG (Animated Portable Network Graphics)
• Motion JPEG
• SVG Animation

Support Me?

• If you have any feedbacks or questions, visit Contact Me
• If you like this script, please consider making a donation to support the development

Any comments will be very helpful and appreciated. Thank you for your support!

“keyboard keys” by chromatix is licensed under Creative Commons License.