https://github.com/ga1az/react-pixel-motion
A lightweight React component for creating smooth, pixelated sprite animations. Perfect for games, retro-style interfaces, and pixel art animations.
https://github.com/ga1az/react-pixel-motion
pixel-animation react sprite-animation spritesheet
Last synced: about 1 month ago
JSON representation
A lightweight React component for creating smooth, pixelated sprite animations. Perfect for games, retro-style interfaces, and pixel art animations.
- Host: GitHub
- URL: https://github.com/ga1az/react-pixel-motion
- Owner: ga1az
- Created: 2025-03-15T22:04:44.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-27T22:07:36.000Z (3 months ago)
- Last Synced: 2025-04-30T06:07:25.825Z (about 1 month ago)
- Topics: pixel-animation, react, sprite-animation, spritesheet
- Language: TypeScript
- Homepage: https://react-pixel-motion.ga1az.com
- Size: 802 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# React Pixel Motion
A lightweight React component for creating smooth, pixelated sprite animations. Perfect for games, retro-style interfaces, and pixel art animations. Totally inspired by [react-sprite-animation](https://github.com/jcblw/react-sprite-animator).
## Features
- 🎮 Simple API for sprite sheet animations
- 🖼️ Support horizontal, vertical and grid sprite sheets
- 🔄 Control over animation speed, scale, and direction
- 📱 Responsive and lightweight
## Sprite Sheet example supports
Sprite 1 row x 3 columns
Sprite 1 rows x 1 columns
Sprite 4 rows x 4 columns
## Installation
```bash
# Using npm
npm install @ga1az/react-pixel-motion
# Using yarn
yarn add @ga1az/react-pixel-motion
# Using pnpm
pnpm add @ga1az/react-pixel-motion
# Using bun
bun add @ga1az/react-pixel-motion
```
## Usage
```tsx
import { PixelMotion } from "@ga1az/react-pixel-motion";
import characterSprite from './assets/character.svg'; // or any other image format
import warrior from './assets/warrior.png';
function App() {
return (
console.log('Animation ended')} // Callback when animation ends (optional)
onAnimationStart={() => console.log('Animation started')} // Callback when animation starts (optional)
/>
// Grid 4x4 example
console.log(`Current frame: ${frameIndex}`)} // Callback for each frame change (optional)
/>
// Example with specific frame callback
console.log(`Special action on frame ${frameIndex}`) // Callback for specific frames (optional)
}}
/>
);
}
```
## API
### Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `sprite` | `string` \| `StaticImageData` | *Required* | URL or import of the sprite sheet image |
| `width` | `number` | *Required* | Width of each frame in pixels |
| `height` | `number` | *Required* | Height of each frame in pixels |
| `frameCount` | `number` | `1` | Total number of frames in the sprite sheet |
| `fps` | `number` | `60` | Frames per second for the animation |
| `direction` | `'horizontal'` \| `'vertical'` \| `'grid'` | `'horizontal'` | Direction of the sprite sheet |
| `shouldAnimate` | `boolean` | `false` | Whether the animation should play |
| `scale` | `number` | `1` | Scale factor for the sprite |
| `startFrame` | `number` | `0` | Initial frame to start the animation |
| `loop` | `boolean` | `true` | Whether the animation should loop |
| `imageRendering` | `boolean` | `true` | Whether the image should be rendered in pixelated mode |
| `gridOptions` | `object` | `undefined` | Options for grid sprite sheets (see Grid Options table) |
| `onAnimationEnd` | `() => void` | `undefined` | Callback function when animation ends (only if loop=false) |
| `onAnimationStart` | `() => void` | `undefined` | Callback function when animation starts |
| `onFrameChange` | `(frameIndex: number) => void` | `undefined` | Callback function for each frame change |
| `onSpecificFrame` | `{ frame: number \| number[], callback: (frameIndex: number) => void }` | `undefined` | Callback for specific frames |
### Grid Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `columns` | `number` | *Required* | Number of columns in the grid |
| `rows` | `number` | *Required* | Number of rows in the grid |
| `rowIndex` | `number` | `undefined` | Index of the row to animate (animate horizontally) |
| `columnIndex` | `number` | `undefined` | Index of the column to animate (animate vertically) |
| `gap` | `number` | `0` | Gap between frames in pixels |
## Development
```bash
bun install
bun run dev # to run the demo
bun run build # to build the library
```