React Prize Wheel

A highly customizable, animated prize wheel component for React applications with TypeScript support.

Demo

Live Demo

Installation

npm install @mertercelik/react-prize-wheel

yarn add @mertercelik/react-prize-wheel

pnpm add @mertercelik/react-prize-wheel

Quick Start

import { useRef } from 'react';
import { PrizeWheel } from '@mertercelik/react-prize-wheel';
import type { Sector, PrizeWheelRef } from '@mertercelik/react-prize-wheel';
import '@mertercelik/react-prize-wheel/style.css';

function App() {
  const wheelRef = useRef<PrizeWheelRef>(null);

  const sectors: Sector[] = [
    { id: 1, label: 'Prize 1', probability: 10 },
    { id: 2, label: 'Prize 2', probability: 20 },
    { id: 3, label: 'Prize 3', probability: 15 },
    { id: 4, label: 'Prize 4', probability: 5 },
  ];

  const handleSpinEnd = (sector: Sector) => {
    console.log('Winner:', sector.label);
  };

  return (
    <div>
      <PrizeWheel
        ref={wheelRef}
        sectors={sectors}
        onSpinEnd={handleSpinEnd}
      />
      <button onClick={() => wheelRef.current?.spin()}>
        Spin the Wheel
      </button>
    </div>
  );
}

API Reference

PrizeWheel Component

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | sectors | Sector[] | required | Array of prize sectors | | onSpinStart | () => void | undefined | Callback fired when spin starts | | onSpinEnd | (sector: Sector) => void | undefined | Callback fired when spin ends with winning sector | | duration | number | 4 | Spin duration in seconds | | minSpins | number | 5 | Minimum number of full rotations | | maxSpins | number | 8 | Maximum number of full rotations |

Customization Props

Colors

| Prop | Type | Default | Description | |------|------|---------|-------------| | frameColor | string | '#ddd' | Outer frame color | | middleColor | string | '#ddd' | Center circle color | | middleDotColor | string | '#bbb' | Center dot color | | winIndicatorColor | string | '#ddd' | Win indicator arrow color | | winIndicatorDotColor | string | '#bbb' | Win indicator dot color | | sticksColor | string | '#ddd' | Divider sticks color | | wheelColors | [string, string] | ['#1592e8', '#14c187'] | Alternating sector colors | | borderColor | string | '#ddd' | Sector border color | | textColor | string | '#fff' | Sector text color |

Styling

| Prop | Type | Default | Description | |------|------|---------|-------------| | borderWidth | number | 2 | Sector border width in pixels | | textFontSize | number | 18 | Sector text font size in pixels |

Shadows

| Prop | Type | Default | Description | |------|------|---------|-------------| | wheelShadowColor | string | '#000' | Wheel shadow color | | wheelShadowOpacity | number | 0.15 | Wheel shadow opacity (0-1) | | middleShadowColor | string | '#000' | Middle circle shadow color | | middleShadowOpacity | number | 0.2 | Middle circle shadow opacity (0-1) | | indicatorShadowColor | string | '#000' | Indicator shadow color | | indicatorShadowOpacity | number | 0.22 | Indicator shadow opacity (0-1) |

Sector Interface

interface Sector {
  id: number | string;
  label: string;
  text?: string;
  probability?: number;
}

| Property | Type | Required | Description | |----------|------|----------|-------------| | id | number \| string | Yes | Unique identifier for the sector | | label | string | Yes | Label returned in callbacks | | text | string | No | Text displayed on the sector (defaults to label) | | probability | number | No | Relative probability weight (default: 10) |

Ref API

The component exposes a ref with the following methods and properties:

interface PrizeWheelRef {
  spin: () => void;
  isSpinning: boolean;
}

| Member | Type | Description | |--------|------|-------------| | spin | () => void | Programmatically trigger a spin | | isSpinning | boolean | Current spinning state |

Advanced Usage

Custom Button with State

import { useRef, useState } from 'react';
import { PrizeWheel } from '@mertercelik/react-prize-wheel';
import type { Sector, PrizeWheelRef } from '@mertercelik/react-prize-wheel';
import '@mertercelik/react-prize-wheel/style.css';

function App() {
  const wheelRef = useRef<PrizeWheelRef>(null);
  const [isSpinning, setIsSpinning] = useState(false);
  const [winner, setWinner] = useState<Sector | null>(null);

  const handleSpinStart = () => {
    setIsSpinning(true);
    setWinner(null);
  };

  const handleSpinEnd = (sector: Sector) => {
    setIsSpinning(false);
    setWinner(sector);
  };

  return (
    <div>
      <PrizeWheel
        ref={wheelRef}
        sectors={sectors}
        onSpinStart={handleSpinStart}
        onSpinEnd={handleSpinEnd}
      />
      <button 
        onClick={() => wheelRef.current?.spin()}
        disabled={isSpinning}
      >
        {isSpinning ? 'Spinning...' : 'Spin the Wheel'}
      </button>
      {winner && <p>Winner: {winner.label}</p>}
    </div>
  );
}

Probability System

The probability system uses relative weights. Higher values increase the chance of winning.

const sectors = [
  { id: 1, label: 'Common', probability: 50 },   // 50% chance
  { id: 2, label: 'Uncommon', probability: 30 }, // 30% chance
  { id: 3, label: 'Rare', probability: 15 },     // 15% chance
  { id: 4, label: 'Legendary', probability: 5 }, // 5% chance
];

Full Customization

<PrizeWheel
  ref={wheelRef}
  sectors={sectors}
  onSpinStart={handleSpinStart}
  onSpinEnd={handleSpinEnd}
  duration={6}
  minSpins={4}
  maxSpins={4}
  frameColor="#ffd700"
  middleColor="#ffd700"
  middleDotColor="#8b7500"
  winIndicatorColor="#ffd700"
  winIndicatorDotColor="#8b7500"
  sticksColor="#ffd700"
  wheelColors={['#0a1d3f', '#0a2249']}
  borderColor="#ffd700"
  borderWidth={3}
  textColor="#ffffff"
  textFontSize={20}
  wheelShadowColor="#000"
  wheelShadowOpacity={0.2}
  middleShadowColor="#000"
  middleShadowOpacity={0.25}
  indicatorShadowColor="#000"
  indicatorShadowOpacity={0.3}
/>

TypeScript

The package includes full TypeScript definitions. Import types as needed:

import type { 
  Sector, 
  PrizeWheelProps, 
  PrizeWheelRef 
} from '@mertercelik/react-prize-wheel';

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Dependencies

• React 18+
• GSAP 3+

Credits

The wheel SVG design is based on the work by Soma Szoboszlai.

License

MIT

Acknowledgments

• Wheel design inspiration: Soma Szoboszlai
• Animation library: GSAP

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

Support

For issues and feature requests, please use the GitHub issue tracker.