Shipfox Loader React Component

A React component version of the Shipfox Loader animation system. This component provides the same interactive animations as the original HTML version but in a reusable React component format.

Features

4 Animation Patterns: Random, Vertical, Circular, and Left-to-Right
Customizable Properties: Size, color, background, speed, and more
Interactive Controls: Optional play/pause and reset controls
Hover Effects: Smooth cursor interactions
TypeScript Support: Full type definitions included
Zero Dependencies: Pure React implementation

Installation

npm install shipfox-loader-react

Basic Usage

import ShipfoxLoader from 'shipfox-loader-react';

function App() {
  return (
    <ShipfoxLoader
      size={60}
      animation="random"
      color="orange"
      background="dark"
    />
  );
}

Props

Prop	Type	Default	Description
`size`	`number`	`60`	Size of the canvas in pixels
`animation`	`'random' \| 'vertical' \| 'circular' \| 'leftright'`	`'random'`	Animation pattern type
`color`	`'orange' \| 'white' \| 'black'`	`'orange'`	Color mode for the fox
`background`	`'dark' \| 'light'`	`'dark'`	Background mode
`showControls`	`boolean`	`false`	Show play/pause and reset controls
`autoPlay`	`boolean`	`true`	Start animation automatically
`speed`	`number`	`1`	Animation speed multiplier
`config`	`Partial<ShipfoxConfig>`	`{}`	Advanced configuration options
`className`	`string`	`''`	CSS class name
`style`	`React.CSSProperties`	`{}`	Inline styles
`onAnimationComplete`	`() => void`	`undefined`	Callback when animation cycle completes

Advanced Configuration

<ShipfoxLoader
  size={120}
  animation="circular"
  color="white"
  background="light"
  showControls={true}
  autoPlay={true}
  speed={1.5}
  config={{
    ghostOpacity: 0.3,      // Transparency of unlit pixels
    lightRadius: 6,         // Glow effect radius
    lightBrightness: 0.8,   // Glow intensity
    lightCurve: 5,          // Glow falloff curve
    sizeScale: 0.2,         // Size scaling factor
    cursorRadius: 8         // Hover effect radius
  }}
  onAnimationComplete={() => console.log('Animation completed!')}
  style={{ margin: '20px' }}
  className="my-loader"
/>

Configuration Options

The config prop accepts a partial ShipfoxConfig object:

interface ShipfoxConfig {
  ghostOpacity: number;    // 0-1, transparency of unlit pixels
  lightRadius: number;     // 1-8, glow effect radius around head
  lightBrightness: number; // 0-1, maximum glow intensity
  lightCurve: number;      // 1-6, how fast glow fades with distance
  sizeScale: number;       // 0-1, how much size affects effects
  cursorRadius: number;    // 0.5-10, hover effect radius
}

Examples

Multiple Loaders

function MultipleLoaders() {
  return (
    <div>
      <ShipfoxLoader size={32} animation="random" />
      <ShipfoxLoader size={48} animation="vertical" />
      <ShipfoxLoader size={64} animation="circular" />
      <ShipfoxLoader size={80} animation="leftright" />
    </div>
  );
}

Controlled Animation

function ControlledLoader() {
  const [isPlaying, setIsPlaying] = useState(true);
  
  return (
    <div>
      <ShipfoxLoader
        autoPlay={isPlaying}
        showControls={true}
        onAnimationComplete={() => setIsPlaying(false)}
      />
      <button onClick={() => setIsPlaying(!isPlaying)}>
        {isPlaying ? 'Pause' : 'Play'}
      </button>
    </div>
  );
}

Custom Styling

<ShipfoxLoader
  size={100}
  style={{
    border: '2px solid #333',
    borderRadius: '10px',
    padding: '20px',
    backgroundColor: '#f0f0f0'
  }}
  className="custom-loader"
/>

Development

To run the example app:

cd example
npm install
npm start

To build the component:

npm run build

TypeScript

The component is written in TypeScript and includes full type definitions:

import ShipfoxLoader, { 
  ShipfoxLoaderProps, 
  AnimationType, 
  ColorMode, 
  BackgroundMode 
} from 'shipfox-loader-react';

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

License

MIT

Original Project

This React component is based on the original Shipfox Loader HTML implementation.