npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-framage

v3.0.0

Published

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

Downloads

65

Readme

React Framage

React Framage Logo

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

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