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.1.1/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. EasyFrame automatically creates a child element inside .ef-sprite to host the animation. The parent element’s size will default to the size value (in pixels).

When the page loads, EasyFrame:
1. Scans all .ef-sprite elements
2. Parses the data-ef configuration
3. Generates CSS classes and @keyframes
4. Injects styles into <head>
5. Creates a child element and applies the 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) – used for aspect ratio and background positioning	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.

Container Sizing and Fit (new in v1.1.0)

Use data-ef-box to control the dimensions of the parent container and how the sprite fills it.

Format:
```
data-ef-box="<width> <height> [fit]"
```
- width / height: any valid CSS length (e.g., 50vw, 300px, 100%). If a plain number is given, px is added automatically.
- fit (optional, default none): defines how the sprite adapts:
  - none – Child element keeps the original frame size (from size) and sits at the top-left corner of the parent.
  - contain – Sprite scales to fit entirely inside the parent (letterboxing).
  - cover – Sprite scales to cover the parent (may be cropped).
Examples:
```

<div class="ef-sprite"
     data-ef="size:100x200;frames:8;duration:1"
     data-ef-src="sprite.png"
     data-ef-box="50vw 300px cover">
</div>


<div class="ef-sprite"
     data-ef="size:64x64;frames:6;duration:1"
     data-ef-src="walk.png"
     data-ef-box="200px 150px contain">
</div>


<div class="ef-sprite"
     data-ef="size:64x64;frames:6;duration:1"
     data-ef-src="walk.png">
</div>
```
If data-ef-box is omitted, the parent container’s dimensions are taken from the size value (in pixels), and fit is none. This ensures backward compatibility with previous versions.

Note: The sprite’s aspect ratio is always preserved according to the size in data-ef.
Styling the Child Element

EasyFrame automatically adds a fixed class ef-child to the internal element that holds the animation. This makes it easy to apply custom CSS without worrying about changing UIDs.

Global styling
```
.ef-child {
    filter: drop-shadow(0 0 4px gold);
    border-radius: 8px;
}
```
Per‑instance styling

Add your own class to the parent .ef-sprite and use a descendant selector:
```
<div class="ef-sprite my-walk-cycle" data-ef="size:64x64;frames:8;duration:1" data-ef-src="walk.png"></div>

<style>
.my-walk-cycle .ef-child {
    filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.5));
    transform: scale(1.1);
}
</style>
```
Important: Never rely on the auto‑generated class names like ef_child_2 – they change when new elements are added. Always use .ef-child or a parent‑based selector.

API

Method	Description
EasyFrame.init()	Manually initialize
EasyFrame.refresh()	Re-scan DOM (clears old child elements and styles)
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)