Skip to content

v2.0.0
Compare
Choose a tag to compare
@QuazChick QuazChick released this 13 Apr 14:17
· 6 commits to main since this release
v2.0.0
48775e9

Changes:

  • Removed property mode from animation prop.
    • Use the new loop and destroy parameters instead.
  • animation parameter frames now takes types number and number[] to simplify pattern creation.
  • Animation event handlers onStart and onEnd no longer have arguments.
  • Animation event handler onChange now has argument frame: number which represents the current frame's index.
  • Removed animation event handler onDestroy as it has duplicate functionality.
    • Use onEnd instead (with condition to check if should be destroyed if necessary).
  • Removed class FramageElement as it had no use.
    • useFramage no longer takes a second optional element argument.
  • Animation now restarts properly when animation prop changes.
  • Now uses transform style property rather than translate to improve browser support.
  • Default styles are now applied instantly.
  • Size of <react-framage> element now defaults to the sizes declared through the view prop.
    • <Framage> now automatically sets custom style properties --framage-view-width and --framage-view-height to support this.

React Framage

React Framage Logo

Move between portions of an image to create flipbook-like animations!

Contents

Features

  • Responsive
  • Supports custom frame patterns/orders for animations
  • Toggle looping animations
  • Toggle the removal of Framage when its animation ends
  • Animation event handlers (onStart, onEnd, onChange)
  • No dependencies

Installation

npm i react-framage

This library functions on major browsers such as Chrome, Edge, Firefox and Opera.

Usage

Demo.tsx:

import { Framage } from "react-framage";

export function Demo({ src }) {
  return (
    <Framage
      src={src}
      alt="Demo Image"
      view={{ width: 15, height: 15 }}
      animation={{
        // Create an alternate/wave pattern
        frames: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 8, 7, 6, 5, 4, 3, 2, 1],
        fps: 24,
        step: 15,
        orientation: "horizontal", // Step horizontally across source image
        loop: true,
        onChange: (frame) => console.log(`Frame ${frame} has arrived!`),
      }}
    />
  );
}

style.css:

react-framage {
  width: 100px;
  height: 100px;
  image-rendering: pixelated;
}
react-framage img {
  /* Avoid applying styles to the <img> child element as conflicts may emerge. */
}

Props

The <Framage> component supports all <img> props (e.g. src, alt, srcset) as well as:

  • view?: object - Visible portion of source image.
    • width?: number - Width of portion in pixels, relative to source.
    • height?: number - Height of portion in pixels, relative to source.
    • left?: number - Offset of portion from the left in pixels, relative to source.
    • top?: number - Offset of portion from the top in pixels, relative to source.
  • animation?: FramageAnimation - Framage animation configuration - if undefined, no animation is applied.

FramageAnimation

An object containing animation settings.

  • frames: number | number[] - Animation's frame configuration.
    • Set to an array of numbers to configure timeline of steps. Each item represents the amount of steps taken across the source image.
    • Set to a number to move one step at a time for the specified amount of frames
  • step: number - Number of pixels until next frame, relative to source image (usually same as view width/height).
  • orientation: "horizontal" | "vertical" - Direction the view portion moves in for each step.
  • fps: number - Amount of frames to cycle through per second (frames per second).
  • loop?: boolean - Whether animation should repeat.
  • destroy?: boolean - Whether component should remove itself when animation ends.
  • onStart?: () => void - Function to run on the first frame.
  • onEnd?: () => void - Function to run at the end of the last frame.
  • onChange?: (frame: number) => void - Function to run every frame change.

Styling

Below is the default styling prepended to the <head> tag by Framage:

react-framage {
  display: inline-block;
  position: relative;
  overflow: hidden;
  width: var(--framage-view-width);
  height: var(--framage-view-height);
}
react-framage img {
  position: absolute;
  left: 0;
  top: 0;
}

The custom properties --framage-view-width and --framage-view-height are automatically set on the <Framage> component, representing the values passed through props.

useFramage

A custom hook used by <Framage>.

Returns an array containing the current frame index and a boolean representing whether the Framage is destroyed.

  • animation?: FramageAnimation - Animation settings, the same options as the <Framage> prop.
import { useFramage } from "react-framage";

function Demo({ animation }) {
  const [frame, isDestroyed] = useFramage(animation);

  return !isDestroyed ? <p>Current frame: {frame}</p> : <p>Animation go bye bye 😢</p>;
}
Assets 2
Loading