v3.0.0

Changes:

• Restructured source code
• Renamed useFramage hook to useFramageAnimation
  • The returned array now contains a steps value
• Added useFramageImage hook
• Removed frame and steps attributes on <react-framage> elements without an animation
• Setting an animation to a speed of 0 FPS now works correctly
• Modified default styling
  • --framage-view-* properties renamed to --fallback-*
  • Added the --fallback-nineslice-* properties

React Framage

Display portions of an image, flipbook animate between them and apply nineslice scaling!

Contents

• Features
• Installation
• Animation
• Nineslice Scaling
• Props
• Styling
• Hooks
  • useFramageAnimation
  • useFramageImage

Features

• Responsive
• 9-slice scaling
• Custom frame orders for animations
• Looping animations
• Removal of Framage when its animation ends
• Animation event handlers (onStart, onEnd, onChange)
• No dependencies

Installation

npm i react-framage

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

Animation

Demo.tsx

import Framage from "react-framage";

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

Nineslice Scaling

Demo.tsx

import Framage from "react-framage";

export function Demo({ src }) {
  return (
    <Framage
      src={src}
      alt="Demo Image"
      view={{ width: 15, height: 15 }}
      nineslice={{
        top: 8,
        right: 16,
        bottom: 8,
        left: 8,
      }}
    />
  );
}

The displayed width of the outer slices can be controlled through the --nineslice and --nineslice-* CSS properties.

style.css

react-framage {
  --nineslice: 30px;
  --nineslice-right: 60px;
}

Props

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

• view: FramageView

  Visible portion of source image.

• animation?: FramageAnimation

  Framage animation configuration - if undefined, no animation is applied.

• nineslice?: FramageNineslice

  Enable 9-slice scaling for this Framage. Configures the width of the outer area with limited scaling.

FramageView

An object defining the visible portion of the source image.

• height: number

  Height of portion in pixels, relative to source.

• width: number

  Width of portion in pixels, relative to source.

• top?: number

  Offset of portion from the top in pixels, relative to source.

• left?: number

  Offset of portion from the left in pixels, relative to source.

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.

• initial?: number

  Frame index to start animation at.

• 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.

• key?: any

  Restarts animation when value is updated.

• 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.

FramageNineslice

A number or object containing settings for 9-slice scaling. These values define how wide the outer slices are. A single number value will apply the same width to all sides.

• top?: number

  Height of the top row in pixels, relative to the source image.

• right?: number

  Width of the right column in pixels, relative to the source image.

• bottom?: number

  Height of the bottom row in pixels, relative to the source image.

• left?: number

  Width of the left row in pixels, relative to the source image.

Styling

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

Default Styling

To appear properly, this library adds some default styling to the custom <react-framage> and <react-framage-slice> elements. This is applied automatically and shouldn't be included within your own stylesheets.

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

react-framage,
react-framage-slice {
  position: relative;
  overflow: hidden;
}

react-framage {
  display: inline-block;
  width: var(--fallback-width);
  height: var(--fallback-height);
}

react-framage[ninesliced] {
  display: inline-grid;
  grid-template-rows: var(--nineslice-top, var(--nineslice, var(--fallback-nineslice-top))) 1fr var(--nineslice-bottom, var(--nineslice, var(--fallback-nineslice-bottom)));
  grid-template-columns: var(--nineslice-left, var(--nineslice, var(--fallback-nineslice-left))) 1fr var(--nineslice-right, var(--nineslice, var(--fallback-nineslice-right)));
}

react-framage-slice {
  width: 100%;
  height: 100%;
}

react-framage img {
  position: absolute;
  left: 0;
  top: 0;
}

Custom --fallback-* properties are applied to the image wrapper element (<react-framage> or <react-framage-slice>) to ensure that the default styling appears correctly.

Hooks

useFramageAnimation

A custom hook used by <Framage>.

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

• animation?: FramageAnimation

import { useFramageAnimation } from "react-framage";

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

  return <p>{!isDestroyed ? `Current frame index: ${frame}. ${steps} steps have been taken.` : "Animation go bye bye 😢"}</p>;
}

useFramageImage

A custom hook used by <Framage>.

Controls the scaling and positioning on the <img> element.

• wrapper: RefObject<HTMLElement>
• image: RefObject<HTMLImageElement>
• data: object
  • animation?: FramageAnimation
  • frame: number
  • steps: number
  • view: FramageView

import { useFramageAnimation, useFramageImage } from "react-framage";

function Demo({ src, animation, view }) {
  const wrapper = useRef<HTMLDivElement>(null);
  const image = useRef<HTMLImageElement>(null);

  const [frame, steps] = useFramageAnimation(animation);

  useFramageImage(wrapper, image, {
    animation,
    frame,
    steps,
    view,
  });

  return (
    <div ref={wrapper}>
      <img ref={image} src={src} alt="Demo Image" />
    </div>
  );
}

