Tutorial

How to use EasyFrame?

Preparation

EasyFrame generates CSS frame-by-frame animations from a single-row sprite sheet. Please prepare your sprite sheet as a single row of images, ensuring that each cell (each frame in the sheet) has the same dimensions.

example sprite sheet with 7 frames

Setup configuration

Using EasyFrame.JS (recommended)

Import EasyFrame.js

CDN (Recommended)

<script src="https://cdn.jsdelivr.net/gh/ShuninYu/easy-frame@v1.0.0/dist/easy-frame.umd.min.js"></script>

<script src="https://cdn.jsdelivr.net/npm/easy-frame/dist/easy-frame.umd.min.js"></script>

NPM

npm install easy-frame

ES Module:

import EasyFrame from "easyframe";

CommonJS:

const EasyFrame = require("easyframe");

Usage
```
<script src="easyframe.min.js"></script>

<div
    class="ef-sprite"
    data-ef="size:64x64;frames:6;duration:1"
    data-ef-src="/images/character.png">
</div>
```
That’s it.

When the page loads, EasyFrame:
1. Scans all .ef-sprite elements
2. Parses the data-ef configuration
3. Generates CSS classes
4. Injects @keyframes into <head>
5. Automatically applies animation

Configuration

You can use our online tool to help you generate HTML element for EasyFrame easily. But I still recommend you to read the description below to fully understand how EasyFrame works.

All animation settings are defined inside the data-ef attribute.

Format:

data-ef="key:value;key:value;flag"

Required Parameters

Key	Description	Example
size	Frame size (width x height)	size:64x64
frames	Number or segments	frames:6 or frames:4,3,7
duration	Duration in seconds	duration:1 or duration:0.4,0.2,0.6

Optional Parameters

Key	Description	Example
mode	Animation mode	mode:loop
pixel	Enables pixelated rendering	pixel

Animation Modes

Mode	Behavior
loop	Infinite loop (default)
pingpong	Infinite alternate
none	Play once

Example:

data-ef="size:64x64;frames:4;duration:1;mode:pingpong"

Segmented Animation Example

<div
    class="ef-sprite"
    data-ef="size:64x64;frames:4,3,7;duration:0.4,0.2,0.6;mode:pingpong;pixel"
    data-ef-src="/sprite/man.png">
</div>

This creates:

3 animation segments
Custom duration per segment
Ping-pong looping
Pixelated rendering

Background Image

Set sprite image using:
```
data-ef-src="/path/to/sprite.png"
```
If omitted, background image must be defined in CSS.

API

Method	Description
EasyFrame.init()	Manually initialize
EasyFrame.refresh()	Re-scan DOM
EasyFrame.version	Library version

Using online tool
1. (If you use EasyFrame.JS, you can skip this step) Fill in the Animation name and Class name.
  
  Note: The class name you enter will be the one you reference in your HTML. Also, if you are not familiar with how CSS @keyframe animations work, please do not modify the CSS code generated by EasyFrame. If you need to adjust the animation effect, simply change the settings in EasyFrame and regenerate the code to replace the old one.
2. Fill in the Width and Height.
  
  The width and height here should be the dimensions of the animated element, typically the same as each cell (each frame) in your sprite sheet. If you are unsure what size to use, just enter the dimensions of each cell.
3. Upload your sprite sheet (optional)
  
  If you want to preview the animation, you can upload your sprite sheet file (image) or provide a CDN/online resource link pointing to the image. EasyFrame will automatically generate an animation preview when it produces the code.
  
  If you want the generated CSS to include the image link (so you can paste and use it directly), then fill in the sprite sheet (image) link that will be used in the CSS. Please note that if the link you provide is a file path or an invalid URL, the animation preview will not be generated, but the CSS code will still be produced normally.
4. Fill in Frames and Duration (important)
  
  In frames, enter the total number of frames in your sprite sheet. If your animation has segments with different durations, enter them as an array.
  
  For example, suppose frames 1, 2, and 3 each last 0.1s (3 frames total), frame 4 lasts 1s, and frames 5, 6, and 7 each last 0.2s (3 frames total). Then you would enter frames as [3,1,3].
  
  In duration, enter the durations of the animation segments. If your animation has segments with different durations, enter them as an array.
  
  Using the same example: frames 1, 2, and 3 together last 0.3s, frame 4 lasts 1s, and frames 5, 6, and 7 together last 0.6s. Then you would enter duration as [0.3,1,0.6].
  
  Note that the lengths of the frames and duration arrays must match. If frames is a single number (e.g., 7), then duration should also be a single number (e.g., 0.7). Similarly, if frames is an array of three numbers (like [3,1,3]), then duration must also be an array of three numbers (like [0.3,1,0.6]).
5. Finally, choose the Cycle mode. There are three options:
  - None – Plays once and stops at the last frame.
  - Loop – Plays repeatedly, restarting from the first frame after the last.
  - Ping-pong – Plays back and forth between the first and last frames repeatedly.
6. Generate!
  
  After all settings are complete, click the Generate CSS button to produce the CSS code. If you imported EasyFrame.JS in your project, you can just copy HTML code into your HTML file and EasyFrame will generate animation for you!
  You can also copy the CSS and paste it into your own CSS (or Less) file for use.
  
  Here is the example animation.
  (scaled 4 times larger than origin)