react-framage
v3.0.0
Published
Display portions of an image, flipbook animate between them and apply nineslice scaling!
Downloads
65
Maintainers
Readme
React Framage
Display portions of an image, flipbook animate between them and apply nineslice scaling!
Contents
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
step
s. Each item represents the amount ofstep
s taken across the source image. - Set to a number to move one step at a time for the specified amount of frames.
- Set to an array of numbers to configure timeline of
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
- animation?:
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>
);
}