v2.1.0

Changes:

• frames animation parameter no longer restarts the animation. This behaviour can be replicated through the key parameter.
• Added 9-slice scaling support through the nineslice prop.

React Framage

Display portions of an image, flipbook animate between them and apply nineslice scaling!

Contents

• Features
• Installation
• Usage
• Props
• Styling
• useFramage Hook

Features

• Responsive
• Supports 9-slice scaling
• 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.
• nineslice?: number | object - Enable 9-slice scaling for this Framage. Configures the width of the border area with limited scaling.
  • top?: number - Width of top border in pixels, relative to source.
  • right?: number - Width of right border in pixels, relative to source.
  • bottom?: number - Width of bottom border in pixels, relative to source.
  • left?: number - Width of left border 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.
• initial?: number - Frame index to start animation at.
• 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.
• key?: any - Restarts animation when value is updated.
• 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[ninesliced] {
  display: inline-grid;
}

react-framage-slice {
  width: 100%;
  height: 100%;
  overflow: hidden;
  position: relative;
}

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.

Nineslice Styling

The displayed width of the nineslice border can be controlled through the --nineslice-border-width and --nineslice-border-*-width properties.

react-framage {
  --nineslice-border-width: 30px;
  --nineslice-border-top-width: 40px;
}

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 <p>{!isDestroyed ? `Current frame index: ${frame}` : "Animation go bye bye 😢"}</p>;
}

v2.0.2

Changes:

• Added key option to animation prop.
  • Changing this value results in an animation restart.
• Animation restarts are now only caused by updates to the frames and key values on the animation prop.
• Added JSDoc descriptions for FramageAnimation properties.

React Framage

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

Contents

• Features
• Installation
• Usage
• Props
• Styling
• useFramage Hook

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.
  • Restarts animation when updated.
• initial?: number - Frame index to start animation at.
• 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.
• key?: any - Restarts animation when value is updated.
• 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 <p>{!isDestroyed ? `Current frame index: ${frame}` : "Animation go bye bye 😢"}</p>;
}

v2.0.0

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

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

Contents

• Features
• Installation
• Usage
• Props
• Styling
• useFramage Hook

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>;
}

v1.1.0

Framage no longer restarts animation after rerender.

React Framage

Display specific portions of an image, and animate between frames.

Contents

• Features
• Installation
• Usage
• Props
• useFramage
• FramageElement
• Styling

Features

• Responsive
• Supports custom frame patterns/orders for animations
• 3 animation modes ("loop", "keep-on-last", "destroy-after-last")
• Animation events (onStart, onEnd, onDestroy, 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, { FramageElement } from "react-framage";

export function Demo({ src }) {
  const framage = useRef<FramageElement>(null);

  return (
    <Framage
      ref={framage}
      src="https://github.com/Uspel/react-framage/blob/main/images/demo.png"
      alt="Demo Image"
      view={{ width: 15, height: 15 }}
      animation={{
        frames: {
          amount: 10,
          // Creates a wave pattern
          // Would return [0,1,2,3,4,5,6,7,8,9,9,8,7,6,5,4,3,2,1,0] as there are 10 frames.
          pattern: f => [...f, ...[...f].reverse()]
        },
        step: 15,
        fps: 24, // Cannot be active at the same time as `frameDuration` - both control timing.
        mode: "loop",
        orientation: "horizontal",
        onChange(e) {
          console.log(`Frame ${e.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 - Portion of the source image visible.
  • width: number - Pixel width.
  • height: number - Pixel height.
  • left?: number - Initial X position of the view portion (from the left).
  • top?: number - Initial Y position of the view portion (from the top).
• animation?: FramageAnimation or false (default) - Settings for the component's animation - set to false for no animation.

---

FramageAnimation

An object containing animation settings.

• frames: object - Animation's frame configuration.
  • amount: number - Number of frames in total on source.
  • pattern?: number[] or (frames: number[]) => number[] - Order to display frames in.
  • initial?: number - Frame to start on first mount.
• step: number - Number of pixels until next frame (usually view width).
• fps: number - Frames per second (cannot be active at the same times as frameDuration).
• frameDuration: number - Seconds per frame (cannot be active at the same times as fps).
• mode?: "loop" (default), "keep-on-last" or "destroy-after-last" - How the animation cycles.
  • "loop" - repeats animation infinitely.
  • "keep-on-last" - once the last frame is reached, it will stay on that frame.
  • "destroy-after-last" - removes element when animation is complete.
• orientation?: "horizontal" (default) or "vertical" - Direction the view portion moves in for each frame.
• onStart?: (e: FramageEvent) => void - Function to run on first frame.
• onEnd?: (e: FramageEvent) => void - Function to run on last frame.
• onDestroy?: (e: FramageEvent) => void - Function to run when animation is destroyed by the "destroy-after-last" mode.
• onChange?: (e: FramageEvent) => void - Function to run every frame change.

useFramage

A custom hook used by <Framage>.

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

• animation: FramageAnimation or false (default) - Animation settings, the same options as the <Framage> prop.
• element?: HTMLElement - An element to trigger events on. Prop event handlers do not require this.

import { useFramage } from "react-framage";

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

  return !isDestroyed && <p>Current frame: {frame}</p>;
}

FramageElement

<react-framage> element created by <Framage> component.

Events useable in addEventListener etc:

• "framageanimationstart"
• "framageanimationend"
• "framageanimationdestroy"
• "framageanimationchange"

Styling

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

react-framage {
  display: inline-block;
  position: relative;
  overflow: hidden;
}
react-framage img {
  position: absolute;
  top: 0;
  left: 0;
}

Alternatively to CSS files, you can apply styling through the style prop:

<Framage
  {...}
  style={{
    width: 100,
    height: 100,
    imageRendering: "pixelated",
    img: {
      /* Styles to apply to the <img> child element. */
    }
  }}
/>

v1.0.0

React Framage

Display specific portions of an image, and animate between frames.

Contents

• Features
• Installation
• Usage
• Props
• useFramage
• FramageElement
• Styling

Features

• Responsive
• Supports custom frame patterns/orders for animations
• 3 animation modes ("loop", "keep-on-last", "destroy-after-last")
• Animation events (onStart, onEnd, onDestroy, 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, { FramageElement } from "react-framage";

export function Demo({ src }) {
  const framage = useRef<FramageElement>(null);

  return (
    <Framage
      ref={framage}
      src="https://github.com/Uspel/react-framage/blob/main/images/demo.png"
      alt="Demo Image"
      view={{ width: 15, height: 15 }}
      animation={{
        frames: {
          amount: 10,
          // Creates a wave pattern
          // Would return [0,1,2,3,4,5,6,7,8,9,9,8,7,6,5,4,3,2,1,0] as there are 10 frames.
          pattern: f => [...f, ...[...f].reverse()]
        },
        step: 15,
        fps: 24, // Cannot be active at the same time as `frameDuration` - both control timing.
        mode: "loop",
        orientation: "horizontal",
        onChange(e) {
          console.log(`Frame ${e.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 - Portion of the source image visible.
  • width: number - Pixel width.
  • height: number - Pixel height.
  • left?: number - Initial X position of the view portion (from the left).
  • top?: number - Initial Y position of the view portion (from the top).
• animation?: FramageAnimation or false (default) - Settings for the component's animation - set to false for no animation.

---

FramageAnimation

An object containing animation settings.

• frames: object - Animation's frame configuration.
  • amount: number - Number of frames in total on source.
  • pattern?: number[] or (frames: number[]) => number[] - Order to display frames in.
  • initial?: number - Frame to start on first mount.
• step: number - Number of pixels until next frame (usually view width).
• fps: number - Frames per second (cannot be active at the same times as frameDuration).
• frameDuration: number - Seconds per frame (cannot be active at the same times as fps).
• mode?: "loop" (default), "keep-on-last" or "destroy-after-last" - How the animation cycles.
  • "loop" - repeats animation infinitely.
  • "keep-on-last" - once the last frame is reached, it will stay on that frame.
  • "destroy-after-last" - removes element when animation is complete.
• orientation?: "horizontal" (default) or "vertical" - Direction the view portion moves in for each frame.
• onStart?: (e: FramageEvent) => void - Function to run on first frame.
• onEnd?: (e: FramageEvent) => void - Function to run on last frame.
• onDestroy?: (e: FramageEvent) => void - Function to run when animation is destroyed by the "destroy-after-last" mode.
• onChange?: (e: FramageEvent) => void - Function to run every frame change.

useFramage

A custom hook used by <Framage>.

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

• animation: FramageAnimation or false (default) - Animation settings, the same options as the <Framage> prop.
• element?: HTMLElement - An element to trigger events on. Prop event handlers do not require this.

import { useFramage } from "react-framage";

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

  return !isDestroyed && <p>Current frame: {frame}</p>;
}

FramageElement

<react-framage> element created by <Framage> component.

Events useable in addEventListener etc:

• "framageanimationstart"
• "framageanimationend"
• "framageanimationdestroy"
• "framageanimationchange"

Styling

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

react-framage {
  display: inline-block;
  position: relative;
  overflow: hidden;
}
react-framage img {
  position: absolute;
}

Alternatively to CSS files, you can apply styling through the style prop:

<Framage
  {...}
  style={{
    width: 100,
    height: 100,
    imageRendering: "pixelated",
    img: {
      /* Styles to apply to the <img> child element. */
    }
  }}
/>